Instrução using (Referência de C#)using statement (C# Reference)

Fornece uma sintaxe conveniente que garante o uso correto de objetos IDisposable.Provides a convenient syntax that ensures the correct use of IDisposable objects. A partir do C# 8,0, a using instrução garante o uso correto de IAsyncDisposable objetos.Beginning in C# 8.0, the using statement ensures the correct use of IAsyncDisposable objects.

ExemploExample

O exemplo a seguir mostra como usar a instrução using.The following example shows how to use the using statement.

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

using (var reader = new StringReader(manyLines))
{
    string? item;
    do {
        item = reader.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}

A partir do C# 8,0, você pode usar a seguinte sintaxe alternativa para a using instrução que não exige chaves:Beginning with C# 8.0, you can use the following alternative syntax for the using statement that doesn't require braces:

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

using var reader = new StringReader(manyLines);
string? item;
do {
    item = reader.ReadLine();
    Console.WriteLine(item);
} while(item != null);

ComentáriosRemarks

File e Font são exemplos de tipos gerenciados que acessam recursos não gerenciados (nesse caso, identificadores de arquivo de caso e contextos de dispositivo).File and Font are examples of managed types that access unmanaged resources (in this case file handles and device contexts). Há muitos outros tipos de recursos não gerenciados e tipos de biblioteca de classes que os encapsula.There are many other kinds of unmanaged resources and class library types that encapsulate them. Todos esses tipos devem implementar a IDisposable interface ou a IAsyncDisposable interface.All such types must implement the IDisposable interface, or the IAsyncDisposable interface.

Quando o tempo de vida de um objeto IDisposable é limitado a um único método, você deve declará-lo e instanciá-lo na instrução using.When the lifetime of an IDisposable object is limited to a single method, you should declare and instantiate it in the using statement. A instrução using chama o método Dispose no objeto da forma correta e (quando você o usa como mostrado anteriormente) ele também faz com que o objeto em si saia do escopo assim que Dispose é chamado.The using statement calls the Dispose method on the object in the correct way, and (when you use it as shown earlier) it also causes the object itself to go out of scope as soon as Dispose is called. Dentro do using bloco, o objeto é somente leitura e não pode ser modificado ou reatribuído.Within the using block, the object is read-only and can't be modified or reassigned. Se o objeto for implementado IAsyncDisposable em vez de IDisposable , a using instrução chamará o DisposeAsync e awaits o retornado ValueTask .If the object implements IAsyncDisposable instead of IDisposable, the using statement calls the DisposeAsync and awaits the returned ValueTask. Para obter mais informações sobre IAsyncDisposable o, consulte implementar um método DisposeAsync.For more information on IAsyncDisposable, see Implement a DisposeAsync method.

A using instrução garante que Dispose (ou DisposeAsync ) seja chamado mesmo se ocorrer uma exceção dentro do using bloco.The using statement ensures that Dispose (or DisposeAsync) is called even if an exception occurs within the using block. Você pode obter o mesmo resultado colocando o objeto dentro de um try bloco e, em seguida Dispose , chamando (ou DisposeAsync ) em um finally bloco; na verdade, é assim que a using instrução é convertida pelo compilador.You can achieve the same result by putting the object inside a try block and then calling Dispose (or DisposeAsync) in a finally block; in fact, this is how the using statement is translated by the compiler. O exemplo de código anterior se expande para o seguinte código em tempo de compilação (observe as chaves extras para criar o escopo limitado para o objeto):The code example earlier expands to the following code at compile time (note the extra curly braces to create the limited scope for the object):

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

{
    var reader = new StringReader(manyLines);
    try {
        string? item;
        do {
            item = reader.ReadLine();
            Console.WriteLine(item);
        } while(item != null);
    } finally
    {
        reader?.Dispose();
    }
}

A sintaxe mais recente da using instrução é convertida em código semelhante.The newer using statement syntax translates to similar code. O try bloco é aberto onde a variável é declarada.The try block opens where the variable is declared. O finally bloco é adicionado ao fechamento do bloco delimitador, normalmente no final de um método.The finally block is added at the close of the enclosing block, typically at the end of a method.

Para obter mais informações sobre a try - finally instrução, consulte o artigo Experimente-finally .For more information about the try-finally statement, see the try-finally article.

Várias instâncias de um tipo podem ser declaradas em uma única using instrução, conforme mostrado no exemplo a seguir.Multiple instances of a type can be declared in a single using statement, as shown in the following example. Observe que você não pode usar variáveis de tipo implícito ( var ) ao declarar várias variáveis em uma única instrução:Notice that you can't use implicitly typed variables (var) when you declare multiple variables in a single statement:

string numbers=@"One
Two
Three
Four.";
string letters=@"A
B
C
D.";

using (StringReader left = new StringReader(numbers),
    right = new StringReader(letters))
{
    string? item;
    do {
        item = left.ReadLine();
        Console.Write(item);
        Console.Write("    ");
        item = right.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}

Você pode combinar várias declarações do mesmo tipo usando a nova sintaxe introduzida com C# 8 também, conforme mostrado no exemplo a seguir:You can combine multiple declarations of the same type using the new syntax introduced with C# 8 as well, as shown in the following example:

string numbers=@"One
Two
Three
Four.";
string letters=@"A
B
C
D.";

using StringReader left = new StringReader(numbers),
    right = new StringReader(letters);
string? item;
do {
    item = left.ReadLine();
    Console.Write(item);
    Console.Write("    ");
    item = right.ReadLine();
    Console.WriteLine(item);
} while(item != null);

Você pode instanciar o objeto de recurso e, em seguida, passar a variável para a using instrução, mas essa não é uma prática recomendada.You can instantiate the resource object and then pass the variable to the using statement, but this isn't a best practice. Nesse caso, após o controle sair do bloco using, o objeto permanecerá no escopo, mas provavelmente não terá acesso a seus recursos não gerenciados.In this case, after control leaves the using block, the object remains in scope but probably has no access to its unmanaged resources. Em outras palavras, ele não é mais totalmente inicializado.In other words, it's not fully initialized anymore. Se você tentar usar o objeto fora do bloco using, corre o risco de causar o lançamento de uma exceção.If you try to use the object outside the using block, you risk causing an exception to be thrown. Por esse motivo, é melhor instanciar o objeto na using instrução e limitar seu escopo ao using bloco.For this reason, it's better to instantiate the object in the using statement and limit its scope to the using block.

string manyLines=@"This is line one
This is line two
Here is line three
The penultimate line is line four
This is the final, fifth line.";

var reader = new StringReader(manyLines);
using (reader)
{
    string? item;
    do {
        item = reader.ReadLine();
        Console.WriteLine(item);
    } while(item != null);
}
// reader is in scope here, but has been disposed

Para obter mais informações sobre como descartar objetos IDisposable, veja Usando objetos que implementam IDisposable.For more information about disposing of IDisposable objects, see Using objects that implement IDisposable.

Especificação da linguagem C#C# language specification

Para obter mais informações, consulte A instrução using na Especificação da linguagem C#.For more information, see The using statement in the C# Language Specification. A especificação da linguagem é a fonte definitiva para a sintaxe e o uso de C#.The language specification is the definitive source for C# syntax and usage.

Confira tambémSee also