SafeHandle 類別

定義

命名空間:

System.Runtime.InteropServices

組件:

System.Runtime.dll

來源:

SafeHandle.cs

表示操作系統句柄的包裝函式類別。 這個類別必須繼承。

public ref class SafeHandle abstract : System::Runtime::ConstrainedExecution::CriticalFinalizerObject, IDisposable

public abstract class SafeHandle : System.Runtime.ConstrainedExecution.CriticalFinalizerObject, IDisposable

type SafeHandle = class
    inherit CriticalFinalizerObject
    interface IDisposable

Public MustInherit Class SafeHandle
Inherits CriticalFinalizerObject
Implements IDisposable

繼承

Object

CriticalFinalizerObject

SafeHandle

衍生

Microsoft.Win32.SafeHandles.SafeAccessTokenHandle

Microsoft.Win32.SafeHandles.SafeHandleMinusOneIsInvalid

Microsoft.Win32.SafeHandles.SafeHandleZeroOrMinusOneIsInvalid

System.Security.Cryptography.SafeEvpPKeyHandle

實作

IDisposable

範例

下列程式代碼範例會建立操作系統檔句柄的自定義安全句柄，衍生自 SafeHandleZeroOrMinusOneIsInvalid。 它會從檔案讀取位元組，並顯示其十六進位值。 它也包含導致線程中止但句柄值釋出的錯誤測試控管。 使用 IntPtr 來表示句柄時，句柄偶爾會因為異步線程中止而外洩。

您將需要與已編譯應用程式位於相同資料夾中的文字檔。 假設您將應用程式命名為 「HexViewer」，命令行使用方式為：

HexViewer <filename> -Fault

選擇性地指定 -Fault，以刻意嘗試在某個視窗中中止線程來洩漏句柄。 使用 Windows Perfmon.exe 工具來監視插入錯誤時處理計數。

using System;
using System.Runtime.InteropServices;
using System.IO;
using System.ComponentModel;
using System.Security;
using System.Threading;
using Microsoft.Win32.SafeHandles;
using System.Runtime.ConstrainedExecution;
using System.Security.Permissions;

namespace SafeHandleDemo
{
    internal class MySafeFileHandle : SafeHandleZeroOrMinusOneIsInvalid
    {
        // Create a SafeHandle, informing the base class
        // that this SafeHandle instance "owns" the handle,
        // and therefore SafeHandle should call
        // our ReleaseHandle method when the SafeHandle
        // is no longer in use.
        private MySafeFileHandle()
            : base(true)
        {
        }
        [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.
        }
    }

    [SuppressUnmanagedCodeSecurity()]
    internal static class NativeMethods
    {
        // Win32 constants for accessing files.
        internal const int GENERIC_READ = unchecked((int)0x80000000);

        // Allocate a file object in the kernel, then return a handle to it.
        [DllImport("kernel32", SetLastError = true, CharSet = CharSet.Unicode)]
        internal extern static MySafeFileHandle CreateFile(String fileName,
           int dwDesiredAccess, System.IO.FileShare dwShareMode,
           IntPtr securityAttrs_MustBeZero, System.IO.FileMode dwCreationDisposition,
           int dwFlagsAndAttributes, IntPtr hTemplateFile_MustBeZero);

        // Use the file handle.
        [DllImport("kernel32", SetLastError = true)]
        internal extern static int ReadFile(MySafeFileHandle handle, byte[] bytes,
           int numBytesToRead, out int numBytesRead, IntPtr overlapped_MustBeZero);

        // Free the kernel's file object (close the file).
        [DllImport("kernel32", SetLastError = true)]
        [ReliabilityContract(Consistency.WillNotCorruptState, Cer.MayFail)]
        internal extern static bool CloseHandle(IntPtr handle);
    }

    // The MyFileReader class is a sample class that accesses an operating system
    // resource and implements IDisposable. This is useful to show the types of
    // transformation required to make your resource wrapping classes
    // more resilient. Note the Dispose and Finalize implementations.
    // Consider this a simulation of System.IO.FileStream.
    public class MyFileReader : IDisposable
    {
        // _handle is set to null to indicate disposal of this instance.
        private MySafeFileHandle _handle;

