Interface System.IDisposable

O principal uso da IDisposable interface é liberar recursos não gerenciados. O coletor de lixo libera automaticamente a memória alocada para um objeto gerenciado quando esse objeto não é mais usado. No entanto, não é possível prever quando ocorrerá a coleta de lixo. Além disso, o coletor de lixo não tem conhecimento de recursos não gerenciados, como alças de janela ou arquivos e fluxos abertos.

Use o Dispose método dessa interface para liberar explicitamente recursos não gerenciados em conjunto com o coletor de lixo. O consumidor de um objeto pode chamar esse método quando o objeto não é mais necessário.

Como a IDisposable.Dispose implementação é chamada pelo consumidor de um tipo quando os recursos de propriedade de uma instância não são mais necessários, você deve envolver o objeto gerenciado em um SafeHandle (a alternativa recomendada) ou substituir Object.Finalize para liberar recursos não gerenciados no caso de o consumidor esquecer de chamar Dispose.

Para obter uma discussão detalhada sobre como essa interface e o Object.Finalize método são usados, consulte os tópicos Garbage Collection e Implementing a Dispose Method .

Usar um objeto que implementa IDisposable

Se seu aplicativo simplesmente usa um objeto que implementa a IDisposable interface, você deve chamar a implementação do objeto quando terminar de IDisposable.Dispose usá-lo. Dependendo da sua linguagem de programação, você pode fazer isso de duas maneiras:

• Usando uma construção de linguagem como a using instrução em C# e Visual Basic e a use instrução ou using função em F#.
• Envolvendo a chamada para a IDisposable.Dispose implementação em um try/finally bloco.

A instrução C#, F# e Visual Basic Using

Se sua linguagem oferece suporte a uma construção como a instrução using em C#, a instrução Using no Visual Basic ou a instrução use em F#, você pode usá-la em vez de chamar IDisposable.Dispose explicitamente a si mesmo. O exemplo a seguir usa essa abordagem na definição de uma WordCount classe que preserva informações sobre um arquivo e o número de palavras nele.

using System;
using System.IO;
using System.Text.RegularExpressions;

public class WordCount
{
    private String filename = String.Empty;
    private int nWords = 0;
    private String pattern = @"\b\w+\b";

    public WordCount(string filename)
    {
        if (!File.Exists(filename))
            throw new FileNotFoundException("The file does not exist.");

        this.filename = filename;
        string txt = String.Empty;
        using (StreamReader sr = new StreamReader(filename))
        {
            txt = sr.ReadToEnd();
        }
        nWords = Regex.Matches(txt, pattern).Count;
    }

    public string FullName
    { get { return filename; } }

    public string Name
    { get { return Path.GetFileName(filename); } }

    public int Count
    { get { return nWords; } }
}

open System.IO
open System.Text.RegularExpressions

type WordCount(filename) =
    let txt = 
        if File.Exists filename |> not then
            raise (FileNotFoundException "The file does not exist.")

        use sr = new StreamReader(filename)
        sr.ReadToEnd()

    let pattern = @"\b\w+\b"
    
    let nWords = Regex.Matches(txt, pattern).Count

    member _.FullName = filename

    member _.Name = Path.GetFileName filename

    member _.Count = nWords

Imports System.IO
Imports System.Text.RegularExpressions

Public Class WordCount
   Private filename As String
   Private nWords As Integer
   Private pattern As String = "\b\w+\b" 

   Public Sub New(filename As String)
      If Not File.Exists(filename) Then
         Throw New FileNotFoundException("The file does not exist.")
      End If   
      
      Me.filename = filename
      Dim txt As String = String.Empty
      Using sr As New StreamReader(filename)
         txt = sr.ReadToEnd()
      End Using
      nWords = Regex.Matches(txt, pattern).Count
   End Sub
   
   Public ReadOnly Property FullName As String
      Get
         Return filename
      End Get   
   End Property
   
   Public ReadOnly Property Name As String
      Get
         Return Path.GetFileName(filename)
      End Get   
   End Property
   
   Public ReadOnly Property Count As Integer
      Get
         Return nWords
      End Get
   End Property
End Class

