Instrução using – garantir o uso correto de objetos descartáveis

  • Artigo

A instrução using garante o uso correto de uma instância IDisposable:

var numbers = new List<int>();
using (StreamReader reader = File.OpenText("numbers.txt"))
{
    string line;
    while ((line = reader.ReadLine()) is not null)
    {
        if (int.TryParse(line, out int number))
        {
            numbers.Add(number);
        }
    }
}

Quando o controle sai do bloco da instrução using, uma instância adquirida IDisposable é descartada. Em particular, a instrução using garante que uma instância descartável seja descartada mesmo que ocorra uma exceção dentro do bloco da instrução using. No exemplo anterior, um arquivo aberto é fechado depois que todas as linhas são processadas.

Use a instrução await using para usar corretamente uma instância IAsyncDisposable:

await using (var resource = new AsyncDisposableExample())
{
    // Use the resource
}

Para obter mais informações sobre o uso de instâncias IAsyncDisposable, confira a seção Usando descartáveis assíncronos do artigo Implementar um método DisposeAsync.

Você também pode usar uma usingdeclaração que não exige chaves:

static IEnumerable<int> LoadNumbers(string filePath)
{
    using StreamReader reader = File.OpenText(filePath);
    
    var numbers = new List<int>();
    string line;
    while ((line = reader.ReadLine()) is not null)
    {
        if (int.TryParse(line, out int number))
        {
            numbers.Add(number);
        }
    }
    return numbers;
}

Quando declarada em uma declaração using, uma variável local é descartada no final do escopo em que é declarada. No exemplo anterior, o descarte ocorre no final de um método.

Uma variável declarada pela instrução ou declaração using é somente leitura. Não é possível reatribuí-la nem passá-la como um parâmetro ref ou out.

Você pode declarar várias instâncias do mesmo tipo em uma instrução using, como mostra o seguinte exemplo:

using (StreamReader numbersFile = File.OpenText("numbers.txt"), wordsFile = File.OpenText("words.txt"))
{
    // Process both files
}

Quando você declara várias instâncias em uma instrução using, elas são descartadas na ordem inversa da declaração.

Você também pode usar a instrução e a declaração using com uma instância de um struct ref que se ajusta ao padrão descartável. Ou seja, ele tem um método de instância Dispose, que é acessível, sem parâmetros e tem um tipo void de retorno.

A instrução using também pode ser da seguinte forma:

using (expression)
{
    // ...
}

em que expression produz uma instância descartável. O exemplo a seguir demonstra que:

StreamReader reader = File.OpenText(filePath);

using (reader)
{
    // Process file content
}

Aviso

No exemplo anterior, depois que o controle deixa a instrução using, uma instância descartável permanece no escopo enquanto ela já está descartada. Se você usar essa instância mais adiante, poderá encontrar uma exceção, por exemplo, ObjectDisposedException. É por isso que recomendamos declarar uma variável descartável dentro da instrução using ou com a declaração using.

Especificação da linguagem C#

Para obter mais informações, confira a seção A instrução using da especificação da linguagem C# e a nota de proposta sobre o "uso baseado em padrões" e "declarações using".

Confira também