BCL mscorlib [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] 1.0.5000.0 2.0.0.0 4.0.0.0 System.Runtime.InteropServices.ComVisible(true)

The primary use of this interface is to release unmanaged resources. The garbage collector automatically releases the memory allocated to a managed object when that object is no longer used. However, it is not possible to predict when garbage collection will occur. Furthermore, the garbage collector has no knowledge of unmanaged resources such as window handles, or open files and streams.

Use the method of this interface to explicitly release unmanaged resources in conjunction with the garbage collector. The consumer of an object can call this method when the object is no longer needed.

It is a version-breaking change to add the interface to an existing class, because it changes the semantics of the class.

C++ programmers should read Destructors and Finalizers in Visual C++. In the .NET Framework version, the C++ compiler provides support for implementing deterministic disposal of resources and does not allow direct implementation of the method.

For a detailed discussion about how this interface and the method are used, see the Garbage Collection and Implementing a Dispose Method topics.

## IDisposable and the inheritance hierarchy

A base class with subclasses that should be disposable must implement as follows:

It should provide one public non-virtual method and a protected virtual Dispose(Boolean ) method.

The method must call Dispose(true) and should suppress finalization for performance.

The base type should not include any finalizers.

Subclasses should implement the disposable pattern as follows:

They must override Dispose(Boolean) and call the base class Dispose(Boolean) implementation.

They can provide a finalizer if needed. The finalizer must call Dispose(false).

## Calling the IDisposable interface

When calling a class that implements the interface, use the try/finally pattern to make sure that unmanaged resources are disposed of even if an exception interrupts your application.

For more information about the try/finally pattern, see Try...Catch...Finally Statement (Visual Basic), try-finally (C# Reference), or The try-finally Statement(C++).

Note that you can use the using statement (Using in Visual Basic) instead of the try/finally pattern. For more information, see the Using Statement (Visual Basic) documentation or the using Statement (C# Reference) documentation.

Defines a method to release allocated resources.

- Method
  1.0.5000.0
  2.0.0.0
  4.0.0.0
  System.Void

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

  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 . For more information about implementing on a base class and its subclasses, see the "IDisposable and the inheritance hierarchy" section in the topic.

  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 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 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 method.

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

  When you use an object that accesses unmanaged resources, such as a , 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 class.

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

  0
0