usando declaração - garantir o uso correto de objetos descartáveis

  • Artigo

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

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 deixa o bloco da using instrução, uma instância adquirida IDisposable é descartada. Em particular, a using declaração garante que uma instância descartável seja descartada mesmo que ocorra uma exceção dentro do bloco da using declaração. No exemplo anterior, um arquivo aberto é fechado depois que todas as linhas são processadas.

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

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

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

Você também pode usar uma usingdeclaração que não exija 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 using declaração, uma variável local é descartada no final do escopo em que é declarada. No exemplo anterior, o descarte acontece no final de um método.

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

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

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

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

Você também pode usar a instrução e a using declaração com uma instância de uma ref struct que se encaixa no 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 de void retorno.

A using declaração também pode ter a seguinte forma:

using (expression)
{
    // ...
}

onde 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 using instrução, uma instância descartável permanece no escopo enquanto já está descartada. Se você usar essa instância ainda mais, poderá encontrar uma exceção, por exemplo, ObjectDisposedException. É por isso que recomendamos declarar uma variável descartável dentro da using declaração ou com a using declaração.

Especificação da linguagem C#

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

Consulte também