The optional attribute section consists of a pair of square brackets surrounding a comma-separated list of one or more attributes. An attribute consists of the attribute name followed by an optional list of positional or named arguments. The attribute may also contain an attribute target—that is, the entity to which the attribute applies.

[ClassDesc]

[ClassDesc(Author="Knuth", 0)]

[ClassDesc(Author="Knuth"), ClassDesc(Author="James")]

Description

Attributes provide a way to associate additional information with a target entity. In our discussion, the target is a newly created class; but attributes may also be associated with methods, fields, properties, parameters, structures, assemblies, and modules. Their simple definition belies a truly innovative and powerful programming tool. Consider the following:

• An attribute is an instance of a public class. As such, it has fields and properties that can be used to provide rich descriptive information about a target or targets.

• All compilers that target the Common Language Runtime (CLR) recognize attributes and store information about them in the module's metadata. This is an elegant way to attach information to a program entity that can affect its behavior without modifying its implementation code. An application can then use reflection (a set of types for reading metadata) to read the metadata at runtime and make decisions based on its value.

• Hundreds of predefined attributes are included in the .NET Framework Class Library (FCL). They are used heavily in dealing with interoperability issues such as accessing the Win32API or allowing .NET applications and COM objects to communicate. They also are used to control compiler operations. The[assembly:CLSComplianttrue)] attribute in Figure 3-1 tells the C# compiler to check the code for CLS compliance.

Core Note

Attributes provide a way to extend the metadata generated by the C# compiler with custom descriptive information about a class or class member.

.NET supports two types of attributes: custom attributes and standard attributes. Custom attributes are defined by the programmer. The compiler adds them to the metadata, but it's up to the programmer to write the reflection code that incorporates this metadata into the program. Standard attributes are part of the .NET Framework and recognized by the runtime and .NET compilers. The Flags attribute that was discussed in conjunction with enums in Chapter 2, “C# Language Fundamentals,” is an example of this; another is the conditional attribute, described next.

#define DEBUG
using System;
using System.Diagnostics;   // Required for conditional attrib.
public class AttributeTest
{
   [Conditional("TRACE")]
   public static void ListTrace()
   { Console.WriteLine("Trace is On"); }
   [Conditional("DEBUG")]
   public static void ListDebug()
   { Console.WriteLine("Debug is On"); }
}

#define TRACE
using System;
public class MyApp {
   static void Main()
   {
      Console.WriteLine("Testing Method Calls");
      AttributeTest.ListTrace();
      AttributeTest.ListDebug();
   }
}

Testing Method Calls
Trace is On

The primary role of modifiers is to designate the accessibility (also called scope or visibility) of types and type members. Specifically, a class access modifier indicates whether a class is accessible from other assemblies, the same assembly, a containing class, or classes derived from a containing class.

Core Note

A base class must be at least as accessible as its derived class. The following raises an error:

class  Furniture { }               // default access is internal
public class Sofa : Furniture { }  // error

The error occurs because the Furniture class (internal by default) is less accessible than the derived Sofa class. Errors such as this occur most frequently when a developer relies on a default modifer. This is one reason that modifiers should be included in a declaration.

In addition to the access modifiers, C# provides a dozen or so other modifiers for use with types and type members. Of these, three can be used with classes: abstract, sealed, and static.

This is the name assigned to the class. The ECMA standard recommends the following guidelines for naming the identifier:

This optional list contains a previously defined class or interface(s) from which a class may derive its behavior and capabilities. The new class is referred to as the derived class, and the class or interface from which it inherits is the base class or interface. A base class must be listed before any interface(s).

Example

// .. FCL Interface and user-defined base class
public interface System.Icomparable
   {Int32 CompareTo(Object object); }
class Furniture {  }
// .. Derived Classes
class Sofa: Furniture { ... }  // Inherits from one base class
// Following inherits from one base class and one interface.
class Recliner: Furniture, IComparable {...}

The C# language does not permit multiple class inheritance, thus the base list can contain only one class. Because there is no limit on the number of inherited interfaces, this serves to increase the role of interfaces in the .NET world.

Core Note

• Inheritance from a base class is referred to as implementation inheritance. The derived class inherits all of the members of the base class. However, the base class can prevent access to a member by defining it with the private modifier.

• Inheritance from an interface is referred to as interface inheritance because the interface does not provide implementation code. The derived class must provide the logic to implement any functions defined in the base interface(s).

The access modifiers used for a class declaration can also be applied to class members. They determine the classes and assemblies that have access to the class. Table 3-2 summarizes the scope of accessibility.

C# uses the const keyword to declare variables that have a fixed, unalterable value. Listing 3-1 provides an example of using constants. Although simple, the code illustrates several basic rules for defining and accessing constants.

using System;
class Conversions
{
   public const double Cm = 2.54;
   public const double Grams = 454.0 , km = .62 ;
   public const string ProjectName = "Metrics";
}
class ShowConversions
{
   static void Main()
   {
      double pounds, gramWeight;
      gramWeight = 1362;
      pounds = gramWeight / Conversions.Grams;
      Console.WriteLine(
         "{0} Grams= {1} Pounds", gramWeight,pounds);
      Console.WriteLine("Cm per inch {0}", Conversions.Cm);
      Conversions c= new Conversions();  // Create class
                                         // instance
      // This fails to compile. Cannot access const from object
      Console.WriteLine("Cm per inch {0}", c.Cm);
   }
}

