SafeHandle.ReleaseHandle Method


在派生类中重写时,执行释放句柄所需的代码。When overridden in a derived class, executes the code required to free the handle.

 abstract bool ReleaseHandle();
protected abstract bool ReleaseHandle ();
abstract member ReleaseHandle : unit -> bool
Protected MustOverride Function ReleaseHandle () As Boolean



如果句柄释放成功,则为 true;如果出现灾难性故障,则为 falsetrue if the handle is released successfully; otherwise, in the event of a catastrophic failure, false. 在这种情况下,它会生成 releaseHandleFailed 托管调试助手。In this case, it generates a releaseHandleFailed Managed Debugging Assistant.


下面的代码示例释放句柄,该句柄是为 SafeHandle 类提供的更大示例的一部分。The following code example releases the handle and is part of a larger example provided for the SafeHandle class.

[ReliabilityContract(Consistency.WillNotCorruptState, Cer.MayFail)]
override protected bool ReleaseHandle()
    // Here, we must obey all rules for constrained execution regions.
    return NativeMethods.CloseHandle(handle);
    // If ReleaseHandle failed, it can be reported via the
    // "releaseHandleFailed" managed debugging assistant (MDA).  This
    // MDA is disabled by default, but can be enabled in a debugger
    // or during testing to diagnose handle corruption problems.
    // We do not throw an exception because most code could not recover
    // from the problem.


ReleaseHandle 方法保证只调用一次,并且仅当句柄有效,如 IsInvalid 属性所定义的那样。The ReleaseHandle method is guaranteed to be called only once and only if the handle is valid as defined by the IsInvalid property. SafeHandle 派生类中实现此方法可执行释放句柄所需的任何代码。Implement this method in your SafeHandle derived classes to execute any code that is required to free the handle. 由于 SafeHandle 的一项功能是保证防止资源泄漏,因此,实现 ReleaseHandle 的代码必须永远不会失败。Because one of the functions of SafeHandle is to guarantee prevention of resource leaks, the code in your implementation of ReleaseHandle must never fail. 在对同时进行了垃圾回收的对象运行正常终结器后,垃圾回收器将调用 ReleaseHandleThe garbage collector calls ReleaseHandle 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. 在实例构造时,此方法将准备为受约束的执行区域(CER)(以及其可静态定义的调用关系图中的所有方法)。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). 尽管这会阻止线程中止中断,但你仍必须注意不要在重写的 ReleaseHandle 方法中引入任何错误路径。Although this prevents thread abort interrupts, you must still be careful not to introduce any fault paths in your overridden ReleaseHandle method. 具体而言,将 ReliabilityContractAttribute 特性应用于从 ReleaseHandle中调用的任何方法。In particular, apply the ReliabilityContractAttribute attribute to any methods you call from ReleaseHandle. 在大多数情况下,此代码应为:In most cases this code should be:

ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)

此外,对于简单清除(例如,在文件句柄上调用 Windows API CloseHandle),可以检查单个平台调用的返回值。Additionally, for simple cleanup (for example, calling the Windows 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.

如果出于任何原因 ReleaseHandle 返回 false,它将生成releaseHandleFailed托管调试助手。If ReleaseHandle returns false for any reason, it generates a releaseHandleFailed Managed Debugging Assistant. 这有助于检测到释放资源的尝试失败的情况。This helps you detect cases where your attempt to release resources fails.

Applies to

See also