Реализация метода DisposeImplementing a Dispose method

Реализация метода Dispose необходима для освобождения неуправляемых ресурсов, которые использует ваше приложение.You implement a Dispose method to release unmanaged resources used by your application. Сборщик мусора .NET не выделяет и не освобождает неуправляемую память.The .NET garbage collector does not allocate or release unmanaged memory.

Шаблон ликвидации объекта, именуемый также шаблоном удаления, налагает определенные правила на время жизни объекта.The pattern for disposing an object, referred to as a dispose pattern, imposes order on the lifetime of an object. Шаблон удаления используется только для объектов, осуществляющих доступ к неуправляемым ресурсам, таких как дескрипторы файлов и каналов, дескрипторы реестра, дескрипторы ожидания и указатели на блоки неуправляемой памяти.The dispose pattern is used only for objects that access unmanaged resources, such as file and pipe handles, registry handles, wait handles, or pointers to blocks of unmanaged memory. Это вызвано тем, что сборщик мусора очень эффективно удаляет неиспользуемые управляемые объекты, но не может удалить неуправляемые объекты.This is because the garbage collector is very efficient at reclaiming unused managed objects, but it is unable to reclaim unmanaged objects.

Существует два варианта шаблона удаления:The dispose pattern has two variations:

  • Заключение в оболочку каждого неуправляемого ресурса, используемого типом в безопасном дескрипторе (то есть в классе, производном от System.Runtime.InteropServices.SafeHandle).You wrap each unmanaged resource that a type uses in a safe handle (that is, in a class derived from System.Runtime.InteropServices.SafeHandle). В этом случае необходимо реализовать интерфейс IDisposable и дополнительный метод Dispose(Boolean).In this case, you implement the IDisposable interface and an additional Dispose(Boolean) method. Это рекомендуемый вариант, не требующий переопределения метода Object.Finalize.This is the recommended variation and doesn't require overriding the Object.Finalize method.

    Примечание

    Пространство имен Microsoft.Win32.SafeHandles содержит набор классов, производных от SafeHandle. Эти классы перечислены в разделе Использование безопасных дескрипторов.The Microsoft.Win32.SafeHandles namespace provides a set of classes derived from SafeHandle, which are listed in the Using safe handles section. Если не удается найти класс, способный освободить неуправляемый ресурс, можно реализовать собственный подкласс SafeHandle.If you can't find a class that is suitable for releasing your unmanaged resource, you can implement your own subclass of SafeHandle.

  • Реализация интерфейса IDisposable и дополнительного метода Dispose(Boolean), а также переопределение метода Object.Finalize.You implement the IDisposable interface and an additional Dispose(Boolean) method, and you also override the Object.Finalize method. Необходимо переопределить метод Finalize, чтобы убедиться, что неуправляемые ресурсы удаляются, если реализация IDisposable.Dispose не вызывается объектом-получателем типа.You must override Finalize to ensure that unmanaged resources are disposed of if your IDisposable.Dispose implementation is not called by a consumer of your type. При использовании рекомендуемого метода, описанного в предыдущем пункте, класс System.Runtime.InteropServices.SafeHandle делает это от вашего имени.If you use the recommended technique discussed in the previous bullet, the System.Runtime.InteropServices.SafeHandle class does this on your behalf.

Чтобы обеспечить соответствующую очистку ресурсов, метод Dispose должен быть доступен для многократного вызова без выдачи исключения.To help ensure that resources are always cleaned up appropriately, a Dispose method should be callable multiple times without throwing an exception.

В приведенном для метода GC.KeepAlive примере показано, как чрезмерно активная сборка мусора может привести к выполнению финализатора до завершения выполнения утилизируемого объекта.The code example provided for the GC.KeepAlive method shows how aggressive garbage collection can cause a finalizer to run while a member of the reclaimed object is still executing. Рекомендуется вызывать метод KeepAlive в конце большого метода Dispose.It is a good idea to call the KeepAlive method at the end of a lengthy Dispose method.