A using instrução (a use expressão em F#) é, na verdade, uma facilidade sintática. Em tempo de compilação, o compilador de linguagem implementa a linguagem intermediária (IL) para um try/finally bloco.

Para obter mais informações sobre a using instrução, consulte os tópicos Usando instrução ou usando instrução .

O bloco Try/Finally

Se sua linguagem de programação não oferece suporte a uma construção como a using instrução em C# ou Visual Basic, ou a use instrução em F#, ou se você preferir não usá-la, você pode chamar a IDisposable.Dispose implementação a finally partir do bloco de uma try/finally instrução. O exemplo a seguir substitui o using bloco no exemplo anterior por um try/finally bloco.

using System;
using System.IO;
using System.Text.RegularExpressions;

public class WordCount2
{
    private String filename = String.Empty;
    private int nWords = 0;
    private String pattern = @"\b\w+\b";

    public WordCount2(string filename)
    {
        if (!File.Exists(filename))
            throw new FileNotFoundException("The file does not exist.");

        this.filename = filename;
        string txt = String.Empty;
        StreamReader? sr = null;
        try
        {
            sr = new StreamReader(filename);
            txt = sr.ReadToEnd();
        }
        finally
        {
            if (sr != null) sr.Dispose();
        }
        nWords = Regex.Matches(txt, pattern).Count;
    }

    public string FullName
    { get { return filename; } }

    public string Name
    { get { return Path.GetFileName(filename); } }

    public int Count
    { get { return nWords; } }
}

open System.IO
open System.Text.RegularExpressions

type WordCount2(filename) =
    let txt = 
        if File.Exists filename |> not then
            raise (FileNotFoundException "The file does not exist.")

        let sr = new StreamReader(filename)
        try
            sr.ReadToEnd()
        finally
            sr.Dispose()

    let pattern = @"\b\w+\b"
    
    let nWords = Regex.Matches(txt, pattern).Count

    member _.FullName = filename

    member _.Name = Path.GetFileName filename

    member _.Count = nWords

Imports System.IO
Imports System.Text.RegularExpressions

Public Class WordCount2
   Private filename As String
   Private nWords As Integer
   Private pattern As String = "\b\w+\b" 

   Public Sub New(filename As String)
      If Not File.Exists(filename) Then
         Throw New FileNotFoundException("The file does not exist.")
      End If   
      
      Me.filename = filename
      Dim txt As String = String.Empty
      Dim sr As StreamReader = Nothing
      Try
         sr = New StreamReader(filename)
         txt = sr.ReadToEnd()
      Finally
         If sr IsNot Nothing Then sr.Dispose() 
      End Try
      nWords = Regex.Matches(txt, pattern).Count
   End Sub
   
   Public ReadOnly Property FullName As String
      Get
         Return filename
      End Get   
   End Property
   
   Public ReadOnly Property Name As String
      Get
         Return Path.GetFileName(filename)
      End Get   
   End Property
   
   Public ReadOnly Property Count As Integer
      Get
         Return nWords
      End Get
   End Property
End Class

Para obter mais informações sobre o try/finally padrão, consulte Tentar... Pegar... Finalmente Declaração, tente-finalmente, tente... finalmente expressão, ou tente-finalmente declaração.

Implementar IDisposable

Você deve implementar IDisposable se o seu tipo usa recursos não gerenciados diretamente ou se você deseja usar recursos descartáveis por conta própria. Os consumidores do seu tipo podem chamar sua IDisposable.Dispose implementação para liberar recursos quando a instância não for mais necessária. Para lidar com casos em que eles não conseguem chamar Dispose, você deve usar uma classe derivada de para encapsular os recursos não gerenciados, ou você deve substituir o SafeHandle método para um tipo de Object.Finalize referência. Em qualquer dos casos, utiliza-se o método Dispose para realizar a limpeza necessária depois de usar os recursos não geridos, como libertar, liberar ou redefinir esses recursos. Para obter mais informações sobre como implementar IDisposable.Disposeo , consulte a sobrecarga do método Dispose(bool).

IDisposable e a hierarquia de herança

Uma classe base com subclasses que devem ser descartáveis deve ser implementada IDisposable da seguinte forma. Você deve usar este padrão sempre que implementar IDisposable em qualquer tipo que não seja sealed (NotInheritable no Visual Basic).

• Deve fornecer um método público, não virtual Dispose() e um método virtual Dispose(Boolean disposing) protegido.
• O Dispose() método deve chamar Dispose(true) e, para melhorar o desempenho, deve suprimir a finalização.
• O tipo de base não deve incluir nenhum finalizador.

O fragmento de código a seguir reflete o padrão de descarte para classes base. Ele pressupõe que seu tipo não substitui o Object.Finalize método.

using System;
using System.IO;
using System.Runtime.InteropServices;

class BaseClass1 : IDisposable
{
    // Flag: Has Dispose already been called?
    bool disposed = false;
    // Instantiate a FileStream instance.
    FileStream fs = new FileStream("test.txt", FileMode.OpenOrCreate);

    // Public implementation of Dispose pattern callable by consumers.
    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }

    // Protected implementation of Dispose pattern.
    protected virtual void Dispose(bool disposing)
    {
        if (disposed)
            return;

        if (disposing)
        {
            fs.Dispose();
            // Free any other managed objects here.
            //
        }

        disposed = true;
    }
}

