usando a declaração (Referência C#)

  • Artigo
  • 4 minutos para ler

Fornece uma sintaxe conveniente que garante o uso correto de IDisposable objetos. A partir de C# 8.0, a using declaração garante a utilização correta de IAsyncDisposable objetos.

Exemplo

O exemplo a seguir mostra como utilizar a using declaração.

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 declaração de utilização, introduzida em C# 8.0, não requer aparelhos:

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);

Observações

File e Font são exemplos de tipos geridos que acedem a recursos não geridos (neste caso, alças de ficheiros e contextos de dispositivo). Existem muitos outros tipos de recursos não geridos e tipos de bibliotecas de classes que os encapsulam. Todos estes tipos devem implementar a IDisposable interface, ou a IAsyncDisposable interface.

Quando a vida útil de um IDisposable objeto se limita a um único método, deve declará-lo e instantaneamente na using declaração ou using declaração. A using declaração chama o Dispose método do objeto da forma correta quando este se desesmes. A using declaração faz com que o objeto saia do alcance assim que Dispose for chamado. Dentro do using bloco, o objeto é apenas de leitura e não pode ser modificado ou reatribuído. Uma variável declarada com uma using declaração é apenas leitura. Se o objeto implementar IAsyncDisposable em vez de IDisposable, qualquer formulário using chama o DisposeAsync e awaits o devolvido ValueTask. Para obter mais informações sobre IAsyncDisposable, consulte implementar um método DisposeAsync.

Ambas as using formas asseguram que Dispose (ou DisposeAsync) é chamada mesmo que ocorra uma exceção dentro do using bloco. Pode obter o mesmo resultado colocando o objeto dentro de um try bloco e, em seguida, chamando Dispose (ou DisposeAsync) num finally bloco; na verdade, é assim que a using declaração e a using declaração são traduzidas pelo compilador. O exemplo de código anteriormente expande-se para o seguinte código no tempo de compilação (note os aparelhos curly extra para criar o âmbito limitado para o objeto):

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 de declaração mais using recente traduz-se em código semelhante. O try bloco abre onde a variável é declarada. O finally bloco é adicionado no fecho do bloco de enclosing, tipicamente no final de um método.

Para mais informações sobre a try-finally declaração, consulte o artigo try-finally .

Várias instâncias de um tipo podem ser declaradas numa única using declaração, como mostra o exemplo seguinte. Note que não pode usar variáveis implicitamente dactilografadas (var) quando declara várias variáveis numa única declaração:

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);
}

Pode combinar várias declarações do mesmo tipo utilizando a sintaxe de declaração introduzida também com C# 8, como mostra o seguinte exemplo:

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);

Pode instantaneaizar o objeto de recurso e depois passar a variável para a using declaração, mas esta não é uma boa prática. Neste caso, após o controlo deixar o using bloco, o objeto permanece no âmbito, mas provavelmente não tem acesso aos seus recursos não geridos. Por outras palavras, já não está totalmente inicializado. Se tentar utilizar o objeto fora do bloco, corre o using risco de causar uma exceção. Por esta razão, é melhor instantanear o objeto na declaração e limitar o using seu âmbito ao using bloco.

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 a eliminação de IDisposable objetos, consulte utilizando objetos que implementem iDisposable.

Especificação linguística C#

Para obter mais informações, consulte a declaração de utilização na especificação c. idiomas. A especificação linguística é a fonte definitiva para a sintaxe e utilização C#.

Ver também