Dispose() и Dispose(Boolean)Dispose() and Dispose(Boolean)

Интерфейс IDisposable требует реализации одного метода Dispose без параметров.The IDisposable interface requires the implementation of a single parameterless method, Dispose. Однако шаблон удаления требует реализации двух методов Dispose:However, the dispose pattern requires two Dispose methods to be implemented:

  • Реализация открытого невиртуального (в Visual Basic — NonInheritable) метода IDisposable.Dispose без параметров.A public non-virtual (NonInheritable in Visual Basic) IDisposable.Dispose implementation that has no parameters.

  • Защищенный виртуальный (в Visual Basic — Overridable) метод Dispose со следующей подписью:A protected virtual (Overridable in Visual Basic) Dispose method whose signature is:

    protected virtual void Dispose(bool disposing)
    
    Protected Overridable Sub Dispose(disposing As Boolean)
    

Перегрузка Dispose()The Dispose() overload

Поскольку открытый невиртуальный (NonInheritable в Visual Basic) метод Dispose без параметров вызывается объектом-получателем типа, его назначение состоит в том, чтобы освободить неуправляемые ресурсы и указать, что метод завершения, если он задан, не должен выполняться.Because the public, non-virtual (NonInheritable in Visual Basic), parameterless Dispose method is called by a consumer of the type, its purpose is to free unmanaged resources and to indicate that the finalizer, if one is present, doesn't have to run. Он имеет стандартную реализацию:Because of this, it has a standard implementation:

public void Dispose()
{
   // Dispose of unmanaged resources.
   Dispose(true);
   // Suppress finalization.
   GC.SuppressFinalize(this);
}
Public Sub Dispose() _
           Implements IDisposable.Dispose
   ' Dispose of unmanaged resources.
   Dispose(True)
   ' Suppress finalization.
   GC.SuppressFinalize(Me)
End Sub

Метод Dispose полностью выполняет очистку объектов, поэтому сборщику мусора не требуется вызывать переопределенный метод Object.Finalize.The Dispose method performs all object cleanup, so the garbage collector no longer needs to call the objects' Object.Finalize override. Таким образом, вызов метода SuppressFinalize не позволит сборщику мусора запустить метод завершения.Therefore, the call to the SuppressFinalize method prevents the garbage collector from running the finalizer. Если тип не имеет метода завершения, вызов метода GC.SuppressFinalize не производит эффекта.If the type has no finalizer, the call to GC.SuppressFinalize has no effect. Обратите внимание, что фактическая работа по освобождению неуправляемых ресурсов выполняется вторым перегруженным методом Dispose.Note that the actual work of releasing unmanaged resources is performed by the second overload of the Dispose method.

Перегрузка Dispose(Boolean)The Dispose(Boolean) overload

Во второй перегрузке disposing используется параметр типа Boolean, который указывает, откуда осуществляется вызов метода: из метода Dispose (значение true) или из метода завершения (значение false).In the second overload, the disposing parameter is a Boolean that indicates whether the method call comes from a Dispose method (its value is true) or from a finalizer (its value is false).

Тело метода состоит из двух блоков кода:The body of the method consists of two blocks of code:

  • Блок, который освобождает неуправляемые ресурсы.A block that frees unmanaged resources. Этот блок выполняется вне зависимости от значения параметра disposing.This block executes regardless of the value of the disposing parameter.

  • Условный блок, который освобождает управляемые ресурсы.A conditional block that frees managed resources. Этот блок выполняется, если параметр disposing имеет значение true.This block executes if the value of disposing is true. К управляемым ресурсам, которые он освобождает, могут относиться:The managed resources that it frees can include:

    Управляемые объекты, реализующие IDisposable.Managed objects that implement IDisposable. Условный блок может использоваться для вызова реализации Dispose.The conditional block can be used to call their Dispose implementation. При использовании безопасного дескриптора в качестве оболочки для неуправляемого ресурса необходимо вызвать реализацию SafeHandle.Dispose(Boolean).If you have used a safe handle to wrap your unmanaged resource, you should call the SafeHandle.Dispose(Boolean) implementation here.

    Управляемые объекты, которые используют большие объемы памяти или дефицитные ресурсы.Managed objects that consume large amounts of memory or consume scarce resources. При использовании метода Dispose эти объекты освобождаются быстрее, чем при недетерминированной очистке сборщиком мусора.Freeing these objects explicitly in the Dispose method releases them faster than if they were reclaimed non-deterministically by the garbage collector.

