Interface System.IDisposable

Este artigo fornece observações complementares à documentação de referência para essa API.

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 método Dispose dessa interface explicitamente para liberar 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.

Aviso

É uma alteração de quebra para adicionar a interface a IDisposable uma classe existente. Como os consumidores pré-existentes do seu tipo não podem ligar Disposepara o , você não pode ter certeza de que os recursos não gerenciados mantidos pelo seu tipo serão liberados.

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

Importante

No .NET Framework, o compilador C++ oferece suporte à eliminação determinística de recursos e não permite a implementação direta do Dispose método.

Para obter uma discussão detalhada sobre como essa interface e o Object.Finalize método são usados, consulte os tópicos Coleta de lixo e Implementando um método de descarte.

Usar um objeto que implementa IDisposable

Se seu aplicativo simplesmente usa um objeto que implementa a interface, você deve chamar a IDisposable 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 instrução em C# e Visual Basic, e a usinguse instrução ou using função em F#.
• Encapsulando a chamada para a IDisposable.Dispose implementação em um try/finally bloco.

Observação

A documentação para tipos que implementam IDisposable anota esse fato e inclui um lembrete para chamar sua Dispose implementação.

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 classe que preserva informações sobre um arquivo e o número de WordCount 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 (use expressão em F#) é, na verdade, uma conveniência sintática. No momento da 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 oferecer suporte a uma construção como a instrução em C# ou Visual Basic, ou a instrução em F#, ou se você preferir não usá-la, você pode chamar a usinguseIDisposable.Dispose implementação do finally 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 tentativa de finalmente Declaração.

Implementar IDisposable

Você deve implementar IDisposable se seu tipo usa recursos não gerenciados diretamente ou se você mesmo deseja usar recursos descartáveis. 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 substituir o Object.Finalize método para um tipo de SafeHandle referência. Em ambos os casos, você usa o método para executar a Dispose limpeza necessária depois de usar os recursos não gerenciados, como liberar, liberar ou redefinir os recursos não gerenciados. Para obter mais informações sobre como implementar IDisposable.Disposeo , consulte a sobrecarga do método Dispose(bool).

Importante

Se você estiver definindo uma classe base que usa recursos não gerenciados e que tem, ou provavelmente terá, subclasses que devem ser descartadas, você deve implementar o IDisposable.Dispose método e fornecer uma segunda sobrecarga de , conforme discutido Disposena próxima seção.

IDisposable e a hierarquia de herança

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

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

O fragmento de código a seguir reflete o padrão de descarte para classes base. Ele pressupõe que seu tipo não substitua 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 método, sua classe deverá implementar o Object.Finalize 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 maneira:

• Eles devem substituir Dispose(Boolean) e chamar a implementação da classe Dispose(Boolean) base.
• Eles podem fornecer um finalizador, se necessário. O finalizador deve ligar para 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 de classe Dispose(Boolean) 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 substitua 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