mscorlib 2.0.0.0 4.0.0.0 System.Runtime.ConstrainedExecution.CriticalFinalizerObject System.IDisposable .NET 2.0

The class provides critical finalization of handle resources, preventing handles from being reclaimed prematurely by garbage collection and from being recycled by Windows to reference unintended unmanaged objects. Before the .NET Framework version 2.0, all operating system handles could only be encapsulated in the managed wrapper object.

The class contains a finalizer that ensures that the handle is closed and is guaranteed to run, even during unexpected unloads when a host may not trust the consistency of the state of the .

For more information about the benefits of using a , see Safe Handles and Critical Finalization.

This class is abstract because you cannot create a generic handle. To implement , you must create a derived class. To create derived classes, you must know how to create and free an operating system handle. This process is different for different handle types because some use CloseHandle, while others use more specific methods such as UnmapViewOfFile or FindClose. For this reason, you must create a derived class of for each operating system handle type; such as MySafeRegistryHandle, MySafeFileHandle, and MySpecialSafeFileHandle. Some of these derived classes are prewritten and provided for you in the namespace.

Writing your own classes derived from is an advanced programming feature. A set of prewritten classes derived from is provided as abstract derivations, and this set is located in the namespace. These classes are designed to provide common functionality supporting file and operating system handles.

Represents a wrapper class for operating system handles. This class must be inherited.

- Constructor
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.MayFail)

  If the parameter is false, is never called; thus, it is not recommended to use this parameter value as your code may leak resources.

  Initializes a new instance of the class with the specified invalid handle value.

  The value of an invalid handle (usually 0 or -1). Your implementation of should return true for this value.
  true to reliably let release the handle during the finalization phase; otherwise, false (not recommended).
- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void

  Calling the or method allows the resources to be freed. This might not happen immediately if other threads are using the same safe handle object, but will happen as soon as that is no longer the case. Although most classes that use the class do not need to provide a finalizer, this is sometimes necessary (for example, to flush out file buffers or to write some data back into memory). In this case, the class can provide a finalizer that is guaranteed to run before the critical finalizer runs.

  Call the or method when you are finished using the object.

  Always call or before you release your last reference to the object. Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method.

  Marks the handle for releasing and freeing resources.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.MayFail)
  System.Void `` To be added. To be added. To be added.
- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.IntPtr

  You can use this method to retrieve the actual handle value from an instance of the derived class. This method is needed for backwards compatibility because many properties in the .NET Framework return IntPtr handle types. IntPtr handle types are platform-specific types used to represent a pointer or a handle.

  Using the method can pose security risks because, if the handle has been marked as invalid with , still returns the original, potentially stale handle value. The returned handle can also be recycled at any point. At best, this means the handle might suddenly stop working. At worst, if the handle or the resource that the handle represents is exposed to untrusted code, this can lead to a recycling security attack on the reused or returned handle. For example, an untrusted caller can query data on the handle just returned and receive information for an entirely unrelated resource. See the and the methods for more information about using the methodsafely.

  Returns the value of the field.

  An IntPtr representing the value of the field. If the handle has been marked invalid with , this method still returns the original handle value, which can be a stale value.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void

  The method is the counterpart to . You should always match a call to the method with a successful call to .

  This method is intended for advanced users and must always be used carefully. To avoid leaking handle resources, always call this method inside a constrained execution region (CER), where a thread abort cannot interrupt processing. In the same way that unmatched calls can cause resource leaks, unmatched calls can cause invalid handle states to become visible to other threads. Do not expose or calls to untrusted code.

  Manually decrements the reference counter on a instance.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void

  Calling the or method allows the resources to be freed. This might not happen immediately if other threads are using the same instance of the safe handle, but will happen as soon as that is no longer the case. Although most classes using do not need to provide a finalizer, this is sometimes necessary (for example, to flush out file buffers or to write some data back into memory). In this case, they can provide a finalizer that is guaranteed to run before the critical finalizer runs.

  Call the or method when you are finished using the object. The method leaves the object in an unusable state.

  Always call the or method before you release your last reference to the object. Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method.

  Releases all resources used by the class.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void ``

  You should never explicitly call the method with the parameter set to false.

  Releases the unmanaged resources used by the class specifying whether to perform a normal dispose operation.

  true for a normal dispose operation; false to finalize the handle.
- Method
  2.0.0.0
  4.0.0.0
  System.Void

  The method is the destructor for the class. Application code should not call this method directly.

  Frees all resources associated with the handle.

- Field
  2.0.0.0
  4.0.0.0
  System.IntPtr

  Do not expose the handle publicly (that is, outside of the derived class).

  Specifies the handle to be wrapped.

- Property
  2.0.0.0
  4.0.0.0
  get: System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Boolean To be added.

  The method returns a value indicating whether the object's handle is no longer associated with a native resource. This differs from the definition of the property, which computes whether a given handle is always considered invalid. The method returns a true value in the following cases:

  The method was called.

  The method or method was called and there are no references to the object on other threads.

  Gets a value indicating whether the handle is closed.

- Property
  2.0.0.0
  4.0.0.0
  get: System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Boolean To be added.

  Derived classes must implement the property so that the common language runtime can determine whether critical finalization is required. Derived classes must provide an implementation that suits the general type of handle they support (0 or -1 is invalid). These classes can then be further derived for specific safe handle types.

  Unlike the property, which reports whether the object has finished using the underlying handle, the property calculates whether the given handle value is always considered invalid. Therefore, the property always returns the same value for any one handle value.

  When overridden in a derived class, gets a value indicating whether the handle value is invalid.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Boolean

  The method is guaranteed to be called only once and only if the handle is valid as defined by the property. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time. The garbage collector guarantees the resources to invoke this method and that the method will not be interrupted while it is in progress. This method will be prepared as a constrained execution region (CER) at instance construction time (along with all the methods in its statically determinable call graph). Although this prevents thread abort interrupts, you must still be careful not to introduce any fault paths in your overridden method. In particular, apply the attribute to any methods you call from . In most cases this code should be:

  ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)

  Additionally, for simple cleanup (for example, calling the Win32 API CloseHandle on a file handle) you can check the return value for the single platform invoke call. For complex cleanup, you may have a lot of program logic and many method calls, some of which might fail. You must ensure that your program logic has fallback code for each of those cases.

  If returns false for any reason, it generates a ReleaseHandleFailed Managed Debugging Assistant. This helps you detect cases where your attempt to release resources fails.

  When overridden in a derived class, executes the code required to free the handle.

  true if the handle is released successfully; otherwise, in the event of a catastrophic failure, false. In this case, it generates a ReleaseHandleFailed Managed Debugging Assistant.

- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void ``

  Use the method only if you need to support a pre-existing handle (for example, if the handle is returned in a structure) because the .NET Framework COM interop infrastructure does not support marshaling output handles in a structure.

  Sets the handle to the specified pre-existing handle.

  The pre-existing handle to use.
- Method
  2.0.0.0
  4.0.0.0
  System.Runtime.ConstrainedExecution.ReliabilityContract(System.Runtime.ConstrainedExecution.Consistency.WillNotCorruptState, System.Runtime.ConstrainedExecution.Cer.Success)
  System.Void

  Call the method only when you know that your handle no longer references a resource. Doing so does not change the value of the field; it only marks the handle as closed. The handle might then contain a potentially stale value. The effect of this call is that no attempt is made to free the resources.

  As with the method, use only if you need to support a pre-existing handle.

  Marks a handle as no longer used.