Если метод вызывается из метода завершения (т. е. если свойство disposing имеет значение false), выполняется только тот код, который освобождает неуправляемые ресурсы.If the method call comes from a finalizer (that is, if disposing is false), only the code that frees unmanaged resources executes. Поскольку порядок уничтожения управляемых объектов сборщиком мусора во время завершения не определен, вызов этой перегрузки Dispose со значением false предотвращает попытки метода завершения освободить управляемые ресурсы, которые уже могли быть освобождены.Because the order in which the garbage collector destroys managed objects during finalization is not defined, calling this Dispose overload with a value of false prevents the finalizer from trying to release managed resources that may have already been reclaimed.

Реализация шаблона удаления для базового классаImplementing the dispose pattern for a base class

При реализации шаблона удаления для базового класса необходимо следующее:If you implement the dispose pattern for a base class, you must provide the following:

Важно!

Вам следует реализовать этот шаблон для всех базовых классов, которые реализуют Dispose() и не являются sealed (NotInheritable в Visual Basic).You should implement this pattern for all base classes that implement Dispose() and are not sealed (NotInheritable in Visual Basic).

  • Реализация Dispose, которая вызывает метод Dispose(Boolean).A Dispose implementation that calls the Dispose(Boolean) method.

  • Метод Dispose(Boolean), который выполняет фактическую работу по освобождению ресурсов.A Dispose(Boolean) method that performs the actual work of releasing resources.

  • Любой класс, производный от класса SafeHandle, который создает оболочку для неуправляемого ресурс (рекомендуется), или переопределенный метод Object.Finalize.Either a class derived from SafeHandle that wraps your unmanaged resource (recommended), or an override to the Object.Finalize method. Класс SafeHandle содержит метод завершения, что освобождает разработчика от необходимости создавать его вручную.The SafeHandle class provides a finalizer that frees you from having to code one.

Вот общий шаблон реализации шаблона удаления для базового класса, который использует безопасный дескриптор.Here's the general pattern for implementing the dispose pattern for a base class that uses a safe handle.

using Microsoft.Win32.SafeHandles;
using System;
using System.Runtime.InteropServices;

class BaseClass : IDisposable
{
   // Flag: Has Dispose already been called?
   bool disposed = false;
   // Instantiate a SafeHandle instance.
   SafeHandle handle = new SafeFileHandle(IntPtr.Zero, true);
   
   // Public implementation of Dispose pattern callable by consumers.
   public void Dispose()
   { 
      Dispose(true);
      GC.SuppressFinalize(this);           
   }
   
   // Protected implementation of Dispose pattern.
   protected virtual void Dispose(bool disposing)
   {
      if (disposed)
         return; 
      
      if (disposing) {
         handle.Dispose();
         // Free any other managed objects here.
         //
      }
      
      disposed = true;
   }
}
Imports Microsoft.Win32.SafeHandles
Imports System.Runtime.InteropServices

Class BaseClass : Implements IDisposable
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   ' Instantiate a SafeHandle instance.
   Dim handle As SafeHandle = New SafeFileHandle(IntPtr.Zero, True)

   ' Public implementation of Dispose pattern callable by consumers.
   Public Sub Dispose() _
              Implements IDisposable.Dispose
      Dispose(True)
      GC.SuppressFinalize(Me)           
   End Sub
   
   ' Protected implementation of Dispose pattern.
   Protected Overridable Sub Dispose(disposing As Boolean)
      If disposed Then Return
      
      If disposing Then
         handle.Dispose()
         ' Free any other managed objects here.
         '
      End If
      
      disposed = True
   End Sub
