SafeHandle SafeHandle SafeHandle SafeHandle Class


Stellt eine Wrapperklasse für Betriebssystemhandles dar.Represents a wrapper class for operating system handles. Die Klasse muss geerbt werden.This class must be inherited.

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


Das folgende Codebeispiel erstellt ein benutzerdefiniertes sicheres Handle für ein Betriebssystem-Dateihandle, ableiten von SafeHandleZeroOrMinusOneIsInvalid.The following code example creates a custom safe handle for an operating system file handle, deriving from SafeHandleZeroOrMinusOneIsInvalid. Er liest Bytes aus einer Datei und zeigt ihre Hexadezimalwerte.It reads bytes from a file and displays their hexadecimal values. Es enthält auch einen Fehler, die testumgebung zu testen, die bewirkt, dass der Thread abgebrochen, aber der Wert des Handles wird freigegeben.It also contains a fault testing harness that causes the thread to abort, but the handle value is freed. Bei Verwendung einer IntPtr um Handles darzustellen, geht das Handle gelegentlich aufgrund der asynchronen Threadabbruch verloren.When using an IntPtr to represent handles, the handle is occasionally leaked due to the asynchronous thread abort.

Sie benötigen eine Textdatei im gleichen Ordner wie die kompilierte Anwendung.You will need a text file in the same folder as the compiled application. Vorausgesetzt, dass Sie die Anwendung "HexViewer" Namen verwenden, ist die Verwendung der Befehlszeile aus:Assuming that you name the application "HexViewer", the command line usage is:

HexViewer <filename> -Fault

Geben Sie optional -Fault an, um das Handle zur Offenlegung durch das Abbrechen von Threads in einem bestimmten Fenster absichtlich.Optionally specify -Fault to intentionally attempt to leak the handle by aborting the thread in a certain window. Verwenden Sie das Tool Windows Perfmon.exe Handle Anzahl während Fehler überwachen.Use the Windows Perfmon.exe tool to monitor handle counts while injecting faults.

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

namespace SafeHandleDemo
    [SecurityPermission(SecurityAction.InheritanceDemand, UnmanagedCode = true)]
    [SecurityPermission(SecurityAction.Demand, UnmanagedCode = true)]
    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.

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

        // No finalizer is needed. The finalizer on SafeHandle
        // will clean up the MySafeFileHandle instance,
        // if it hasn't already been disposed.
        // Howerver, there may be a need for a subclass to
        // introduce a finalizer, so Dispose is properly implemented here.
        [SecurityPermission(SecurityAction.Demand, UnmanagedCode = true)]
        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
            // SafeHandle records the fact that we've called Dispose.

        [SecurityPermission(SecurityAction.Demand, UnmanagedCode = true)]
        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()
            // Assumes that application is named HexViwer"
            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]);

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

            String fileName = args[0];
            bool injectFaultMode = args.Length > 1;
            if (!injectFaultMode)
                _printToConsole = true;
                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));
                    while (!_workerStarted)
                    t.Abort();  // Normal applications should not do this.
                    if (numIterations % 10 == 0)
                    if (numIterations % 10000 == 0)



Die SafeHandle -Klasse stellt Kritische Finalisierung der Handleressourcen, die verhindert, dass Ziehpunkte vorzeitig, durch die Garbagecollection und von Windows zu nicht beabsichtigten nicht verwaltete Objekte verweisen wiederverwendet wird.The SafeHandle 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.

Dieses Thema enthält die folgenden Abschnitte:This topic includes the following sections:

Warum SafeHandle? Why SafeHandle?
Funktionsweise von SafeHandle What SafeHandle does
Von SafeHandle abgeleitete KlassenClasses derived from SafeHandle

Warum SafeHandle?Why SafeHandle?

Bevor Sie .NET Framework, Version 2.0, alle Handles können nur in gekapselt Betriebssystem die IntPtr verwalteten Wrapper-Objekt.Before the .NET Framework version 2.0, all operating system handles could only be encapsulated in the IntPtr managed wrapper object. Dies war eine einfache Möglichkeit, die Interoperabilität mit systemeigenem Code können durch asynchrone Ausnahmen, z. B. ein Thread unerwartet abgebrochen oder ein Stapelüberlauf Handles verloren gehen.While this was a convenient way to interoperate with native code, handles could be leaked by asynchronous exceptions, such as a thread aborting unexpectedly or a stack overflow. Diese asynchronen Ausnahmen sind ein Hindernis für das Bereinigen von Ressourcen des Betriebssystems und praktisch von überall in Ihrer Anwendung auftreten können.These asynchronous exceptions are an obstacle to cleaning up operating system resources, and they can occur almost anywhere in your app.

