Remarks

Note:

This method is, by convention, used for all tasks associated with freeing resources held by an object, or preparing an object for reuse.

When implementing the IDisposable.Dispose method, objects should seek to 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 B allocates an object C, then A's IDisposable.Dispose implementation should call IDisposable.Dispose on B, which should in turn call IDisposable.Dispose on C. Objects should also call the IDisposable.Dispose method of their base class if the base class implements IDisposable.

If an object's IDisposable.Dispose method is called more than once, the object should ignore all calls after the first one. The object should not throw an exception if its IDisposable.Dispose method is called multiple times. IDisposable.Dispose can throw an exception if an error occurs because a resource has already been freed and IDisposable.Dispose had not been called previously.

A resource type might 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. Classes that have such conventions might choose to implement a public method with a customized name, which calls the IDisposable.Dispose method.

Because the IDisposable.Dispose method must be called explicitly, objects that implement IDisposable should also implement a finalizer to handle freeing resources when IDisposable.Dispose is not called. By default, the garbage collector will automatically call an object's finalizer prior to reclaiming its memory. However, once the IDisposable.Dispose method has been called, it is typically unnecessary and/or undesirable for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, IDisposable.Dispose implementations can call GC.SuppressFinalize(object). For additional information on implementing finalizers, see GC and object.Finalize.

[Edit]

Example

Resource classes should follow the pattern illustrated by this example:

C# 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(); } }

Requirements

Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0