End Class

Примечание

В предыдущем примере используется объект SafeFileHandle для иллюстрации шаблона. Вместо него может использоваться любой объект, производный от SafeHandle.The previous example uses a SafeFileHandle object to illustrate the pattern; any object derived from SafeHandle could be used instead. Обратите внимание, что в этом примере неправильно создаются экземпляры объекта SafeFileHandle.Note that the example does not properly instantiate its SafeFileHandle object.

Вот общий шаблон реализации шаблона удаления для базового класса, который переопределяет метод Object.Finalize.Here's the general pattern for implementing the dispose pattern for a base class that overrides Object.Finalize.

using System;

class BaseClass : IDisposable
{
   // Flag: Has Dispose already been called?
   bool disposed = false;
   
   // Public implementation of Dispose pattern callable by consumers.
   public void Dispose()
   { 
      Dispose(true);
      GC.SuppressFinalize(this);           
   }
   
   // Protected implementation of Dispose pattern.
   protected virtual void Dispose(bool disposing)
   {
      if (disposed)
         return; 
      
      if (disposing) {
         // Free any other managed objects here.
         //
      }
      
      // Free any unmanaged objects here.
      //
      disposed = true;
   }

   ~BaseClass()
   {
      Dispose(false);
   }
}
Class BaseClass : Implements IDisposable
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   
   ' Public implementation of Dispose pattern callable by consumers.
   Public Sub Dispose() _
              Implements IDisposable.Dispose
      Dispose(True)
      GC.SuppressFinalize(Me)           
   End Sub
   
   ' Protected implementation of Dispose pattern.
   Protected Overridable Sub Dispose(disposing As Boolean)
      If disposed Then Return
      
      If disposing Then
         ' Free any other managed objects here.
         '
      End If
      
      ' Free any unmanaged objects here.
      '
      disposed = True
   End Sub

   Protected Overrides Sub Finalize()
      Dispose(False)      
   End Sub
End Class

Примечание

В C# переопределение Object.Finalize выполняется путем определения деструктора.In C#, you override Object.Finalize by defining a destructor.

Реализация шаблона удаления для производного классаImplementing the dispose pattern for a derived class

Класс, производный от класса, реализующего интерфейс IDisposable, не должен реализовывать интерфейс IDisposable, поскольку реализация метода IDisposable.Dispose базового класса наследуется производными классами.A class derived from a class that implements the IDisposable interface shouldn't implement IDisposable, because the base class implementation of IDisposable.Dispose is inherited by its derived classes. Вместо этого, чтобы реализовать шаблон удаления для базового класса, необходимо следующее:Instead, to implement the dispose pattern for a derived class, you provide the following:

  • Метод protected Dispose(Boolean), который переопределяет метод базового класса и выполняет фактическую работу по освобождению ресурсов производного класса.A protected Dispose(Boolean) method that overrides the base class method and performs the actual work of releasing the resources of the derived class. Этот метод должен также вызвать метод Dispose(Boolean) базового класса и передать состояние удаления ресурса в качестве аргумента.This method should also call the Dispose(Boolean) method of the base class and pass its disposing status for the argument.

  • Любой класс, производный от класса SafeHandle, который создает оболочку для неуправляемого ресурс (рекомендуется), или переопределенный метод Object.Finalize.Either a class derived from SafeHandle that wraps your unmanaged resource (recommended), or an override to the Object.Finalize method. Класс SafeHandle содержит метод завершения, что освобождает разработчика от необходимости создавать его вручную.The SafeHandle class provides a finalizer that frees you from having to code one. Если есть метод завершения, он должен вызывать перегруженный метод Dispose(Boolean), указывая при этом аргумент disposing со значением false.If you do provide a finalizer, it should call the Dispose(Boolean) overload with a disposing argument of false.

Вот общий шаблон реализации шаблона удаления для производного класса, который использует безопасный дескриптор:Here's the general pattern for implementing the dispose pattern for a derived class that uses a safe handle:

using Microsoft.Win32.SafeHandles;
using System;
using System.Runtime.InteropServices;

class DerivedClass : BaseClass
{
   // Flag: Has Dispose already been called?
   bool disposed = false;
   // Instantiate a SafeHandle instance.
   SafeHandle handle = new SafeFileHandle(IntPtr.Zero, true);

   // Protected implementation of Dispose pattern.
   protected override void Dispose(bool disposing)
   {
      if (disposed)
         return; 
      
      if (disposing) {
         handle.Dispose();
         // Free any other managed objects here.
         //
      }
      
      // Free any unmanaged objects here.
      //

      disposed = true;
      // Call base class implementation.
      base.Dispose(disposing);
   }
}
Imports Microsoft.Win32.SafeHandles
Imports System.Runtime.InteropServices

Class DerivedClass : Inherits BaseClass 
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   ' Instantiate a SafeHandle instance.
   Dim handle As SafeHandle = New SafeFileHandle(IntPtr.Zero, True)

   ' Protected implementation of Dispose pattern.
   Protected Overrides Sub Dispose(disposing As Boolean)
      If disposed Then Return
      
      If disposing Then
         handle.Dispose()
         ' Free any other managed objects here.
         '
      End If
      
      ' Free any unmanaged objects here.
      '
      disposed = True
      
      ' Call base class implementation.
      MyBase.Dispose(disposing)
   End Sub
End Class

Примечание

В предыдущем примере используется объект SafeFileHandle для иллюстрации шаблона. Вместо него может использоваться любой объект, производный от SafeHandle.The previous example uses a SafeFileHandle object to illustrate the pattern; any object derived from SafeHandle could be used instead. Обратите внимание, что в этом примере неправильно создаются экземпляры объекта SafeFileHandle.Note that the example does not properly instantiate its SafeFileHandle object.

Вот общий шаблон реализации шаблона удаления для производного класса, который переопределяет метод Object.Finalize:Here's the general pattern for implementing the dispose pattern for a derived class that overrides Object.Finalize:

using System;

class DerivedClass : BaseClass
{
   // Flag: Has Dispose already been called?
   bool disposed = false;
   
   // Protected implementation of Dispose pattern.
   protected override void Dispose(bool disposing)
   {
      if (disposed)
         return; 
      
      if (disposing) {
         // Free any other managed objects here.
         //
      }
      
      // Free any unmanaged objects here.
      //
      disposed = true;
      
      // Call the base class implementation.
      base.Dispose(disposing);
   }

   ~DerivedClass()
   {
      Dispose(false);
   }
}
Class DerivedClass : Inherits BaseClass
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   
   ' Protected implementation of Dispose pattern.
   Protected Overrides Sub Dispose(disposing As Boolean)
      If disposed Then Return
      
      If disposing Then
         ' Free any other managed objects here.
         '
      End If
      
      ' Free any unmanaged objects here.
      '
      disposed = True

      ' Call the base class implementation.
      MyBase.Dispose(disposing)
   End Sub
   
   Protected Overrides Sub Finalize()
      Dispose(False)
   End Sub 
End Class

Примечание

В C# переопределение Object.Finalize выполняется путем определения деструктора.In C#, you override Object.Finalize by defining a destructor.

Использование безопасных дескрипторовUsing safe handles

Написание кода для метода завершения объекта является сложной задачей, которая может вызвать проблемы при неправильном выполнении.Writing code for an object's finalizer is a complex task that can cause problems if not done correctly. Поэтому вместо реализации метода завершения рекомендуется создавать объекты System.Runtime.InteropServices.SafeHandle.Therefore, we recommend that you construct System.Runtime.InteropServices.SafeHandle objects instead of implementing a finalizer.