Obwohl außer Kraft gesetzt werden die Object.Finalize Methode Cleanup von nicht verwalteten Ressourcen ermöglichen, wenn ein Objekt mit Garbage Collection, in einigen Fällen wird, finalisierbare Objekte freigegeben werden können, durch die Garbagecollection während der Ausführung einer Methode in einer Plattform aufrufen Rufen Sie.Although overrides to the Object.Finalize method allow cleanup of unmanaged resources when an object is being garbage collected, in some circumstances, finalizable objects can be reclaimed by garbage collection while executing a method within a platform invoke call. Wenn ein Finalizer das Handle für diese Plattform übergeben frei Plattformaufrufs, konnte dies um zu einer Beschädigung zu behandeln.If a finalizer frees the handle passed to that platform invoke call, it could lead to handle corruption. Das Handle kann auch freigegeben werden, während Ihre Methode, während eine Plattform blockiert wird Plattformaufrufs, z. B. beim Lesen einer Datei.The handle could also be reclaimed while your method is blocked during a platform invoke call, such as while reading a file.

Da Windows aggressiv wiederverwendet Steuerpunkte wird, kann ein Handle Kritischer, wiederverwendet und zeigen Sie auf eine andere Ressource, die möglicherweise vertrauliche Daten enthalten.More critically, because Windows aggressively recycles handles, a handle could be recycled and point to another resource that might contain sensitive data. Dies kann wird als einen wiederverwendungsbeschränkungs-Angriff bezeichnet und Daten beschädigt werden und werden ein Sicherheitsrisiko darstellen.This is known as a recycle attack and can potentially corrupt data and be a security threat.

Funktionsweise von SafeHandleWhat SafeHandle does

Die SafeHandle Klasse vereinfacht einige dieser Probleme mit der Objektlebensdauer und ist in die Plattform integriert aufrufen, damit Ressourcen des Betriebssystems nicht verloren.The SafeHandle class simplifies several of these object lifetime issues, and is integrated with platform invoke so that operating system resources are not leaked. Die SafeHandle Klasse löst Probleme mit der Objektlebensdauer, indem Sie Handles ohne Unterbrechung zuweist und freigibt.The SafeHandle class resolves object lifetime issues by assigning and releasing handles without interruption. Sie enthält einen kritischen Finalizer, der sicherstellt, dass das Handle geschlossen ist, und garantiert ausgeführt ist, während unerwartete AppDomain wird angenommen, dass entladen wird, auch in Fällen, wenn der Plattformaufruf als beschädigt angezeigt werden.It contains a critical finalizer that ensures that the handle is closed and is guaranteed to run during unexpected AppDomain unloads, even in cases when the platform invoke call is assumed to be in a corrupted state.

Da SafeHandle erbt CriticalFinalizerObject, alle nicht kritischen Finalizer vor den kritischen Finalizer aufgerufen.Because SafeHandle inherits from CriticalFinalizerObject, all the noncritical finalizers are called before any of the critical finalizers. Für Objekte, die im gleichen Garbage Collection Durchlauf nicht mehr aktiv sind, werden die Finalizer aufgerufen.The finalizers are called on objects that are no longer live during the same garbage collection pass. Z. B. eine FileStream Objekt kann einen normalen Finalizer geleert werden vorhandene gepufferte Daten ohne das Risiko von das Handle verloren oder wiederverwendet wird ausgeführt.For example, a FileStream object can run a normal finalizer to flush out existing buffered data without the risk of the handle being leaked or recycled. Diese sehr schwachen Sortierung zwischen kritisch "und" nicht kritischen Finalizer ist nicht zur allgemeinen Verwendung vorgesehen.This very weak ordering between critical and noncritical finalizers is not intended for general use. Vorhanden ist, in erster Linie um bei der Migration von vorhandenen Bibliotheken unterstützen, indem Sie diese Bibliotheken können mit SafeHandle ohne ihre Semantik zu verändern.It exists primarily to assist in the migration of existing libraries by allowing those libraries to use SafeHandle without altering their semantics. Darüber hinaus die kritischen Finalizer und alles, was sie aufruft, z. B. die SafeHandle.ReleaseHandle() -Methode muss in einem eingeschränkten Ausführungsbereich.Additionally, the critical finalizer and anything it calls, such as the SafeHandle.ReleaseHandle() method, must be in a constrained execution region. Dies erzwingt Einschränkungen für Code innerhalb des Finalizers Aufrufdiagramm geschrieben werden kann.This imposes constraints on what code can be written within the finalizer's call graph.