The most important thing to recognize about a constant is that its value is determined at compile time. This can have important ramifications. For example, suppose the Furniture class in Figure 3-1 is contained in a DLL that is used by other assemblies as a source for the sales tax rate. If the rate changes, it would seem logical that assigning the new value to SalesTax and recompiling the DLL would then make the new value to external assemblies. However, the way .NET handles constants requires that all assemblies accessing the DLL must also be recompiled. The problem is that const types are evaluated at compile time.

When any calling routine is compiled against the DLL, the compiler locates all constant values in the DLL's metadata and hardcodes them in the executable code of the calling routine. This value is not changed until the calling routine is recompiled and reloads the value from the DLL. In cases such as tax, where a value is subject to change, it's preferable to define the value as a readonly field—sometimes referred to as a runtime constant.

Core Approach

It is often desirable to store a group of constants in a special utility or helper class. Declare them public to make them available to all classes. Because there is no need to create instances of the class, declare the class as abstract.

A field is also used to store data within a class. It differs from a const in two significant ways: Its value is determined at runtime, and its type is not restricted to primitives.

Field Modifiers

In addition to the access modifiers, fields have two additional modifiers: static and readonly (see Table 3-3).

Table 3-3. Field Modifiers

Modifier	Definition
static	The field is part of the class's state rather than any instances of the class. This means that it can be referenced directly (like a constant) by specifying classname.fieldname without creating an instance of the class.
readonly	The field can only be assigned a value in the declaration statement or class constructor. The net effect is to turn the field into a constant. An error results if code later attempts to change the value of the field.

As a rule of thumb, fields should be defined with the private attribute to ensure that the state of an object is safe from outside manipulation. Methods and properties should then be used to retrieve and set the private data if outside access is required.

Core Note

If a field is not initialized, it is set to the default value for its type: 0 for numbers, null for a reference type, single quotation marks ('') for a string, and false for boolean.

There is one case where setting a field to public makes sense: when your program requires a global constant value. By declaring a field to be public static readonly, you can create a runtime constant. For example, this declaration in Figure 3-1:

const double salesTax = .065;

can be replaced with a field

public static readonly double SalesTax = .065;

A method then references this field as Furniture.SalesTax, and the readonly modifier ensures the value cannot be changed. Note that if you create an instance of this class, you cannot access salesTax as a member of that instance. An attempt to do so results in the compile error “static member cannot be accessed with an instance reference”.

Furniture chair = new Furniture("Broyhill","12422",225.00);
double itemTax = chair.SalesTax;    // Raises an error

Upholstery.silk.FabCost(10);   // Value from method
Upholstery.silk.DeliveryTime;  // Value from property

public class Upholstery
{
   // fields to contain price and delivery time for fabrics
   public static readonly Upholstery silk =
      new Upholstery(15.00, 8);
   public static readonly Upholstery wool =
      new Upholstery(12.00, 6);
   public static readonly Upholstery cotton =
      new Upholstery(9.00, 6);
   private double yardPrice;
   private int deliveryWeeks;
   // constructor - set price per yard and delivery time
   // private modifier prevents external class instantiation
   private Upholstery ( double yrPrice, int delWeeks)
   {
      yardPrice = yrPrice;
      deliveryWeeks = delWeeks;
   }
   // method to return total cost of fabric
   public double FabCost(double yards)
   {
      return yards * this.yardPrice;
   }
   // property to return delivery time
   public int DeliveryTime
      {get { return deliveryWeeks;}}
   // property to return price per yard
   public double PricePerYard
      {get {return yardPrice;}}
}

A property is used to control read and write access to values within a class. Java and C++ programmers create properties by writing an accessor method to retrieve field data and a mutator method to set it. Unlike these languages, the C# compiler actually recognizes a special property construct and provides a simplified syntax for creating and accessing data. In truth, the syntax is not a whole lot different than a comparable C++ implementation, but it does allow the compiler to generate more efficient code.

Syntax:

[attributes] <modifier>   <data type>  <property name>
{
   [access modifier] get
   {  ...
      return(propertyvalue)
   }
   [access modifier] set
   {  ...  Code to set a field to the keyword value  }
}

Note:

public class  Upholstery
{
   private double yardPrice;
   // Property to return or set the price
   public double PricePerYard
   {
      get {return yardPrice;}   // Returns a property value
      set {                     // Sets a property value
         if ( value <= 0 )
            throw new ArgumentOutOfRangeException(
            "Price must be greater than 0.");
         yardPrice = value
      }
   }
   ...
}

The syntax for accessing the property of a class instance is the same as for a field:

// fabObj is instance of Upholstery class
double fabricPrice = fabObj.PricePerYard;
fabObj.PricePerYard = 12.50D;

The get block of code serves as a traditional accessor method and the set block as a mutator method. Only one is required. Leave out the get block to make the property write-only or the set block to make it read-only.

All return statements in the body of a get block must specify an expression that is implicitly convertible to the property type.

In this example, the code in the set block checks to ensure that the property is set to a value greater than 0. This capability to check for invalid data is a major argument in favor of encapsulating data in a property.

If you were to examine the underlying code generated for this example, you would find that C# actually creates a method for each get or set block. These names are created by adding the prefix get or set to the property name—for example, get_PricePerYard. In the unlikely case you attempt to create a method with the same name as the internal one, you will receive a compile-time error.

The use of properties is not necessarily any less efficient than exposing fields directly. For a non-virtual property that contains only a small amount of code, the JIT (Just-in-Time) compiler may replace calls to the accessor methods with the actual code contained in the get or set block. This process, known as inlining, reduces the overhead of making calls at runtime. The result is code that is as efficient as that for fields, but much more flexible.