Классы, производные от класса System.Runtime.InteropServices.SafeHandle, упрощают проблемы времени существования объекта путем назначения и освобождения дескрипторов без прерываний.Classes derived from the System.Runtime.InteropServices.SafeHandle class simplify object lifetime issues by assigning and releasing handles without interruption. Они содержат критический метод завершения, который обязательно выполняется во время выгрузки домена приложения.They contain a critical finalizer that is guaranteed to run while an application domain is unloading. Дополнительные сведения о преимуществах использования безопасного дескриптора см. в разделе System.Runtime.InteropServices.SafeHandle.For more information about the advantages of using a safe handle, see System.Runtime.InteropServices.SafeHandle. Безопасные дескрипторы предоставляются следующими производными классами в пространстве имен Microsoft.Win32.SafeHandles:The following derived classes in the Microsoft.Win32.SafeHandles namespace provide safe handles:

Использование безопасного дескриптора для реализации шаблона удаления для базового классаUsing a safe handle to implement the dispose pattern for a base class

В следующем примере показан шаблон удаления для базового класса DisposableStreamResource, который использует безопасный дескриптор для инкапсуляции неуправляемых ресурсов.The following example illustrates the dispose pattern for a base class, DisposableStreamResource, that uses a safe handle to encapsulate unmanaged resources. Он определяет класс DisposableResource, который использует SafeFileHandle для создания экземпляра объекта Stream, который представляет открытый файл.It defines a DisposableResource class that uses a SafeFileHandle to wrap a Stream object that represents an open file. Метод DisposableResource также включает свойство Size, которое возвращает общее количество байтов в файловом потоке.The DisposableResource method also includes a single property, Size, that returns the total number of bytes in the file stream.

using Microsoft.Win32.SafeHandles;
using System;
using System.IO;
using System.Runtime.InteropServices;

public class DisposableStreamResource : IDisposable
{
   // Define constants.
   protected const uint GENERIC_READ = 0x80000000;
   protected const uint FILE_SHARE_READ = 0x00000001;
   protected const uint OPEN_EXISTING = 3;
   protected const uint FILE_ATTRIBUTE_NORMAL = 0x80;
   protected IntPtr INVALID_HANDLE_VALUE = new IntPtr(-1);
   private const int INVALID_FILE_SIZE = unchecked((int) 0xFFFFFFFF);
   
   // Define Windows APIs.
   [DllImport("kernel32.dll", EntryPoint = "CreateFileW", CharSet = CharSet.Unicode)]
   protected static extern IntPtr CreateFile (
                                  string lpFileName, uint dwDesiredAccess, 
                                  uint dwShareMode, IntPtr lpSecurityAttributes, 
                                  uint dwCreationDisposition, uint dwFlagsAndAttributes, 
                                  IntPtr hTemplateFile);
   
   [DllImport("kernel32.dll")]
   private static extern int GetFileSize(SafeFileHandle hFile, out int lpFileSizeHigh);
    
   // Define locals.
   private bool disposed = false;
   private SafeFileHandle safeHandle; 
   private long bufferSize;
   private int upperWord;
   
   public DisposableStreamResource(string filename)
   {
      if (filename == null)
         throw new ArgumentNullException("The filename cannot be null.");
      else if (filename == "")
         throw new ArgumentException("The filename cannot be an empty string.");
            
      IntPtr handle = CreateFile(filename, GENERIC_READ, FILE_SHARE_READ,
                                 IntPtr.Zero, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL,
                                 IntPtr.Zero);
      if (handle != INVALID_HANDLE_VALUE)
         safeHandle = new SafeFileHandle(handle, true);
      else
         throw new FileNotFoundException(String.Format("Cannot open '{0}'", filename));
      
      // Get file size.
      bufferSize = GetFileSize(safeHandle, out upperWord); 
      if (bufferSize == INVALID_FILE_SIZE)
         bufferSize = -1;
      else if (upperWord > 0) 
         bufferSize = (((long)upperWord) << 32) + bufferSize;
   }
   
   public long Size 
   { get { return bufferSize; } }

   public void Dispose()
   {
      Dispose(true);
      GC.SuppressFinalize(this);
   }           