Plattformaufruf Vorgänge automatisch inkrementiert den Verweiszähler des Handles, die durch gekapselte eine SafeHandle und verringern sie nach Abschluss.Platform invoke operations automatically increment the reference count of handles encapsulated by a SafeHandle and decrement them upon completion. Dadurch wird sichergestellt, dass das Handle nicht wiederverwendet oder wurde unerwartet geschlossen.This ensures that the handle will not be recycled or closed unexpectedly.

Sie können den Besitz der zugrunde liegende Handle angeben, beim Erstellen SafeHandle Objekte, indem der Wert, der ownsHandle -Argument in der SafeHandle Klassenkonstruktor.You can specify ownership of the underlying handle when constructing SafeHandle objects by supplying a value to the ownsHandle argument in the SafeHandle class constructor. Steuert, ob die SafeHandle Objekt wird das Handle freizugeben, nachdem das Objekt verworfen wurde.This controls whether the SafeHandle object will release the handle after the object has been disposed. Dies ist nützlich für Handles spezielle Lebensdauer Anforderungen oder für die Nutzung eines Handles, deren Lebensdauer durch eine andere Person gesteuert wird.This is useful for handles with peculiar lifetime requirements or for consuming a handle whose lifetime is controlled by someone else.

Von SafeHandle abgeleitete KlassenClasses derived from SafeHandle

SafeHandle ist eine abstrakte Wrapperklasse für Betriebssystemhandles.SafeHandle is an abstract wrapper class for operating system handles. Das Ableiten von dieser Klasse ist schwierig.Deriving from this class is difficult. Verwenden Sie stattdessen die abgeleiteten Klassen im Microsoft.Win32.SafeHandles-Namespace, die sichere Handles für Folgendes bereitstellen:Instead, use the derived classes in the Microsoft.Win32.SafeHandles namespace that provide safe handles for the following:

Hinweise für Vererber

Erstellen Sie eine Klasse, die von abgeleiteten SafeHandle, Sie müssen wissen, wie zum Erstellen und Freigeben von einem Betriebssystemhandle.To create a class derived from SafeHandle, you must know how to create and free an operating system handle. Dieser Prozess unterscheidet sich für die unterschiedlichen Handletypen, weil einige verwenden, die "CloseHandle" funktionieren, während andere spezifischere Funktionen, z. B. verwenden UnmapViewOfFile oder FindClose.This process is different for different handle types because some use the CloseHandle function, while others use more specific functions such as UnmapViewOfFile or FindClose. Aus diesem Grund müssen Sie eine abgeleitete Klasse von erstellen SafeHandle für jeden Typ von Handles, die in einem SafeHandle umschlossen werden sollen.For this reason, you must create a derived class of SafeHandle for each operating system handle type that you want to wrap in a safe handle.

Wenn Sie von SafeHandle erben, müssen die folgenden Member überschrieben werden: IsInvalid und ReleaseHandle().When you inherit from SafeHandle, you must override the following members: IsInvalid and ReleaseHandle().

Außerdem sollten Sie bereitstellen, einen Standardkonstruktor, der den Basiskonstruktor mit einem Wert an, die darstellen, einen ungültigen Handlewert, aufruft und ein Boolean Wert, der angibt, ob das systemeigene Handle gehört die SafeHandle und sollte daher beim freigegeben werden SafeHandle wurde verworfen.You should also provide a default constructor that calls the base constructor with a value that represent an invalid handle value, and a Boolean value indicating whether the native handle is owned by the SafeHandle and consequently should be freed when that SafeHandle has been disposed.


