Compartilhar via

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

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 using instrução, a 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 como usar IAsyncDisposable instâncias, consulte a seção Using async descartável do artigo Implement a DisposeAsync method .

Você também pode usar uma using 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.

A linguagem C# faz referência a documentos da versão mais recentemente lançada da linguagem C#. Ele também contém a documentação inicial para recursos em visualizações públicas para a próxima versão do idioma.

A documentação identifica qualquer recurso introduzido pela primeira vez nas três últimas versões do idioma ou nas versões prévias públicas atuais.

Dica

Para descobrir quando um recurso foi introduzido pela primeira vez em C#, consulte o artigo sobre o histórico de versão da linguagem C#.

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

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 acessível, sem parâmetros e que tem um void tipo de retorno.

Um return dentro de um using bloco ainda garante o descarte. O compilador o reescreve em um try/finally, portanto, o recurso Dispose é sempre chamado antes que o método realmente retorne.

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 esse formulário:

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 você deve declarar uma variável descartável dentro da using instruçã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#.

Confira também

  • Last updated on