   protected virtual void Dispose(bool disposing)
   {
      if (disposed) return;

      // Dispose of managed resources here.
      if (disposing)
         safeHandle.Dispose();
      
      // Dispose of any unmanaged resources not wrapped in safe handles.
      
      disposed = true;
   }  
}
Imports Microsoft.Win32.SafeHandles
Imports System.IO

Public Class DisposableStreamResource : Implements IDisposable
   ' Define constants.
   Protected Const GENERIC_READ As UInteger = &H80000000ui
   Protected Const FILE_SHARE_READ As UInteger = &H0000000i
   Protected Const OPEN_EXISTING As UInteger = 3
   Protected Const FILE_ATTRIBUTE_NORMAL As UInteger = &H80
   Protected INVALID_HANDLE_VALUE As New IntPtr(-1)
   Private Const INVALID_FILE_SIZE As Integer = &HFFFFFFFF
   
   ' Define Windows APIs.
   Protected Declare Function CreateFile Lib "kernel32" Alias "CreateFileA" (
                                         lpFileName As String, dwDesiredAccess As UInt32, 
                                         dwShareMode As UInt32, lpSecurityAttributes As IntPtr, 
                                         dwCreationDisposition As UInt32, dwFlagsAndAttributes As UInt32, 
                                         hTemplateFile As IntPtr) As IntPtr
   Private Declare Function GetFileSize Lib "kernel32" (hFile As SafeFileHandle, 
                                                        ByRef lpFileSizeHigh As Integer) As Integer
    
   ' Define locals.
   Private disposed As Boolean = False
   Private safeHandle As SafeFileHandle 
   Private bufferSize As Long 
   Private upperWord As Integer
   
   Public Sub New(filename As String)
      If filename Is Nothing Then
         Throw New ArgumentNullException("The filename cannot be null.")
      Else If filename = ""
         Throw New ArgumentException("The filename cannot be an empty string.")
      End If
            
      Dim handle As IntPtr = CreateFile(filename, GENERIC_READ, FILE_SHARE_READ,
                                        IntPtr.Zero, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL,
                                        IntPtr.Zero)
      If handle <> INVALID_HANDLE_VALUE Then
         safeHandle = New SafeFileHandle(handle, True)
      Else
         Throw New FileNotFoundException(String.Format("Cannot open '{0}'", filename))
      End If
      
      ' Get file size.
      bufferSize = GetFileSize(safeHandle, upperWord) 
      If bufferSize = INVALID_FILE_SIZE Then
         bufferSize = -1
      Else If upperWord > 0 Then 
         bufferSize = (CLng(upperWord) << 32) + bufferSize
      End If     
   End Sub
   
   Public ReadOnly Property Size As Long
      Get
         Return bufferSize
      End Get
   End Property
   
   Public Sub Dispose() _
              Implements IDisposable.Dispose
      Dispose(True)
      GC.SuppressFinalize(Me)
   End Sub           

   Protected Overridable Sub Dispose(disposing As Boolean)
      If disposed Then Exit Sub

      ' Dispose of managed resources here.
      If disposing Then
         safeHandle.Dispose()
      End If
      
      ' Dispose of any unmanaged resources not wrapped in safe handles.
      
      disposed = True
   End Sub  
End Class

Использование безопасного дескриптора для реализации шаблона удаления для производного классаUsing a safe handle to implement the dispose pattern for a derived class

В следующем примере показан шаблон удаления для производного класса DisposableStreamResource2, унаследованного от класса DisposableStreamResource, представленного в предыдущем примере.The following example illustrates the dispose pattern for a derived class, DisposableStreamResource2, that inherits from the DisposableStreamResource class presented in the previous example. Класс добавляет дополнительный метод WriteFileInfo и использует объект SafeFileHandle для создания экземпляра дескриптора записываемого файла.The class adds an additional method, WriteFileInfo, and uses a SafeFileHandle object to wrap the handle of the writable file.

using Microsoft.Win32.SafeHandles;
using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Threading;