SafeHandle() SafeHandle() SafeHandle() SafeHandle()
SafeHandle(IntPtr, Boolean) SafeHandle(IntPtr, Boolean) SafeHandle(IntPtr, Boolean) SafeHandle(IntPtr, Boolean)

Initialisiert eine neue Instanz der SafeHandle-Klasse mit dem angegebenen ungültigen Handlewert.Initializes a new instance of the SafeHandle class with the specified invalid handle value.


handle handle handle handle

Gibt das zu umschließende Handle an.Specifies the handle to be wrapped.


IsClosed IsClosed IsClosed IsClosed

Ruft einen Wert ab, der angibt, ob das Handle geschlossen ist.Gets a value indicating whether the handle is closed.

IsInvalid IsInvalid IsInvalid IsInvalid

Ruft beim Überschreiben in einer abgeleiteten Klasse einen Wert ab, der angibt, ob dieses Handle ungültig ist.When overridden in a derived class, gets a value indicating whether the handle value is invalid.


Close() Close() Close() Close()

Markiert das Handle für das Freigeben und Verfügbarmachen von Ressourcen.Marks the handle for releasing and freeing resources.

DangerousAddRef(Boolean) DangerousAddRef(Boolean) DangerousAddRef(Boolean) DangerousAddRef(Boolean)

Inkrementiert manuell den Verweiszähler für SafeHandle-Instanzen.Manually increments the reference counter on SafeHandle instances.

DangerousGetHandle() DangerousGetHandle() DangerousGetHandle() DangerousGetHandle()

Gibt den Wert des handle-Felds zurück.Returns the value of the handle field.

DangerousRelease() DangerousRelease() DangerousRelease() DangerousRelease()

Dekrementiert manuell den Verweiszähler für eine SafeHandle-Instanz.Manually decrements the reference counter on a SafeHandle instance.

Dispose() Dispose() Dispose() Dispose()

Gibt alle von der SafeHandle-Klasse verwendeten Ressourcen frei.Releases all resources used by the SafeHandle class.

Dispose(Boolean) Dispose(Boolean) Dispose(Boolean) Dispose(Boolean)

Gibt die von der SafeHandle-Klasse verwendeten, nicht verwalteten Ressourcen frei und gibt an, ob ein normaler Freigabevorgang ausgeführt werden soll.Releases the unmanaged resources used by the SafeHandle class specifying whether to perform a normal dispose operation.

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Bestimmt, ob das angegebene Objekt mit dem aktuellen Objekt identisch ist.Determines whether the specified object is equal to the current object.

(Inherited from Object)
Finalize() Finalize() Finalize() Finalize()

Gibt alle dem Handle zugeordneten Ressourcen frei.Frees all resources associated with the handle.

GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Fungiert als Standardhashfunktion.Serves as the default hash function.

(Inherited from Object)
GetType() GetType() GetType() GetType()

Ruft den Type der aktuellen Instanz ab.Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.Creates a shallow copy of the current Object.

(Inherited from Object)
ReleaseHandle() ReleaseHandle() ReleaseHandle() ReleaseHandle()

Führt beim Überschreiben in einer abgeleiteten Klasse den Code aus, der für das Freigeben des Handles erforderlich ist.When overridden in a derived class, executes the code required to free the handle.

SetHandle(IntPtr) SetHandle(IntPtr) SetHandle(IntPtr) SetHandle(IntPtr)

Legt das Handle für das angegebene, bereits vorhandene Handle fest.Sets the handle to the specified pre-existing handle.

SetHandleAsInvalid() SetHandleAsInvalid() SetHandleAsInvalid() SetHandleAsInvalid()

Markiert ein Handle als nicht mehr verwendet.Marks a handle as no longer used.

ToString() ToString() ToString() ToString()

Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt.Returns a string that represents the current object.

(Inherited from Object)


für volle Vertrauenswürdigkeit für erben.for full trust for inheritors. Dieser Member kann nicht von teilweise vertrauenswürdigem Code nicht vererbt werden.This member cannot be inherited by partially trusted code.

erfordert volle Vertrauenswürdigkeit für den unmittelbaren Aufrufer.requires full trust for the immediate caller. Dieser Member kann nicht von teilweise vertrauenswürdigem oder transparentem Code verwendet werden.This member cannot be used by partially trusted or transparent code.

Gilt für:

Siehe auch