An indexer is often referred to as a parameterized property. Like a property, it is declared within a class, and its body may contain get and set accessors that share the same syntax as property accessors. However, an indexer differs from a property in two significant ways: It accepts one or more parameters, and the keyword this is used as its name. Here is the formal syntax:

Syntax:

[attributes] <modifier><return type> this[parameter(s)]  {

Example:

public int this [int ndx] {

Note: The static modifier is not supported because indexers work only with instances.

In a nutshell, the indexer provides a way to access a collection of values maintained within a single class instance. The parameters passed to the indexer are used as a single- or multi-dimensional index to the collection. The example in Listing 3-4 should clarify the concept.

using System;
using System.Collections;  // Namespace containing ArrayList
public class  Upholstery
{
   // Class to represent upholstery fabric
   private double yardPrice;
   private int deliveryWeeks;
   private string fabName;
   // Constructor
   public Upholstery (double price, int delivery, string fabric)
   {
      this.yardPrice = price;
      this.deliveryWeeks = delivery;
      this.fabName = fabric;
   }
   // Three readonly properties to return Fabric information
   public int DeliveryTime
      {get {return deliveryWeeks;}}
   public double PricePerYard
      {get {return yardPrice;}}
   public string FabricName
      {get {return fabName;}}
}
public class Fabrics
{
   // Array to hold list of objects
   private ArrayList fabricArray = new ArrayList();
   // Indexer to add or return an object from the array
   public Upholstery this[int ndx]
   {
      get {
           if(!(ndx<0 || ndx > fabricArray.Count-1))
              return (Upholstery)fabricArray[ndx];
           // Return empty object
           else return(new Upholstery(0,0,""));
          }
           set { fabricArray.Insert(ndx, value);}
   }
}
public class IndexerApp
{
   public static void Main()
   {
      Fabrics sofaFabric = new Fabrics();
      // Use Indexer to create array of Objects
      sofaFabric[0] = new Upholstery(15.00, 8, "Silk");
      sofaFabric[1] = new Upholstery(12.00, 6, "Wool");
      sofaFabric[2] = new Upholstery(9.00, 6, "Cotton");
      // Next statement prints "Fabric: Silk"
      Console.WriteLine("Fabric: {0} ",
                        sofaFabric[0].FabricName);
   }
}

The Fabrics class contains an indexer that uses the get and set accessors to control access to an internal array of Upholstery objects. A single instance of the Fabrics class is created and assigned to sofaFabric. The indexer allows the internal array to be directly accessed by an index parameter passed to the object:

Fabrics sofaFabric = new Fabrics();
// Use Indexer to create array of Objects
sofaFabric[0] = new Upholstery(15.00, 8, "Silk");
sofaFabric[1] = new Upholstery(12.00, 6, "Wool");

The advantage of using an indexer is that it hides the array handling details from the client, and it can also perform any validation checking or data modification before returning a value. Indexers are best used with objects whose properties can be represented as a collection, rather than a scalar value. In this example, the various fabrics available for sofas form a collection. We could also use the indexer to create a collection of fabrics used for curtains:

Fabrics curtainFabric = new Fabrics();
curtainFabric[0] = new Upholstery(11.00, 4, "Cotton");
curtainFabric[1] = new Upholstery(7.00, 5, "Rayon");

In addition to the access modifiers, methods have seven additional modifiers shown in Table 3-4. Five of these—new, virtual, override, sealed, and abstract—provide a means for supporting polymorphism.

using System;
class Conversions
{
   // class contains functions to provide metric conversions
   private static double cmPerInch = 2.54;
   private static double gmPerPound = 455;
   public static double inchesToMetric(double inches) {
      return(inches * cmPerInch);
   }
   public static double poundsToGrams(double pounds) {
      return(pounds * gmPerPound);
   }
}
class Test
{
   static void Main() {
      double cm, grams;
      cm = Conversions.inchesToMetric(28.5);
      grams = Conversions.poundsToGrams(984.4);
   }
}

Method Inheritance with Virtual and Override Modifiers

Inheritance enables a program to create a new class that takes the form and functionality of an existing (base) class. The new class then adds code to distinguish its behavior from that of its base class. The capability of the subclass and base class to respond differently to the same message is classical polymorphism. In practical terms, this most often means that a base and derived class(es) provide different code for methods having the same signature.

By default, methods in the base class cannot be changed in the derived class. To overcome this, .NET provides the virtual modifier as a cue to the compiler that a method can be redefined in any class that inherits it. Similarly, the compiler requires that any derived class that alters a virtual method preface the method with the override modifier. Figure 3-2 and Listing 3-6 provide a simple illustration of this.

Example 3-6. Virtual Methods

using System;
class Fiber
{
   public  virtual string ShowMe() { return("Base");}
}
class Natural:Fiber
{
   public override string ShowMe() { return("Natural");}
}
class Cotton:Natural
{
   public override string ShowMe() { return("Cotton");}
}
class Test
{
   static void Main ()
   {
      Fiber fib1 = new Natural();  // Instance of Natural
      Fiber fib2 = new Cotton();   // Instance of Cotton
      string fibVal;
      fibVal = fib1.ShowMe();      // Returns "Natural"
      fibVal = fib2.ShowMe();      // Returns "Cotton"
   }
}

Figure 3-2. Relationship between base class and subclasses for Listing 3-6

In this example, Cotton is a subclass of Natural, which is itself a subclass of Fiber. Each subclass implements its own overriding code for the virtual method ShowMe.

fib1.ShowMe();    //returns  "Natural"
fib2.ShowMe();    //returns  "Cotton"

A subclass can inherit a virtual method without overriding it. If the Cotton class does not override ShowMe(), it uses the method defined in its base class Natural. In that case, the call to fib2.ShowMe() would return “Natural”.

public class Fiber
{
   public string ShowMe()        {return("Base");}
   public virtual string GetID() {return("BaseID");}
}
public class Natural:Fiber
{
   // Hide Inherited version of ShowMe
   new public string ShowMe()     {return("Natural");}
   public override string GetID() {return("NaturalID");}
   }
public class Cotton:Natural
{  // Inherits two methods: ShowMe() and GetID()
}

class A {
   public virtual void PrintID{....}
}
class B: A {
   sealed override public void PrintID{...}
}
class C:B {
   // This is illegal because it is sealed in B.
   override public void PrintID{...}
}

By default, method parameters are passed by value, which means that a copy of the parameter's data—rather than the actual data—is passed to the method. Consequently, any change the target method makes to these copies does not affect the original parameters in the calling routine. If the parameter is a reference type, such as an instance of a class, a reference to the object is passed. This enables a called method to change or set a parameter value.

C# provides two modifiers that signify a parameter is being passed by reference: out and ref. Both of these keywords cause the address of the parameter to be passed to the target method. The one you use depends on whether the parameter is initialized by the calling or called method. Use ref when the calling method initializes the parameter value, and out when the called method assigns the initial value. By requiring these keywords, C# improves code readability by forcing the programmer to explicitly identify whether the called method is to modify or initialize the parameter.

The code in Listing 3-8 demonstrates the use of these modifiers.

class TestParms
{
   public static void FillArray(out double[] prices)
   {
      prices = new double[4] {50.00,80.00,120.00,200.00};
   }
   public static void UpdateArray(ref double[] prices)
   {
      prices[0] = prices[0] * 1.50;
      prices[1] = prices[1] * 2.0;
   }
   public static double TaxVal(double ourPrice,
                               out double taxAmt)
   {
      double totVal = 1.10 * ourPrice;
      taxAmt = totVal – ourPrice;
      ourPrice = 0.0;  // Does not affect calling parameter
      return totVal;
   }
}
class MyApp
{
   public static void Main()
   {
      double[] priceArray;
      double taxAmt;
      //   (1) Call method to initialize array
      TestParms.FillArray(out priceArray);
      Console.WriteLine( priceArray[1].ToString());  // 80
      //   (2) Call method to update array
      TestParms.UpdateArray(ref priceArray);
      Console.WriteLine( priceArray[1].ToString());  // 160
      //   (3) Call method to calculate amount of tax.
      double ourPrice = 150.00;
      double newtax = TestParms.TaxVal(ourPrice, out taxAmt);
      Console.WriteLine( taxAmt.ToString());  // 15
      Console.WriteLine( ourPrice);           // 150.00
   }
}

In this example, the class MyApp is used to invoke three methods in the TestParms class:

C# includes one other parameter modifier, params, which is used to pass a variable number of arguments to a method. Basically, the compiler maps the variable number of arguments in the method invocation into a single parameter in the target method. To illustrate, let's consider a method that calculates the average for a list of numbers passed to it:

// Calculate average of variable number of arguments
public static double GetAvg(params double[] list)
{
   double tot = 0.0;
   for (int i = 0 ; i < list.Length; i++)
      tot += list[i];
   return tot / list.Length;
}

Except for the params modifier, the code for this method is no different than that used to receive an array. Rather than sending an array, however, the invoking code passes an actual list of arguments:

double avg;
avg = TestParms.GetAvg(12,15, 22, 5, 7 ,19);
avg = TestParms.GetAvg(100.50, 200, 300, 55,88,99,45);

When the compiler sees these method calls, it emits code that creates an array, populates it with the arguments, and passes it to the method. The params modifier is essentially a syntactical shortcut to avoid the explicit process of setting up and passing an array.

Core Note

The params keyword can only be used with the last parameter to a method.

Syntax

[attributes] [modifiers]  <identifier> ( [parameter-list])
[:initializer] { constructor-body}

The syntax is the same as that of the method except that it does not have a return data type and adds an initializer option. There are a number of implementation and behavioral differences:

The instance constructor is called as part of creating a class instance. Because a class may contain multiple constructors, the compiler calls the constructor whose signature matches that of the call:

Fiber fib1 = new Cotton();
Fiber fib1 = new Cotton("Egyptian");

.NET constructs an object by allocating memory, zeroing out the memory, and calling the instance constructor. The constructor sets the state of the object. Any fields in the class that are not explicitly initialized are set to zero or null, depending on the associated member type.

public class Apparel
{
   private string color;
   private decimal price;
   // constructor
   public Apparel(string c, decimal p, string b)
   {
      color = c;
      price = p;
   }
}
// class inheriting from Apparel
class Coat: Apparel
{
   private string length;
   public Coat(string c, decimal p, string b, string l)
   {
      length = l;
      // ... other code
   }
}

using System;
public  class Apparel
{
   private string color;
   private decimal price;
   private string brand;
   // Constructor
   public Apparel(string c,decimal p, string b)
   {
      color = c;
      price = p;
      brand = b;
   }

   public string ItemColor
   {
      get {return color;}
   }
   //  other properties and members go here
}

public class Shirt: Apparel
{
   private decimal mySleeve;
   private decimal myCollar;
   public Shirt (string c, decimal p, string b,
      decimal sleeve, decimal collar)  : base(c,p,b)
   {
      mySleeve = sleeve;
      myCollar = collar;
   }
}
public class TestClass
{
   static void Main()
   {
      Shirt shirtClass = new Shirt("white", 15.00m, "Arrow",
                                   32.0m, 15.5m);
      Console.WriteLine(shirtClass.ItemColor);  // "white"
   }
}

public class Natural
{
   string fiberType = "Generic";
   string color = "white";
   // Constructors
   public Natural() { ... }
   public Natural(string cotton_type) { ... }
   public Natural(string cotton_type, string color) { ... }
}

public Natural() {   // constructor initializes fields
    fiberType="Generic";
    color = "white";
}
// Following constructors use this() to call default
// constructor before constructor body is executed.
public Natural(string cotton_type): this() { ... }
public Natural(string cotton_type, string color):
   this() { ... }

Recall that the private modifier makes a class member inaccessible outside its class. When applied to a class constructor, it prevents outside classes from creating instances of that class. Although somewhat non-intuitive (what good is a class that cannot be instantiated?), this turns out to be a surprisingly powerful feature.

Its most obvious use is with classes that provide functionality solely through static methods and fields. A classic example is the System.Math class found in the Framework Class Library.

It has two static fields, pi and the e (natural logarithmic base), as well as several methods that return trigonometric values. The methods behave as built-in functions, and there is no reason for a program to create an instance of the math class in order to use them.

In the earlier discussion of static methods, we presented a class (refer to Listing 3-5) that performs metric conversions. Listing 3-10 shows this class with the private constructor added.

using System;
class Conversions
{
   // class contains functions to provide metric conversions
   // static method can only work with static field.
   static cmPerInch = 2.54;
   private static double gmPerPound = 455;
   public static double inchesToMetric(double inches) {
      return(inches * cmPerInch);
   }
   public static double poundsToGrams(double pounds) {
      return(pounds*gmPerPound);
   }
   // Private constructor prevents creating class instance
   private Conversions()
   { ...   }
}

Although a simple example, this illustrates a class that does not require instantiation: The methods are static, and there is no state information that would be associated with an instance of the class.

A natural question that arises is whether it is better to use the private constructor or an abstract class to prevent instantiation. The answer lies in understanding the differences between the two. First, consider inheritance. Although an abstract class cannot be instantiated, its true purpose is to serve as a base for derived classes (that can be instantiated) to create their own implementation. A class employing a private constructor is not meant to be inherited, nor can it be. Secondly, recall that a private constructor only prevents outside classes from instantiating; it does not prevent an instance of the class from being created within the class itself.

The traits of the private constructor can also be applied to managing object creation. Although the private constructor prevents an outside method from instantiating its class, it does allow a public method in the class (sometimes called a factory method) to create an object. This means that a class can create instances of itself, control how the outside world accesses them, and control the number of instances created. This topic is discussed in Chapter 4, “Working with Objects in C#.”

Also known as a class or type constructor, the static constructor is executed after the type is loaded and before any one of the type members is accessed. Its primary purpose is to initialize static class members. This limited role results from the many restrictions that distinguish it from the instance constructor:

Although it does not have a parameter, do not confuse it with a default base constructor, which must be an instance constructor. The following code illustrates the interplay between the static and instance constructors.

class BaseClass
{
   private static int callCounter;
   //  Static constructor
   static BaseClass(){
      Console.WriteLine("Static Constructor: "+callCounter);
   }
   //  Instance constructors
   public BaseClass()
   {
      callCounter+= 1;
      Console.WriteLine("Instance Constructor: "+callCounter);
   }
   // ... Other class operations
}

This class contains a static initializer, a static constructor, and an instance constructor. Let's look at the sequence of events that occur when the class is instantiated:

BaseClass myClass1 = new BaseClass();
BaseClass myClass2 = new BaseClass();
BaseClass myClass2 = new BaseClass();

Output:

Static Constructor: 0
Instance Constructor: 1
Instance Constructor: 2
Instance Constructor: 3

The compiler first emits code to initialize the static field to 0; it then executes the static constructor code that displays the initial value of callCounter. Next, the base constructor is executed. It increments the counter and displays its current value, which is now 1. Each time a new instance of BaseClass is created, the counter is incremented. Note that the static constructor is executed only once, no matter how many instances of the class are created.

Connecting an event to the handling method(s) is a delegate object. This object maintains a list of methods that it calls when an event occurs. Its role is similar to that of the callback functions that Windows API programmers are used to, but it represents a considerable improvement in safeguarding code.

In Microsoft Windows programming, a callback occurs when a function calls another function using a function pointer it receives. The calling function has no way of knowing whether the address actually refers to a valid function. As a result, program errors and crashes often occur due to bad memory references. The .NET delegate eliminates this problem. The C# compiler performs type checking to ensure that a delegate only calls methods that have a signature and return type matching that specified in the delegate declaration. As an example, consider this delegate declaration:

public delegate void MyString (string msg);

When the delegate is declared, the C# compiler creates a sealed class having the name of the delegate identifier (MyString). This class defines a constructor that accepts the name of a method—static or instance—as one of its parameters. It also contains methods that enable the delegate to maintain a list of target methods. This means that—unlike the callback approach—a single delegate can call multiple event handling methods.

A method must be registered with a delegate for it to be called by that delegate. Only methods that return no value and accept a single string parameter can be registered with this delegate; otherwise, a compilation error occurs. Listing 3-11 shows how to declare the MyString delegate and register multiple methods with it. When the delegate is called, it loops through its internal invocation list and calls all the registered methods in the order they were registered. The process of calling multiple methods is referred to as multicasting.

// file: delegate.cs
using System;
using System.Threading;
class DelegateSample
{
   public delegate void MyString(string s);
   public static void PrintLower(string s){
      Console.WriteLine(s.ToLower());
   }

   public static void PrintUpper(string s){
      Console.WriteLine(s.ToUpper());
   }

   public static void Main()
   {
      MyString myDel;
      // register method to be called by delegate
      myDel =  new MyString(PrintLower);
      // register second method
      myDel += new MyString(PrintUpper);
      // call delegate
      myDel("My Name is Violetta.");
      // Output: my name is violetta.
      //         MY NAME IS VIOLETTA.
   }
}

Note that the += operator is used to add a method to the invocation list. Conversely, a method can be removed using the -= operator:

myDel += new MyString(PrintUpper); // register for callback
myDel -= new MyString(PrintUpper); // remove method from list

In the preceding example, the delegate calls each method synchronously, which means that each succeeding method is called only after the preceding method has completed operation. There are two potential problems with this: a method could “hang up” and never return control, or a method could simply take a long time to process—blocking the entire application. To remedy this, .NET allows delegates to make asynchronous calls to methods. When this occurs, the called method runs on a separate thread than the calling method. The calling method can then determine when the invoked method has completed its task by polling it, or having it call back a method when it is completed. Asynchronous calls are discussed in Chapter 13, “Asynchronous Programming and Multithreading.”

In abstract terms, the .NET event model is based on the Observer Design Pattern. This pattern is defined as “a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.”^[1] We can modify this definition to describe the .NET event handling model depicted in Figure 3-3: “when an event occurs, all the delegate's registered methods are notified and executed automatically.” An understanding of how events and delegates work together is the key to handling events properly in .NET.

To illustrate, let's look at two examples. We'll begin with built-in events that have a predefined delegate. Then, we'll examine how to create events and delegates for a custom class.

this.MouseDown += new MouseEventHandler(OnMouseDown);

this.event += new delegate(event handler method);

public delegate void MouseEventHandler(
   object sender,
   MouseEventArgs e)

using System;
using System.Windows.Forms;
using System.Drawing;
class DrawingForm:Form
{
   private int lastX;
   private int lastY;
   private Pen myPen= Pens.Black; // defines color of drawn line
   public DrawingForm() {
      this.Text = "Drawing Pad";
      // Create delegates to call MouseUp and MouseDown
      this.MouseDown += new MouseEventHandler(OnMouseDown);
      this.MouseUp   += new MouseEventHandler(OnMouseUp);
   }
   private void OnMouseDown(object sender, MouseEventArgs e)
   {
      lastX = e.X;
      lastY = e.Y;
   }
   private void OnMouseUp(object sender, MouseEventArgs e)
   {
      // The next two statements draw a line on the form
      Graphics g = this.CreateGraphics();
      if (lastX >0 ){
         g.DrawLine(myPen, lastX,lastY,e.X,e.Y);
      }
      lastX = e.X;
      lastY = e.Y;
   }
   static void Main() {
      Application.Run(new DrawingForm());
   }
}

this.MouseDown += new MouseEventHandler(OnMouseDown);

this.MouseDown += delegate(object sender, EventArgs e)
{
   lastX = e.X;
   lastY = e.Y;
}

delegate [(parameter-list)] {anonymous-method-block}

// delegate declaration
public delegate void MyString(string s);

// Register two anonymous methods with the delegate
MyString myDel;
myDel =  delegate(string s) { Console.WriteLine(s.ToLower()); };
myDel += delegate(string s) { Console.WriteLine(s.ToUpper()); };
// invoke delegate
myDel("My name is Violetta");

public event  <delegate name>  <event name>

public class IOMonitor
{
   // Declare delegate
   public delegate void IODelegate(String s);
   // Define event variable
   public event IODelegate DataReceived ;
   // Fire the event
   public void FireReceivedEvent (string msg)
   {
      if (DataReceived != null)  // Always check for null
      {
         DataReceived(msg);      // Invoke callbacks
      }
   }
}

IOMonitor monitor = new IOMonitor();
// You must provide a method that handles the callback
monitor.DataReceived += new IODelegate(callback method);
monitor.FireReceivedEvent("Buffer Full");  // Fire event

Defining a Delegate to Work with Events

In the preceding example, the event delegate defines a method signature that takes a single string parameter. This helps simplify the example, but in practice, the signature should conform to that used by all built-in .NET delegates. The EventHandler delegate provides an example of the signature that should be used:

public delegate void EventHandler(object sender,
                                  EventArgs eventArgs);

The delegate signature should define a void return type, and have an object and EventArgs type parameter. The sender parameter identifies the publisher of the event; this enables a client to use a single method to handle and identify an event that may originate from multiple sources.

The second parameter contains the data associated with the event. .NET provides the EventArgs class as a generic container to hold a list of arguments. This offers several advantages, the most important being that it decouples the event handler method from the event publisher. For example, new arguments can be added later to the EventArgs container without affecting existing subscribers.

Creating an EventArgs type to be used as a parameter requires defining a new class that inherits from EventArgs. Here is an example that contains a single string property. The value of this property is set prior to firing the event in which it is included as a parameter.

public class IOEventArgs: EventArgs
{
   public IOEventArgs(string msg){
      this.eventMsg = msg;
   }
   public string Msg{
      get {return eventMsg;}
   }
   private string eventMsg;
}

IOEventArgs illustrates the guidelines to follow when defining an EventArgs class:

• It must inherit from the EventArgs class.

• Its name should end with EventArgs.

• Define the arguments as readonly fields or properties.

• Use a constructor to initialize the values.

If an event does not generate data, there is no need to create a class to serve as the EventArgs parameter. Instead, simply pass EventArgs.Empty.

Core Note

If your delegate uses the EventHandler signature, you can use EventHandler as your delegate instead of creating your own. Because it is part of the .NET Framework Class Library, there is no need to declare it.

//File: stocktrader.cs
using System;
// (1) Declare delegate
public delegate void TraderDelegate(object sender,
                                    EventArgs e);
// (2) A class to define the arguments passed to the delegate
public class TraderEventArgs: EventArgs
{
   public TraderEventArgs(int shs, decimal prc, string msg,
                          string sym){
      this.tradeMsg   = msg;
      this.tradeprice = prc;
      this.tradeshs   = shs;
      this.tradesym   = sym;
   }
   public string Desc{
      get {return tradeMsg;}
   }
   public decimal SalesPrice{
      get {return tradeprice;}
   }
   public int Shares{
      get {return tradeshs;}
   }
   public string Symbol{
       get {return tradesym;}
   }

   private string  tradeMsg;
   private decimal tradeprice;
   private int tradeshs;
   private string tradesym;
}
// (3) class defining event handling methods
public class EventHandlerClass
{
   public void HandleStockSale(object sender,EventArgs e)
   {
      // do housekeeping for stock purchase
      TraderEventArgs ev = (TraderEventArgs) e;
      decimal totSale = (decimal)(ev.Shares * ev.SalesPrice);
      Console.WriteLine(ev.Desc);
   }
   public void LogTransaction(object sender,EventArgs e)
   {
      TraderEventArgs ev = (TraderEventArgs) e;
      Console.WriteLine(ev.Symbol+" "+ev.Shares.ToString()
                        +" "+ev.SalesPrice.ToString("###.##"));
   }
}
// (4) Class to sell stock and publish stock sold event
public class Seller
{
   // Define event indicating a stock sale
   public event TraderDelegate StockSold;
   public void StartUp(string sym, int shs, decimal curr)
   {
      decimal salePrice= GetSalePrice(curr);
      TraderEventArgs t = new TraderEventArgs(shs,salePrice,
            sym+" Sold at "+salePrice.ToString("###.##"), sym);
      FireSellEvent(t);  // Fire event
   }
   // method to return price at which stock is sold
   // this simulates a random price movement from current price
   private decimal GetSalePrice(decimal curr)
   {
      Random rNum = new Random();
      // returns random number between 0 and 1
      decimal rndSale = (decimal)rNum.NextDouble() * 4;
      decimal salePrice= curr - 2 + rndSale;
      return salePrice;
   }
   private void FireSellEvent(EventArgs e)
   {
      if (StockSold != null)  // Publish defensively
      {
         StockSold(this, e);  // Invoke callbacks by delegate
      }
   }
}

class MyApp
{
   public static void Main()
   {
      EventHandlerClass eClass= new EventHandlerClass();
      Seller sell = new Seller();
      // Register two event handlers for stocksold event
      sell.StockSold += new TraderDelegate(
                    eClass.HandleStockSale);
      sell.StockSold += new TraderDelegate(
                    eClass.LogTransaction);
      // Invoke method to sell stock(symbol, curr price,
                                     sell price)
      sell.StartUp("HPQ",100, 26);
   }
}

Listing 3-15 demonstrates how to define, implement, and program against a simple custom interface:

public interface IShapeFunction
{
   double GetArea();    //  public abstract method
}

class Circle : IShapeFunction   // Inherit Interface
{
   private double radius;
   public circle( double rad)
   {
      radius = rad;
   }
   public double GetArea()
   {
      return ( Math.PI*radius * radius);
   }
   public string ShowMe()
   {
      return ("Circle");
   }
}

class Rectangle: IShapeFunction      // Inherit interface
{
   private double width, height;
   public rectangle( double myWidth, double myHeight)
   {
      width= myWidth;
      height= myHeight;
   }
   public double GetArea()
   {
      return (width * height);
   }
}
class MyApp
{
   public static void Main()
   {
      Circle myCircle = new Circle(4);
      // Interface variable that references a circle object.
      IShapeFunction myICircle = myCircle;
      Rectangle myRectangle = new Rectangle(4,8);
      // Place shape instances in an array
      IShapeFunction[] myShapes = {myCircle, myRectangle};
      // The next two statements print the same results
      MessageBox.Show(myCircle.GetArea().ToString());
      MessageBox.Show(myShapes[0].GetArea().ToString());
      MessageBox.Show(myCircle.ShowMe());   // class method
      MessageBox.Show(myICircle.GetArea().ToString());
      // The following will not compile because myICircle can
      // access only members of the IShapeFunction interface.
      MessageBox.Show(myICircle.ShowMe());
   }
}

The declaration of the interface and implementation of the classes is straightforward: A Circle and Rectangle class inherit the IShapeFunction interface and implement its GetArea method.

Conceptually, it is useful to think of a class that implements one or more interfaces as having multiple types. It has its own innate type, but it also can be viewed as having the type of each interface it implements. Consider this code in the MyApp class:

Circle myCircle = new Circle(4);
IShapeFunction myICircle = myCircle;

The first statement creates an instance of the Circle class. The second statement creates a variable that refers to this circle object. However, because it is specified as an IShapeFunction type, it can only access members of that interface. This is why an attempt to reference the ShowMe method fails. By using the interface type, you effectively create a filter that restricts access to members of the interface only.

One of the most valuable aspects of working with interfaces is that a programmer can treat disparate classes in a similar manner, as long at they implement the same interface.

IShapeFunction[] myShapes = {myCircle, myRectangle};
MessageBox.Show(myShapes[0].GetArea().ToString());

This code creates an array that can contain any class that implements the IShapeFunction interface. Its only interest is in using the GetArea method, and it neither has nor requires any knowledge of other class members. We can easily extend this example to create a class to work with this array that has no knowledge of the Circle or Rectangle class.

public class ShapeUtil
{
   public static double SumAreas
         (IShapeFunction[] funArray)
   {
      double tot = 0.0;
      for (int i = 0; i < funArray.Length; i++)
         { tot += funArray[i].GetArea();  }
      return tot;
   }
}
// Access this method with ShapeUtil.SumAreas(myShapes);

The code in this class can be used with any concrete class that implements the IShapeFunction interface.

Core Approach

For maximum program flexibility, consider using interface types, rather than class types, when defining method parameters. This ensures there is no limit on the types of classes that can be passed to the method, as long as they implement the required interface.

Syntax:

[attribute][modifier] struct identifier [:interfaces]
{struct-body}

Example:

public struct DressShirt
{
   public float CollarSz;
   public int SleeveLn;
   // constructor
   public DressShirt(float collar, int sleeve)
   {
      this.CollarSz = collar;
      this.SleeveLn = sleeve;
   }
}

The syntax clearly resembles a class. In fact, replace struct with class and the code compiles. It has a public modifier that permits access from any assembly. The default modifier is internal, which restricts access to the containing assembly. No interfaces are specified—although a struct can inherit from an interface—so the struct is not required to implement any specific methods.

Core Note

It is possible to specify the layout of a struct's fields in memory using the StructLayout attribute. This is most commonly used when the struct is to be accessed by unmanaged code that expects a specific physical layout of the data. By default, the fields in a struct are stored in sequential memory locations.

An instance of the structure can be created in two ways:

DressShirt dShirt = new DressShirt(16, 33);
DressShirt myShirt = new DressShirt();
myShirt.CollarSz = 16.5F;
myShirt.SleeveLn = 33;

The first statement creates an instance that relies on the user-defined constructor to initialize the field values. When designing such a constructor, be aware that you must initialize all fields within the constructor; otherwise, the compiler will issue an error.

The second statement also creates an instance of the struct by calling the default constructor, which initializes the fields to default values of zero (0). Note the difference here between a struct and a class: A struct always has a default parameterless constructor; a class has the default parameterless constructor only if there are no explicitly defined constructors.

Methods and properties are usually associated with classes, but they play an equally important role in the use of structures. In fact, a client accessing a method has no syntactical clue as to whether the method or property is associated with a class or struct. Listing 3-17 extends the original example to add two properties and a method.

public struct DressShirt
{
   private float CollarSz;
   private int SleeveLn;
   public DressShirt(float collar, int sleeve)
   {
      this.CollarSz = collar;
      this.SleeveLn = sleeve;
   }

   // Properties to return sleeve and collar values
   public int Sleeve
   {
      get {return (SleeveLn);}
      set {SleeveLn = value;}
   }
   public float Collar
   {
      get {return (CollarSz); }
      // "value" is an implicit parameter
      set {CollarSz = value;   }
   }

   // Method to convert size to different scale
   public string ShirtSize()
   {
      string mySize = "S";
      if (CollarSz > 14.5) mySize = "M";
      if (CollarSz > 15.5) mySize = "L";
      if (CollarSz > 16.5) mySize = "XL";
      return (mySize);
   }
}

The most important thing to note about this code is that it could be cut and pasted into a class and run with no changes. Although a struct doesn't support all of the features of a class, the ones it does are implemented using identical syntax.

As mentioned, classes are allocated space from the managed heap when the object or class instance is created. The address of the object (on the heap) is returned to the variable representing the object. In contrast, a variable set to a struct type contains the structure's actual data—not a pointer. The ramifications of this are most pronounced when passing arguments to functions. Reference types simply require that a pointer be passed, whereas structures require that a copy of all fields be made and passed to the function.

The structure does have some advantages with regard to memory allocation and Garbage Collection. Structure instances are allocated in a thread's stack rather than the managed heap, thus avoiding the associated overhead of managing pointers. Memory management is also simpler. When a copy of a structure is no longer reachable, its memory is collected and made available. In contrast, classes often require special code to handle unmanaged resources or invoke the system's garbage collection routine. Garbage Collection is covered in the next chapter.

This is a departure from C++ conventions that permit a class to use an existing structure as a base class and permit a structure to use a class as a base. Is the .NET lack of support for this a step backward? Not really. It better delineates the role of the structure versus the class—making the structure less of a pseudo-class and more of a data structure. In addition, it provides for a more efficient implementation of the structure. The restriction enables the compiler to minimize the amount of administrative code that would be required to support inheritance. For example, because the compiler knows that a structure's methods cannot be overridden by subclasses, it can optimize the method invocation by expanding the method code inline rather than executing a method call.

The easiest way to make the choice is to compare the features of the type that you are designing with the following checklist. If any of these are true, you should use a class.