public class DisposableStreamResource2 : DisposableStreamResource
{
   // Define additional constants.
   protected const uint GENERIC_WRITE = 0x40000000; 
   protected const uint OPEN_ALWAYS = 4;
   
   // Define additional APIs.
   [DllImport("kernel32.dll")]   
   protected static extern bool WriteFile(
                                SafeFileHandle safeHandle, string lpBuffer, 
                                int nNumberOfBytesToWrite, out int lpNumberOfBytesWritten,
                                IntPtr lpOverlapped);
   
   // Define locals.
   private bool disposed = false;
   private string filename;
   private bool created = false;
   private SafeFileHandle safeHandle;
   
   public DisposableStreamResource2(string filename) : base(filename)
   {
      this.filename = filename;
   }
   
   public void WriteFileInfo()
   { 
      if (! created) {
         IntPtr hFile = CreateFile(@".\FileInfo.txt", GENERIC_WRITE, 0, 
                                   IntPtr.Zero, OPEN_ALWAYS, 
                                   FILE_ATTRIBUTE_NORMAL, IntPtr.Zero);
         if (hFile != INVALID_HANDLE_VALUE)
            safeHandle = new SafeFileHandle(hFile, true);
         else
            throw new IOException("Unable to create output file.");

         created = true;
      }

      string output = String.Format("{0}: {1:N0} bytes\n", filename, Size);
      int bytesWritten;
      bool result = WriteFile(safeHandle, output, output.Length, out bytesWritten, IntPtr.Zero);                                     
   }

   protected override void Dispose(bool disposing)
   {
      if (disposed) return;
      
      // Release any managed resources here.
      if (disposing)
         safeHandle.Dispose();
      
      disposed = true;
      
      // Release any unmanaged resources not wrapped by safe handles here.
      
      // Call the base class implementation.
      base.Dispose(disposing);
   }
}
Imports Microsoft.Win32.SafeHandles
Imports System.IO

Public Class DisposableStreamResource2 : Inherits DisposableStreamResource
   ' Define additional constants.
   Protected Const GENERIC_WRITE As Integer = &H40000000 
   Protected Const OPEN_ALWAYS As Integer = 4
   
   ' Define additional APIs.
   Protected Declare Function WriteFile Lib "kernel32.dll" (
                              safeHandle As SafeFileHandle, lpBuffer As String, 
                              nNumberOfBytesToWrite As Integer, ByRef lpNumberOfBytesWritten As Integer,
                              lpOverlapped As Object) As Boolean
   
   ' Define locals.
   Private disposed As Boolean = False
   Private filename As String
   Private created As Boolean = False
   Private safeHandle As SafeFileHandle
   
   Public Sub New(filename As String)
      MyBase.New(filename)
      Me.filename = filename
   End Sub
   
   Public Sub WriteFileInfo() 
      If Not created Then
         Dim hFile As IntPtr = CreateFile(".\FileInfo.txt", GENERIC_WRITE, 0, 
                                          IntPtr.Zero, OPEN_ALWAYS, 
                                          FILE_ATTRIBUTE_NORMAL, IntPtr.Zero)
         If hFile <> INVALID_HANDLE_VALUE Then
            safeHandle = New SafeFileHandle(hFile, True)
         Else
            Throw New IOException("Unable to create output file.")
         End If
         created = True
      End If
      Dim output As String = String.Format("{0}: {1:N0} bytes {2}", filename, Size, 
                                           vbCrLf)
      WriteFile(safeHandle, output, output.Length, 0&, Nothing)                                     
   End Sub

   Protected Overloads Overridable Sub Dispose(disposing As Boolean)
      If disposed Then Exit Sub
      
      ' Release any managed resources here.
      If disposing Then
         safeHandle.Dispose()
      End If
      
      disposed = True
      ' Release any unmanaged resources not wrapped by safe handles here.
      
      ' Call the base class implementation.
      MyBase.Dispose(disposing)
   End Sub
End Class

См. такжеSee also