Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
Assembly: mscorlib (in mscorlib.dll)
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.
C++ programmers should read Destructors and Finalizers in Visual C++. In the .NET Framework version 2.0, the C++ compiler provides support for implementing deterministic disposal of resources and does not allow direct implementation of the method.
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 implementation must call on B, which must in turn call on C. An object must also call the method of its base class if the base class implements IDisposable.
If an object's 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 method is called multiple times. Instance methods other than 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 method.
Because the method must be called explicitly, objects that implement IDisposable must also implement a finalizer to handle freeing resources when is not called. By default, the garbage collector automatically calls an object's finalizer prior to reclaiming its memory. However, once the method has been called, it is typically unnecessary for the garbage collector to call the disposed object's finalizer. To prevent automatic finalization, implementations can call the GC.SuppressFinalize method.
For more information on implementing finalizers and the 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 StreamWriter, a good practice is to create the instance with a using statement. The using statement automatically closes the stream and calls on the object when the code that is using it has completed. For an example, see the StreamWriter class.
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.