open System
open System.IO

type BaseClass1() =
    // Flag: Has Dispose already been called?
    let mutable disposed = false

    // Instantiate a FileStream instance.
    let fs = new FileStream("test.txt", FileMode.OpenOrCreate)

    interface IDisposable with
        // Public implementation of Dispose pattern callable by consumers.
        member this.Dispose() =
            this.Dispose true
            GC.SuppressFinalize this

    // Implementation of Dispose pattern.
    abstract Dispose: bool -> unit
    override _.Dispose(disposing) =
        if not disposed then
            if disposing then
                fs.Dispose()
                // Free any other managed objects here.
            disposed <- true

Imports System.IO
Imports System.Runtime.InteropServices

Class BaseClass1 : Implements IDisposable
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   ' Instantiate a FileStream instance.
   Dim fs As FileStream = New FileStream("test.txt", FileMode.OpenOrCreate)

   ' Public implementation of Dispose pattern callable by consumers.
   Public Sub Dispose() _
              Implements IDisposable.Dispose
      Dispose(disposing:=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
         fs.Dispose()
         ' Free any other managed objects here.
         '
      End If

      disposed = True
   End Sub
End Class

Se você substituir o Object.Finalize método, sua classe deverá implementar o seguinte padrão.

using System;

class BaseClass2 : IDisposable
{
    // Flag: Has Dispose already been called?
    bool disposed = false;

    // Public implementation of Dispose pattern callable by consumers.
    public void Dispose()
    {
        Dispose(disposing: 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;
    }

    ~BaseClass2()
    {
        Dispose(disposing: false);
    }
}

open System

type BaseClass2() =
    // Flag: Has Dispose already been called?
    let mutable disposed = false

    interface IDisposable with
        // Public implementation of Dispose pattern callable by consumers.
        member this.Dispose() =
            this.Dispose true
            GC.SuppressFinalize this

    // Implementation of Dispose pattern.
    abstract Dispose: bool -> unit
    override _.Dispose(disposing) =
        if not disposed then
            if disposing then
                // Free any other managed objects here.
                ()

            // Free any unmanaged objects here.
            disposed <- true

    override this.Finalize() =
        this.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(disposing:=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(disposing:=False)
   End Sub
End Class

As subclasses devem implementar o padrão descartável da seguinte forma:

• Eles devem substituir Dispose(Boolean), e chamar a implementação da classe base Dispose(Boolean).
• Eles podem fornecer um finalizador, se necessário. O finalizador deve chamar Dispose(false).

Observe que as classes derivadas não implementam a IDisposable interface e não incluem um método sem Dispose parâmetros. Eles apenas substituem o método Dispose(Boolean) da classe base.

O fragmento de código a seguir reflete o padrão de descarte para classes derivadas. Ele pressupõe que seu tipo não substitui o Object.Finalize método.

using System;
using System.IO;
using System.Runtime.InteropServices;

class MyDerivedClass : MyBaseClass
{
    // Flag: Has Dispose already been called?
    bool disposed = false;
    // Instantiate a FileStream instance.
    FileStream fs = new FileStream("test.txt", FileMode.OpenOrCreate);

    // Protected implementation of Dispose pattern.
    protected override void Dispose(bool disposing)
    {
        if (disposed)
            return;

        if (disposing)
        {
            fs.Dispose();
            // Free any other managed objects here.
            //
        }

        // Free any unmanaged objects here.
        //

        disposed = true;
        // Call base class implementation.
        base.Dispose(disposing);
    }
}

open Microsoft.Win32.SafeHandles
open System

type MyDerivedClass() =
    inherit MyBaseClass()
    
    // Flag: Has Dispose already been called?
    let mutable disposed = false
    // Instantiate a FileStream instance.
    let fs = new FileStream("test.txt", FileMode.OpenOrCreate)

    // Implementation of Dispose pattern.
    override _.Dispose(disposing) =
        if not disposed then
            if disposing then
                fs.Dispose()
                // Free any other managed objects here.

            // Free any unmanaged objects here.
            disposed <- true
            // Call base class implementation.
            base.Dispose disposing

Imports System.IO
Imports System.Runtime.InteropServices

Class DerivedClass2 : Inherits BaseClass2
   ' Flag: Has Dispose already been called?
   Dim disposed As Boolean = False
   ' Instantiate a FileStream instance.
   Dim fs As FileStream = New FileStream("test.txt", FileMode.OpenOrCreate)

   ' Protected implementation of Dispose pattern.
   Protected Overrides Sub Dispose(disposing As Boolean)
      If disposed Then Return

      If disposing Then
         fs.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