The code inside the try block is referred to as a guarded region because it has associated catch or finally blocks to handle possible exceptions or cleanup duties. Each try block must have at least one accompanying catch or finally block.

A catch block consists of the keyword catch followed by an expression in parentheses called the exception filter that indicates the type of exception to which it responds. Following this is the code body that implements the response.

The exception filter identifies the exception it handles and also serves as a parameter when an exception is thrown to it. Consider the following statement:

catch (DivideByZeroException ex)  {  ... }

The filter will be invoked if a System.DivideByZeroException occurs. The variable ex references the exception and provides access to its properties, such as ex.Message and ex.StackTrace.

When using multiple catch blocks, ordering is important. They should be listed hierarchically, beginning with the most specific exceptions and ending with the more general ones. In fact, the compiler generates an error if you do not order them correctly.

catch (DivideByZeroException ex)  {  ... }
catch (IndexOutOfRangeException ex) { ... }
catch (Exception ex)  {  ... }

This codes first looks for specific exceptions such as a division by zero or an index out of range. The final exception filter, Exception, catches any exception derived from System.Exception. When an exception is caught, the code in the block is executed and all other catch blocks are skipped. Control then flows to the finally block—if one exists.

Note that the catch block may include a throw statement to pass the exception further up the call stack to the previous caller. The throw statement has an optional parameter placed in parentheses that can be used to identify the type of exception being thrown. If throw is used without a parameter, it throws the exception caught by the current block. You typically throw an exception when the calling method is better suited to handle it.

Regarded as the “cleanup” block, the finally block is executed whether or not an exception occurs and is a convenient place to perform any cleanup operations such as closing files or database connections. This block must be included if there are no catch blocks; otherwise, it is optional.

Event handling was discussed in the previous chapter along with the important role of delegates. We can now use those techniques to register our own callback method that processes any unhandled exceptions thrown in the Windows application.

When an exception occurs in Windows, the application's OnThreadException method is ultimately called. It displays a dialog box describing the unhandled exception. You can override this by creating and registering your own method that matches the signature of the System.Threading.ThreadExceptionEventHandler delegate. Listing 4-4 shows one way this can be implemented.

MyUnhandledMethod is defined to handle the exception and must be registered to receive the callback. The following code registers the method for the ThreadException event using the ThreadExceptionEventHandler delegate and runs the application:

static void Main()
{
   Application.ThreadException += new
      ThreadExceptionEventHandler(UnForgiven.MyUnhandledMethod);
   Application.Run(new Form1());
}

The implementation code in the method is straightforward. The most interesting aspect is the use of preprocessor directives (#if DEBUG) to execute code based on whether the application is in release or debug mode.

// Class to receive callback to process unhandled exceptions
using System.Diagnostics;
using System.Windows.Forms;
using System.Threading;
public class UnForgiven
{
   // Class signature matches ThreadExceptionEventHandler
   public static void MyUnhandledMethod
      (object sender, ThreadExceptionEventArgs e)
   {
#if DEBUG
   // Statements for debug mode
   // Display trace and start the Debugger
   MessageBox.Show("Debug: "+e.ToString());
#else
   // Statements for release mode
   // Provide output to user and log errors
   MessageBox.Show("Release: "+e.ToString());
#endif
   }
}

For a Console application, the same approach is used except that the delegate and event names are different. You would register the method with the following:

Thread.GetDomain().UnhandledException += new
   UnhandledExceptionEventHandler(
      UnForgiven.MyUnhandledMethodAp);

Also, the method's EventArgs parameter changes to UnhandledExceptionEventArgs.

The GetHashCode method generates an Int32 hash code value for any object. This value serves as an identifier that can be used to place any object in a hash table collection. The Framework designers decreed that any two objects that are equal must have the same hash code. As a result, any new Equals method must be paired with a GetHashCode method to ensure that identical objects generate the same hash code value.

Ideally, the hash code values generated over the range of objects represent a wide distribution. This example used a simple algorithm that calls the base type's GetHashCode method to return a value based on the item's ID. This is a good choice because the IDs are unique for each item, the ID is an instance field, and the ID field value is immutable—being set only in the constructor.

After you override the original Equals method to compare object values, your application may still need to determine if reference variables refer to the same object. System.Object has a static method called ReferenceEquals for this purpose. It is used here with our Chair class:

Chair chair1 = new Chair(120.0, "Broyhill", "66-9888") )
Chair chair2 = new Chair(120.0, "Broyhill", "66-9933") )
Chair chair3 = chair1;
if (Object.ReferenceEquals(chair1, chair3) )
   { MessageBox.Show("Same object");}