        public MyFileReader(String fileName)
        {
            // Security permission check.
            String fullPath = Path.GetFullPath(fileName);
            new FileIOPermission(FileIOPermissionAccess.Read, fullPath).Demand();

            // Open a file, and save its handle in _handle.
            // Note that the most optimized code turns into two processor
            // instructions: 1) a call, and 2) moving the return value into
            // the _handle field.  With SafeHandle, the CLR's platform invoke
            // marshaling layer will store the handle into the SafeHandle
            // object in an atomic fashion. There is still the problem
            // that the SafeHandle object may not be stored in _handle, but
            // the real operating system handle value has been safely stored
            // in a critical finalizable object, ensuring against leaking
            // the handle even if there is an asynchronous exception.

            MySafeFileHandle tmpHandle;
            tmpHandle = NativeMethods.CreateFile(fileName, NativeMethods.GENERIC_READ,
                FileShare.Read, IntPtr.Zero, FileMode.Open, 0, IntPtr.Zero);

            // An async exception here will cause us to run our finalizer with
            // a null _handle, but MySafeFileHandle's ReleaseHandle code will
            // be invoked to free the handle.

            // This call to Sleep, run from the fault injection code in Main,
            // will help trigger a race. But it will not cause a handle leak
            // because the handle is already stored in a SafeHandle instance.
            // Critical finalization then guarantees that freeing the handle,
            // even during an unexpected AppDomain unload.
            Thread.Sleep(500);
            _handle = tmpHandle;  // Makes _handle point to a critical finalizable object.

            // Determine if file is opened successfully.
            if (_handle.IsInvalid)
                throw new Win32Exception(Marshal.GetLastWin32Error(), fileName);
        }

        public void Dispose()  // Follow the Dispose pattern - public nonvirtual.
        {
            Dispose(disposing: true);
            GC.SuppressFinalize(this);
        }

        // No finalizer is needed. The finalizer on SafeHandle
        // will clean up the MySafeFileHandle instance,
        // if it hasn't already been disposed.
        // However, there may be a need for a subclass to
        // introduce a finalizer, so Dispose is properly implemented here.
        protected virtual void Dispose(bool disposing)
        {
            // Note there are three interesting states here:
            // 1) CreateFile failed, _handle contains an invalid handle
            // 2) We called Dispose already, _handle is closed.
            // 3) _handle is null, due to an async exception before
            //    calling CreateFile. Note that the finalizer runs
            //    if the constructor fails.
            if (_handle != null && !_handle.IsInvalid)
            {
                // Free the handle
                _handle.Dispose();
            }
            // SafeHandle records the fact that we've called Dispose.
        }

        public byte[] ReadContents(int length)
        {
            if (_handle.IsInvalid)  // Is the handle disposed?
                throw new ObjectDisposedException("FileReader is closed");

            // This sample code will not work for all files.
            byte[] bytes = new byte[length];
            int numRead = 0;
            int r = NativeMethods.ReadFile(_handle, bytes, length, out numRead, IntPtr.Zero);
            // Since we removed MyFileReader's finalizer, we no longer need to
            // call GC.KeepAlive here.  Platform invoke will keep the SafeHandle
            // instance alive for the duration of the call.
            if (r == 0)
                throw new Win32Exception(Marshal.GetLastWin32Error());
            if (numRead < length)
            {
                byte[] newBytes = new byte[numRead];
                Array.Copy(bytes, newBytes, numRead);
                bytes = newBytes;
            }
            return bytes;
        }
    }

    static class Program
    {
        // Testing harness that injects faults.
        private static bool _printToConsole = false;
        private static bool _workerStarted = false;

        private static void Usage()
        {
            Console.WriteLine("Usage:");
            // Assumes that application is named HexViewer"
            Console.WriteLine("HexViewer <fileName> [-fault]");
            Console.WriteLine(" -fault Runs hex viewer repeatedly, injecting faults.");
        }

