Use this method to close or release unmanaged resources such as files, streams, and handles held by an instance of the class that implements this interface. By convention, this method is used for all tasks associated with freeing resources held by an object, or preparing an object for reuse.

When implementing this method, ensure that all held resources are freed by propagating the call through the containment hierarchy. For example, if an object A allocates an object B, and object B allocates an object C, then A's IDisposable.Dispose implementation must call IDisposable.Dispose on B, which must in turn call IDisposable.Dispose on C.

An object must also call the IDisposable.Dispose method of its base class if the base class implements IDisposable. For more information about implementing IDisposable on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the IDisposable topic.

If an object's IDisposable.Dispose method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its IDisposable.Dispose method is called multiple times. Instance methods other than IDisposable.Dispose can throw an ObjectDisposedException when resources are already disposed.

Users might expect a resource type to use a particular convention to denote an allocated state versus a freed state. An example of this is stream classes, which are traditionally thought of as open or closed. The implementer of a class that has such a convention might choose to implement a public method with a customized name, such as Close, that calls the IDisposable.Dispose method.

Because the IDisposable.Dispose method must be called explicitly, objects that implement IDisposable must also implement a finalizer to handle freeing resources when IDisposable.Dispose is not called. By default, the garbage collector automatically calls an object's finalizer prior to reclaiming its memory. However, once the IDisposable.Dispose method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, IDisposable.Dispose implementations can call the GC.SuppressFinalize(object) method.

For more information on implementing finalizers and the IDisposable.Dispose method, see the GC class, the object.Finalize method, and Implementing Finalize and Dispose to Clean Up Unmanaged Resources.

When you use an object that accesses unmanaged resources, such as a System.IO.StreamWriter, a good practice is to create the instance with a using statement. The using statement automatically closes the stream and calls IDisposable.Dispose on the object when the code that is using it has completed. For an example, see the System.IO.StreamWriter class.

Resource classes should follow the pattern illustrated by this example:

class ResourceWrapper : BaseType, IDisposable {
  // Pointer to a external resource.
  private int handle; 
  private OtherResource otherRes; //Other resource you use.
  private bool disposed = false;

  public ResourceWrapper () {
    handle = //Allocate on the unmanaged side.
    otherRes = new OtherResource (...);
  }
  // Free your own state.
  private void freeState () {
    if (!disposed) {
       CloseHandle (handle);
       dispose = true;
    }
  }

  // Free your own state, call dispose on all state you hold, 
  // and take yourself off the Finalization queue.
  public void Dispose () {
    freeState ();
    OtherRes.Dispose();
    // If base type implements dispose, call it.
    base.Dispose(); 
    GC.SuppressFinalize(this);  
  }

  // Free your own state (not other state you hold) 
  // and give your base class a chance to finalize. 
  ~ResourceWrapper (){
     freeState();
  }
}