else
   { MessageBox.Show("Different objects");}

The method returns true because chair1 and chair3 reference the same instance.

A shallow copy is sufficient when the object to be copied contains no reference type fields needed by the copy. The easiest way to implement shallow copying is to use the System.Object.MemberwiseClone method, a protected, non-virtual method that makes a shallow copy of the object it is associated with. We use this to enable the Chair class to clone itself:

public class Chair: ICloneable
{
   //... other code from Listing 4-5
   public Object Clone()
   {
      return MemberwiseClone(); // from System.Object
   }

The only requirements are that the class inherit the ICloneable interface and implement the Clone method using MemberwiseClone. To demonstrate, let's use this code segment to create a shallow copy clone of myChair by calling its Clone method:

// Make clone of myChair
Chair chairClone = (Chair)myChair.Clone();
bool isEqual;
// (1) Following evaluates to false
isEqual = Object.ReferenceEquals(myChair,chairClone);
// (2) Following evaluates to true
isEqual = Object.ReferenceEquals(
          myChair.myUpholstery,chairClone.myUpholstery);

The results confirm this is a shallow copy: The reference comparison of myChair and its clone fails because chairClone is created as a copy of the original object; on the other hand, the comparison of the reference field myUpholstery succeeds because the original and clone objects point to the same instance of the myUpholstery class.

This interface provides the minimal information that a collection must implement. All classes in the System.Collections namespace inherit it (see Table 4-3).

The IsSynchronized and SyncRoot properties require explanation if you are not yet familiar with threading (discussed in Chapter 13, “Asynchronous Programming and Multithreading”). Briefly, their purpose is to ensure the integrity of data in a collection while it is being accessed by multiple clients. It's analogous to locking records in a database to prevent conflicting updates by multiple users.

This interface has one member—the GetHashCode method—that uses a custom hash function to return a hash code value for an object. The Hashtable class uses this interface as a parameter type in one of its overloaded constructors, but other than that you will rarely see it.

For a class to support iteration using the foreach construct, it must implement the IEnumerable and IEnumerator interfaces. IEnumerator defines the methods and properties used to implement the enumerator pattern; IEnumerable serves only to return an IEnumerator object. Table 4-4 summarizes the member(s) provided by each interface.

These members are implemented in a custom collection class as a way to enable users to traverse the objects in the collection. To understand how to use these members, let's look at the underlying code that implements the foreach construct.

The foreach loop offers a simple syntax:

foreach ( ElementType element in collection)
{
   Console.WriteLine(element.Name);
}

The compiler expands the foreach construct into a while loop that employs IEnumerable and IEnumerator members:

// Get enumerator object using collection's GetEnumerator method
IEnumerator enumerator =
         ((IEnumerable) (collection)).GetEnumerator();
try
{
   while (enumerator.MoveNext())
   {
      ElementType element = (ElementType)enumerator.Current;
      Console.WriteLine(element.Name);
   }
}
finally
//  Determine if enumerator implements IDisposable interface
//  If so, execute Dispose method to release resources
{
   IDisposable disposable = enumerator as System.IDisposable;
   If( disposable !=null) disposable.Dispose();
}

When a client wants to iterate across the members of a collection (enumerable), it obtains an enumerator object using the IEnumerable.GetEnumerator method. The client then uses the members of the enumerator to traverse the collection: MoveNext() moves to the next element in the collection, and the Current property returns the object referenced by the current index of the enumerator. Formally, this is an implementation of the iteration design pattern.

Core Note

Enumerating through a collection is intrinsically not a thread-safe procedure. If another client (thread) modifies the collection during the enumeration, an exception is thrown. To guarantee thread safety, lock the collection prior to traversing it:

lock( myCollection.SyncRoot )
{
   foreach ( Object item in myCollection )
   {
      // Insert your code here
   }
}

The foreach construct provides a simple and uniform way to iterate across members of a collection. For this reason, it is a good practice—almost a de facto requirement—that any custom collection support foreach. Because this requires that the collection class support the IEnumerable and IEnumerator interfaces, the traditional approach is to explicitly implement each member of these interfaces inside the collection class. Referencing Table 4-4, this means writing code to support the GetEnumerator method of the IEnumerable interface, and the MoveNext, Current, and Reset members of IEnumerator. In essence, it is necessary to build a state machine that keeps track of the most recently accessed item in a collection and knows how to move to the next item.

C# 2.0 introduced a new syntax referred to as iterators that greatly simplifies the task of implementing an iterator pattern. It includes a yield return (also a yield break) statement that causes the compiler to automatically generate code to implement the IEnumerable and IEnumerator interfaces. To illustrate, let's add iterators to the GenStack collection class that was introduced in the generics discussion in Chapter 3. (Note that iterators work identically in a non-generics collection.)

Listing 4-7 shows part of the original GenStack class with two new members that implement iterators: a GetEnumerator method that returns an enumerator to traverse the collection in the order items are stored, and a Reverse property that returns an enumerator to traverse the collection in reverse order. Both use yield return to generate the underlying code that supports foreach iteration.

using System;
using System.Collections.Generic;
public class GenStack<T>: IEnumerable<T>
{
   // Use generics type parameter to specify array type
   private T[] stackCollection;
   private int count = 0;
   // Constructor
   public GenStack(int size)
   {
      stackCollection = new T[size];
   }
   // (1) Iterator
   public IEnumerator<T> GetEnumerator()
   {
      for (int i = 0; i < count; i++)
      {
         yield return stackCollection[i];
      }
   }
   // (2) Property to return the collection in reverse order
   public IEnumerable<T> Reverse
   {
      get
      {
         for (int i = count - 1; i >= 0; i--)
         {
            yield return stackCollection[i];
          }
       }
   }
   public void Add(T item)
   {
      stackCollection[count] = item;
      count += 1;
   }
   // other class methods go here ...

This code should raise some obvious questions about iterators: Where is the implementation of IEnumerator? And how can a method with an IEnumerator return type or a property with an IEnumerable return type seemingly return a string value?

The answer to these questions is that the compiler generates the code to take care of the details. If the member containing the yield return statement is an IEnumerable type, the compiler implements the necessary generics or non-generics version of both IEnumerable and IEnumerator; if the member is an IEnumerator type, it implements only the two enumerator interfaces. The developer's responsibility is limited to providing the logic that defines how the collection is traversed and what items are returned. The compiler uses this logic to implement the IEnumerator.MoveNext method.

The client code to access the GenStack collection is straightforward. An instance of the GenStack class is created to hold ten string elements. Three items are added to the collection and are then displayed in original and reverse sequence.

GenStack<string> myStack = new GenStack<string>(10);
myStack.Add("Aida");
myStack.Add("La Boheme");
myStack.Add("Carmen");
// uses enumerator from GetEnumerator()
foreach (string s in myStack)
   Console.WriteLine(s);
// uses enumerator from Reverse property
foreach (string s in myStack.Reverse)
   Console.WriteLine(s);

The Reverse property demonstrates how easy it is to create multiple iterators for a collection. You simply implement a property that traverses the collection in some order and uses tbe yield return statement(s) to return an item in the collection.

Core Note

In order to stop iteration before an entire collection is traversed, use the yield break keywords. This causes MoveNext() to return false.

There are some restrictions on using yield return or yield break:

Chapter 2, “C# Language Fundamentals,” included a discussion of the System.Array object and its associated Sort method. That method is designed for primitive types such as strings and numeric values. However, it can be extended to work with more complex objects by implementing the IComparable and IComparer interfaces on the objects to be sorted.

Unlike the other interfaces in this section, IComparable is a member of the System namespace. It has only one member, the method CompareTo:

int CompareTo(Object obj)

The object in parentheses is compared to the current instance of the object implementing CompareTo, and the returned value indicates the results of the comparison. Let's use this method to extend the Chair class so that it can be sorted on its myPrice field. This requires adding the IComparable inheritance and implementing the CompareTo method.

public class Chair : ICloneable, IComparable
{
   private double myPrice;
   private string myVendor, myID;
   public Upholstery myUpholstery;
   //... Constructor and other code
   // Add implementation of CompareTo to sort in ascending
   int IComparable.CompareTo(Object obj)
   {
      if (obj is Chair) {
         Chair castObj = (Chair)obj;
         if (this.myPrice > castObj.myPrice)
               return 1;
         if (this.myPrice < castObj.myPrice)
               return -1;
         else return 0;
         // Reverse 1 and –1 to sort in descending order
      }
   throw new ArgumentException("object in not a Chair");
   }

The code to sort an array of Chair objects is straightforward because all the work is done inside the Chair class:

Chair[]chairsOrdered = new Chair[4];
chairsOrdered[0] = new Chair(150.0, "Lane","99-88");
chairsOrdered[1] = new Chair(250.0, "Lane","99-00");
chairsOrdered[2] = new Chair(100.0, "Lane","98-88");
chairsOrdered[3] = new Chair(120.0, "Harris","93-9");
Array.Sort(chairsOrdered);
// Lists in ascending order of price
foreach(Chair c in chairsOrdered)
   MessageBox.Show(c.ToString());

The previous example allows you to sort items on one field. A more flexible and realistic approach is to permit sorting on multiple fields. This can be done using an overloaded form of Array.Sort that takes an object that implements IComparer as its second parameter.

IComparer is similar to IComparable in that it exposes only one member, Compare, that receives two objects. It returns a value of –1, 0, or 1 based on whether the first object is less than, equal to, or greater than the second. The first object is usually the array to be sorted, and the second object is a class implementing a custom Compare method for a specific object field. This class can be implemented as a separate helper class or as a nested class within the class you are trying to sort (Chair).

This code creates a helper class that sorts the Chair objects by the myVendor field:

public class CompareByVen : IComparer
{
   public CompareByVen() { }
   int IComparer.Compare(object obj1, object obj2)
   {
      // obj1 contains array being sorted
      // obj2 is instance of helper sort class
      Chair castObj1 = (Chair)obj1;
      Chair castObj2 = (Chair)obj2;
      return String.Compare
         (castObj1.myVendor,castObj2.myVendor);
   }
}

If you refer back to the Chair class definition (refer to Figure 4-6 on page 166), you will notice that there is a problem with this code: myVendor is a private member and not accessible in this outside class. To make the example work, change it to public. A better solution, of course, is to add a property to expose the value of the field.

In order to sort, pass both the array to be sorted and an instance of the helper class to Sort:

Array.Sort(chairsOrdered,new CompareByVen());

In summary, sorting by more than one field is accomplished by adding classes that implement Compare for each sortable field.

This interface, whose members are listed in Table 4-6, is used to retrieve the contents of a collection via a zero-based numeric index. This permits insertion and removal at random location within the list.

void Insert (index, object)
void RemoveAt (index)
void Remove (object)

The most important thing to observe about this interface is that it operates on object types. This means that an ArrayList—or any collection implementing IList—may contain types of any kind. However, this flexibility comes at a cost: Casting must be widely used in order to access the object's contents, and value types must be converted to objects (boxed) in order to be stored in the collection. As we see shortly, C# 2.0 offers a new feature—called generics—that addresses both issues. However, the basic functionality of the ArrayList, as illustrated in this code segment, remains the same.

ArrayList chairList = new ArrayList( );
// alternative: ArrayList chairList = new ArrayList(5);
chairList.Add(new Chair(350.0, "Adams", "88-00"));
chairList.Add(new Chair(380.0, "Lane", "99-33"));
chairList.Add(new Chair(250.0, "Broyhill", "89-01"));
PrintValues(chairList);  // Adams – Lane - Broyhill
//
chairList.Insert(1,new Chair(100,"Kincaid"));
chairList.RemoveAt(2);
Console.WriteLine("Object Count: {0}",chairList.Count);
//
PrintValues(chairList); // Adams – Kincaid - Broyhill
// Copy objects to an array
Object chairArray = chairList.ToArray();
PrintValues((IEnumerable) chairArray);

This parameterless declaration of ArrayList causes a default amount of memory to be initially allocated. You can control the initial allocation by passing a size parameter to the constructor that specifies the number of elements you expect it to hold. In both cases, the allocated space is automatically doubled if the capacity is exceeded.

Collections implementing the IDictionary interface contain items that can be retrieved by an associated key value. Table 4-7 summarizes the most important members for working with such a collection.

ICollection Keys
ICollection Values

void Add (key, value)
void Clear ()
void Remove (key)

IDictionaryEnumerator
   GetEnumerator ()

As shown in Figure 4-7 on page 169, IDictionaryEnumerator inherits from IEnumerator. It adds properties to enumerate through a dictionary by retrieving keys, values, or both.

object Key
object Value

All classes derived from IDictionary maintain two internal lists of data: one for keys and one for the associated value, which may be an object. The values are stored in a location based on the hash code of the key. This code is provided by the key's System.Object.GetHashCode method, although it is possible to override this with your own hash algorithm.

This structure is efficient for searching, but less so for insertion. Because keys may generate the same hash code, a collision occurs that requires the code be recalculated until a free bucket is found. For this reason, the Hashtable is recommended for situations where a large amount of relatively static data is to be searched by key values.

A parameterless constructor creates a Hashtable with a default number of buckets allocated and an implicit load factor of 1. The load factor is the ratio of values to buckets the storage should maintain. For example, a load factor of .5 means that a hash table should maintain twice as many buckets as there are values in the table. The alternate syntax to specify the initial number of buckets and load factor is

Hashtable chairHash = new Hashtable(1000, .6)

The following code creates a hash table and adds objects to it:

// Create HashTable
Hashtable chairHash = new Hashtable();
// Add key - value pair to Hashtable
chairHash.Add ("88-00", new Chair(350.0, "Adams", "88-00");
chairHash.Add ("99-03", new Chair(380.0, "Lane", "99-03");
// or this syntax
chairHash["89-01"] = new Chair(250.0, "Broyhill", "89-01");

There are many ways to add values to a Hashtable, including loading them from another collection. The preceding example shows the most straightforward approach. Note that a System.Argument exception is thrown if you attempt to add a value using a key that already exists in the table. To check for a key, use the ContainsKey method:

// Check for existence of a key
bool keyFound;
if (chairHash.ContainsKey("88-00"))
   { keyFound = true;}
else
   {keyFound = false;}

The following iterates through the Keys property collection:

// List Keys
foreach (string invenKey in chairHash.Keys)
   { MessageBox.Show(invenKey); }

These statements iterate through the Values in a hash table:

// List Values
foreach (Chair chairVal in chairHash.Values)
   { MessageBox.Show(chairVal.myVendor);}

This code lists the keys and values in a hash table:

foreach ( DictionaryEntry deChair in chairHash)
{
   Chair obj = (Chair) deChair.Value;
   MessageBox.Show(deChair.Key+" "+ obj.myVendor);
}

The entry in a Hashtable is stored as a DictionaryEntry type. It has a Value and Key property that expose the actual value and key. Note that the value is returned as an object that must be cast to a Chair type in order to access its fields.

Core Note

According to .NET documentation (1.x), a synchronized version of a Hashtable that is supposed to be thread-safe for a single writer and concurrent readers can be created using the Synchronized method:

Hashtable safeHT = Hashtable.Synchronized(newHashtable());

Unfortunately, the .NET 1.x versions of the Hashtable have been proven not to be thread-safe for reading. Later versions may correct this flaw.

This section has given you a flavor of working with System.Collections interfaces and classes. The classes presented are designed to meet most general-purpose programming needs. There are numerous other useful classes in the namespace as well as in the System.Collections.Specialized namespace. You should have little trouble working with either, because all of their classes inherit from the same interfaces presented in this section.

As the following side-by-side comparison shows, the classes in the two namespaces share the same name with three exceptions: Hashtable becomes Dictionary<>, ArrayList becomes List<>, and SortedList is renamed SortedDictionary<>.

The only other points to note regard IEnumerator. Unlike the original version, the generics version inherits from IDisposable and does not support the Reset method.

Switching to the generics versions of the collection classes is primarily a matter of getting used to a new syntax, because the functionality provided by the generics and non-generics classes is virtually identical. To demonstrate, here are two examples. The first uses the Hashtable to store and retrieve instances of the Chair class (defined in Listing 4-5); the second example performs the same functions but uses the Dictionary class—the generics version of the Hashtable.

This segment consists of a Hashtable declaration and two methods: one to store a Chair object in the table and the other to retrieve an object based on a given key value.

// Example 1: Using Hashtable
public Hashtable ht = new Hashtable();
// Store Chair object in table using a unique product identifier
private void saveHT(double price, string ven, string sku)
{
   if (!ht.ContainsKey(sku))
   {
      ht.Add(sku, new Chair(price,ven,sku));
   }
}
// Display vendor and price for a product identifier
private void showChairHT(string sku)
{
   if (ht.ContainsKey(key))
   {
      if (ht[key] is Chair)  // Prevent casting exception
      {
         Chair ch = (Chair)ht[sku];
         Console.WriteLine(ch.MyVen + " " + ch.MyPr);
      }
         else
      { Console.WriteLine("Invalid Type: " +
                          (ht[key].GetType().ToString()));
      }
   }
}

Observe how data is retrieved from the Hashtable. Because data is stored as an object, verification is required to ensure that the object being retrieved is a Chair type; casting is then used to access the members of the object. These steps are unnecessary when the type-safe Dictionary class is used in place of the Hashtable.

The Dictionary<K,V> class accepts two type parameters that allow it to be strongly typed: K is the key type and V is the type of the value stored in the collection. In this example, the key is a string representing the unique product identifier, and the value stored in the Dictionary is a Chair type.

// Example 2: Using Generics Dictionary to replace Hashtable
//   Dictionary accepts string as key and Chair as data type
Dictionary<string,Chair> htgen = new Dictionary<string,Chair>();
//
private void saveGen(double price, string ven, string sku)
{
   if (!htgen.ContainsKey(sku))
   {
      htgen.Add(sku, new Chair(price,ven,sku));
   }
}

private void showChairGen(string sku)
{
   if (htgen.ContainsKey(key))
   {
      Chair ch = htgen[sku];   // No casting required
      Console.WriteLine(ch.MyVen + " " + ch.MyPr);
   }
}

The important advantage of generics is illustrated in the showChairGen method. It has no need to check the type of the stored object or perform casting.

In the long run, the new generic collection classes will render the classes in the System.Collections namespace obsolete. For that reason, new code development should use the generic classes where possible.

You can selectively exclude class members from being serialized by attaching the [NonSerialized] attribute to them. For example, you can prevent the myUpholstery field of the Chair class from being serialized by including this:

[NonSerialized]
public Upholstery myUpholstery;

The primary reason for marking a field NonSerialized is that it may have no meaning where it is serialized. Because an object graph may be loaded onto a machine different from the one on which it was stored, types that are tied to system operations are the most likely candidates to be excluded. These include delegates, events, file handles, and threads.

Core Note

A class cannot inherit the Serializable attribute from a base class; it must explicitly include the attribute. On the other hand, a derived class can be made serializable only if its base class is serializable.

.NET 2.0 introduced support for four binary serialization and deserialization events, as summarized in Table 4-9.

An event handler for these events is implemented in the object being serialized and must satisfy two requirements: the attribute associated with the event must be attached to the method, and the method must have this signature:

void <event name>(StreamingContext context)

To illustrate, here is a method called after all objects have been deserialized. The binary formatter iterates the list of objects in the order they were deserialized and calls each object's OnDeserialized method. This example uses the event handler to selectively update a field in the object. A more common use is to assign values to fields that were not serialized.

public class Chair
   {
      // other code here
   [OnDeserialized]
   void OnDeserialized(StreamingContext context)
   {
      // Edit vendor name after object is created
      if (MyVen == "Lane") MyVen = "Lane Bros.";
   }
}

Note that more than one method can have the same event attribute, and that more than one attribute can be assigned to a method—although the latter is rarely practical.

Suppose the Chair class from the preceding examples is redesigned. A field could be added or deleted, for example. What happens if one then attempts to deserialize objects in the old format to the new format? It's not an uncommon problem, and .NET offers some solutions.

If a field is deleted, the binary formatter simply ignores the extra data in the deserialized stream. However, if the formatter detects a new field in the target object, it throws an exception. To prevent this, an [OptionalField] attribute can be attached to the new field(s). Continuing the previous example, let's add a field to Chair that designates the type of wood finish:

[OptionalField]
private string finish;

The presence of the attribute causes the formatter to assign a default null value to the finish field, and no exception is thrown. The application may also take advantage of the deserialized event to assign a value to the new field:

void OnDeserialized(StreamingContext context)
{
   if (MyVen == "Lane") finish = "Oak"; else finish = "Cherry";
}

Objects that contain a Finalize method are treated differently during both object creation and Garbage Collection than those that do not contain a Finalize method. When an object implementing a Finalize method is created, space is allocated on the heap in the usual manner. In addition, a pointer to the object is placed in the finalization queue (see Figure 4-9). During Garbage Collection, the GC scans the finalization queue searching for pointers to objects that are no longer reachable. Those found are moved to the freachable queue. The objects referenced in this queue remain alive, so that a special background thread can scan the freachable queue and execute the Finalize method on each referenced object. The memory for these objects is not released until Garbage Collection occurs again.

To implement Finalize correctly, you should be aware of several issues:

It turns out that you do not have to implement Finalize directly. Instead, you can create a destructor and place the finalization code in it. The compiler converts the destructor code into a Finalize method that provides exception handling, includes a call to the base class Finalize, and contains the code entered into the destructor:

Public class Chair
{
   public Chair() { }
   ~Chair()   // Destructor
   {  // finalization code  }
}

Note that an attempt to code both a destructor and Finalize method results in a compiler error.

As it stands, this finalization approach suffers from its dependency on the GC to implement the Finalize method whenever it chooses. Performance and scalability are adversely affected when expensive resources cannot be released when they are no longer needed. Fortunately, the CLR provides a way to notify an object to perform cleanup operations and make itself unavailable. This deterministic finalization relies on a public Dispose method that a client is responsible for calling.

Although the Dispose method can be implemented independently, the recommended convention is to use it as a member of the IDisposable interface. This allows a client to take advantage of the fact that an object can be tested for the existence of an interface. Only if it detects IDisposable does it attempt to call the Dispose method. Listing 4-10 presents a general pattern for calling the Dispose method.

public class MyConnections: IDisposable
{
   public void Dispose()
   {
      // code to dispose of resources
      base.Dispose(); // include call to base Dispose()
   }
   public void UseResources() { }
}
// Client code to call Dispose()
class MyApp
{
   public static void Main()
   {
      MyConnections connObj;
      connObj = new MyConnections();
      try
      {
         connObj.UseResources();
      }
      finally   // Call dispose() if it exists
      {
         IDisposable testDisp;
         testDisp = connObj as IDisposable;
         if(testDisp != null)
            { testDisp.Dispose(); }
      }
   }

This code takes advantage of the finally block to ensure that Dispose is called even if an exception occurs. Note that you can shorten this code by replacing the try/finally block with a using construct that generates the equivalent code:

Using(connObj)
{ connObj.UseResources() }

When Dispose is executed, the object's unmanaged resources are released and the object is effectively disposed of. This raises a couple of questions: First, what happens if Dispose is called after the resources are released? And second, if Finalize is implemented, how do we prevent the GC from executing it since cleanup has already occurred?

The easiest way to handle calls to a disposed object's Dispose method is to raise an exception. In fact, the ObjectDisposedException exception is available for this purpose. To implement this, add a boolean property that is set to true when Dispose is first called. On subsequent calls, the object checks this value and throws an exception if it is true.

Because there is no guarantee that a client will call Dispose, Finalize should also be implemented when resource cleanup is required. Typically, the same cleanup method is used by both, so there is no need for the GC to perform finalization if Dispose has already been called. The solution is to execute the SuppressFinalize method when Dispose is called. This static method, which takes an object as a parameter, notifies the GC not to place the object on the freachable queue.

Listing 4-11 shows how these ideas are incorporated in actual code.

public class MyConnections: IDisposable
{
   private bool isDisposed = false;
   protected bool Disposed
   {
      get{ return isDisposed;}
   }
   public void Dispose()
   {
      if (isDisposed == false)
      {
         CleanUp();
         IsDisposed = true;
         GC.SuppressFinalize(this);
       }
   }
   protected virtual void CleanUp()
   {
      // cleanup code here
   }
   ~MyConnections()   // Destructor that creates Finalize()
   { CleanUp(); }
   public void UseResources()
   {
      // code to perform actions
      if(Disposed)
      {
         throw new ObjectDisposedException
               ("Object has been disposed of");
      }
   }
}
// Inheriting class that implements its own cleanup
public class DBConnections: MyConnections
{
   protected override void CleanUp()
   {
      // implement cleanup here
      base.CleanUp();
   }
}

The key features of this code include the following:

In summary, the .NET Garbage Collection scheme is designed to allow programmers to focus on their application logic and not deal with details of memory allocation and deallocation. It works well as long as the objects are dealing with managed resources. However, when there are valuable unmanaged resources at stake, a deterministic method of freeing them is required. This section has shown how the Dispose and Finalize methods can be used in concert to manage this aspect of an object's life cycle.