        private static void ViewInHex(Object fileName)
        {
            _workerStarted = true;
            byte[] bytes;
            using (MyFileReader reader = new MyFileReader((String)fileName))
            {
                bytes = reader.ReadContents(20);
            }  // Using block calls Dispose() for us here.

            if (_printToConsole)
            {
                // Print up to 20 bytes.
                int printNBytes = Math.Min(20, bytes.Length);
                Console.WriteLine("First {0} bytes of {1} in hex", printNBytes, fileName);
                for (int i = 0; i < printNBytes; i++)
                    Console.Write("{0:x} ", bytes[i]);
                Console.WriteLine();
            }
        }

        static void Main(string[] args)
        {
            if (args.Length == 0 || args.Length > 2 ||
                args[0] == "-?" || args[0] == "/?")
            {
                Usage();
                return;
            }

            String fileName = args[0];
            bool injectFaultMode = args.Length > 1;
            if (!injectFaultMode)
            {
                _printToConsole = true;
                ViewInHex(fileName);
            }
            else
            {
                Console.WriteLine("Injecting faults - watch handle count in perfmon (press Ctrl-C when done)");
                int numIterations = 0;
                while (true)
                {
                    _workerStarted = false;
                    Thread t = new Thread(new ParameterizedThreadStart(ViewInHex));
                    t.Start(fileName);
                    Thread.Sleep(1);
                    while (!_workerStarted)
                    {
                        Thread.Sleep(0);
                    }
                    t.Abort();  // Normal applications should not do this.
                    numIterations++;
                    if (numIterations % 10 == 0)
                        GC.Collect();
                    if (numIterations % 10000 == 0)
                        Console.WriteLine(numIterations);
                }
            }
        }
    }
}

備註

如需此 API 的詳細資訊，請參閱 SafeHandle的補充 API 備註。

給實施者的注意事項

若要建立衍生自 SafeHandle的類別，您必須知道如何建立及釋放操作系統句柄。 此程式對於不同的句柄類型不同，因為有些使用 CloseHandle 函式，而另一些則使用更特定的函式，例如 UnmapViewOfFile 或 FindClose。 基於這個理由，您必須為每個要包裝在安全句柄中的操作系統句柄類型，建立 SafeHandle 的衍生類別。

當您繼承自 SafeHandle時，必須覆寫下列成員：IsInvalid 和 ReleaseHandle()。

您也應該提供公用無參數建構函式，以表示無效句柄值的值呼叫基底建構函式，以及指出原生句柄是否由 SafeHandle 擁有的 Boolean 值，因此應該在處置該 SafeHandle 時釋放。

建構函式

SafeHandle(IntPtr, Boolean)

使用指定的無效句柄值，初始化 SafeHandle 類別的新實例。

欄位

handle

指定要包裝的句柄。

屬性

IsClosed	取得值，指出句柄是否關閉。
IsInvalid	在衍生類別中覆寫時，取得值，指出句柄值是否無效。

方法

Close()	標記釋放和釋放資源的句柄。
DangerousAddRef(Boolean)	在實例上手動遞增參考計數器 SafeHandle。
DangerousGetHandle()	傳回 [handle] 欄位的值。
DangerousRelease()	手動遞減 SafeHandle 實例上的參考計數器。
Dispose()	釋放 SafeHandle 類別所使用的所有資源。
Dispose(Boolean)	釋放 SafeHandle 類別所使用的 Unmanaged 資源，指定是否要執行一般處置作業。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Finalize()	釋放與句柄相關聯的所有資源。
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
ReleaseHandle()	在衍生類別中覆寫時，執行釋放句柄所需的程序代碼。
SetHandle(IntPtr)	將句柄設定為指定的既有句柄。
SetHandleAsInvalid()	將句柄標示為不再使用。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)

另請參閱

• Microsoft.Win32.SafeHandles
• CriticalHandle
• CriticalFinalizerObject