Compartilhar via

Interface System.IDisposable

Este artigo fornece comentários complementares à documentação de referência para esta API.

O uso primário da IDisposable interface é liberar recursos não gerenciados. O coletor de lixo libera automaticamente a memória alocada a um objeto gerenciado quando esse objeto não é mais usado. No entanto, não é possível prever quando a coleta de lixo ocorrerá. Além disso, o coletor de lixo não tem conhecimento de recursos não gerenciados, como identificadores 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.

Aviso

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

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

Importante

No .NET Framework, o compilador C++ dá suporte ao descarte determinístico 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 implementação de um método de descarte .

Use um objeto que implementa IDisposable

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

  • Ao utilizar um construto de linguagem, como a instrução using em C# e Visual Basic, e a instrução use ou função using em F#.
  • Encapsulando a implementação IDisposable.Dispose em um bloco try/finally.

Observação

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

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

Se o idioma der suporte a um constructo, como a instrução using em C#, a instrução Using no Visual Basic ou a instrução use em F#, você poderá usá-la em vez de se chamar IDisposable.Dispose explicitamente. 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 instrução using (use expressão em F#) é, na verdade, uma conveniência sintática. No momento da compilação, o compilador da linguagem implementa a linguagem intermediária (IL) para um bloco try/finally.

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

O bloco Try/finally

Se sua linguagem de programação não oferecer suporte a uma construção como a instrução using no C# ou no Visual Basic ou a use instrução em F#, ou se preferir não usá-la, você poderá chamar a IDisposable.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 padrão try/finally, consulte Instrução Try...Catch...Finally, try-finally, Expressão try...finally ou Instrução try-finally.

Implementar IDisposable

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

Importante

Se você estiver definindo uma classe base que usa recursos não gerenciados e que tenha ou provavelmente tenha subclasses que devem ser descartadas, você deverá implementar o IDisposable.Dispose método e fornecer uma segunda sobrecarga, Disposeconforme discutido na 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 este padrão sempre que implementar IDisposable em qualquer tipo que não seja sealed (NotInheritable no Visual Basic).

  • Ele deve fornecer um método público, não virtual Dispose() e um método virtual Dispose(Boolean disposing) protegido.
  • O método Dispose() precisa chamar Dispose(true) e deve suprimir a finalização por razões de desempenho.
  • O tipo 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 substitua o método Object.Finalize.

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 Object.Finalize, sua classe deverá implementar o padrão a seguir.

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 de descarte da maneira a seguir:

  • Elas devem substituir Dispose(Boolean) e chamar a implementação Dispose(Boolean) da classe base.
  • 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 substituem apenas 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 método Object.Finalize.

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