Operador await - aguardar assincronamente a conclusão de uma tarefa

O await operador suspende a avaliação do método assíncrono de fechamento até que a operação assíncrona representada por seu operando seja concluída. Quando a operação assíncrona for concluída, o await operador retornará o resultado da operação, se houver. Quando o await operador é aplicado ao operando que representa uma operação já concluída, ele retorna o resultado da operação imediatamente sem a suspensão do método de encerramento. O await operador não bloqueia o thread que avalia o método assíncrono. Quando o operador suspende await o método assíncrono de delimitação, o controle retorna ao chamador do método.

A referência da linguagem C# documenta a versão mais recentemente lançada da linguagem C#. Contém também documentação inicial para funcionalidades em versões preliminares públicas para a próxima versão da linguagem.

A documentação identifica qualquer funcionalidade introduzida pela primeira vez nas últimas três versões da língua ou em pré-visualizações públicas atuais.

No exemplo a seguir, o HttpClient.GetByteArrayAsync método retorna a instância, que representa uma operação assíncrona Task<byte[]> que produz uma matriz de bytes quando ela é concluída. Até que a operação seja concluída, o operador suspende await o DownloadDocsMainPageAsync método. Quando DownloadDocsMainPageAsync é suspenso, o controle é retornado para o Main método, que é o chamador de DownloadDocsMainPageAsync. O Main método é executado até precisar do resultado da operação assíncrona executada DownloadDocsMainPageAsync pelo método. Quando GetByteArrayAsync obtém todos os bytes, o resto do DownloadDocsMainPageAsync método é avaliado. Depois disso, o resto do Main método é avaliado.

public class AwaitOperator
{
    public static async Task Main()
    {
        Task<int> downloading = DownloadDocsMainPageAsync();
        Console.WriteLine($"{nameof(Main)}: Launched downloading.");

        int bytesLoaded = await downloading;
        Console.WriteLine($"{nameof(Main)}: Downloaded {bytesLoaded} bytes.");
    }

    private static async Task<int> DownloadDocsMainPageAsync()
    {
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: About to start downloading.");

        var client = new HttpClient();
        byte[] content = await client.GetByteArrayAsync("https://learn.microsoft.com/en-us/");

        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: Finished downloading.");
        return content.Length;
    }
}
// Output similar to:
// DownloadDocsMainPageAsync: About to start downloading.
// Main: Launched downloading.
// DownloadDocsMainPageAsync: Finished downloading.
// Main: Downloaded 27700 bytes.

O operando de uma await expressão deve fornecer notificação quando uma tarefa for concluída. Em geral, um delegado é invocado quando a tarefa é concluída, com ou sem êxito. A await seção da especificação da linguagem C# fornece os detalhes sobre como essas notificações são implementadas.

O exemplo anterior usa o Main async. Para obter mais informações, consulte o operador await na seção Método principal.

Você pode usar o await operador somente em um método, expressão lambda ou método anônimo modificado pela palavra-chave async . Dentro de um método assíncrono, não pode usar o await operador no corpo de uma função local síncrona ou dentro do bloco de uma instrução lock. Nas versões anteriores da língua, também não se podia usar await num contexto inseguro . Na pré-visualização de C# 15, alterações de segurança à memória são permitidas await em contextos inseguros. A restrição restante é que não podes usar await no corpo ou no inicializador de uma fixed instrução; para essa regra e diagnósticos relacionados, vê Resolver erros e avisos em construções de código inseguro.

O operando do await operador é geralmente de um dos seguintes tipos .NET: Task, Task<TResult>, ValueTask, ou ValueTask<TResult>. No entanto, qualquer expressão aguardada pode ser o operando do await operador. Para obter mais informações, consulte a seção Expressões aguardadas da especificação da linguagem C#.

O tipo de expressão await t é TResult se o tipo de expressão t é Task<TResult> ou ValueTask<TResult>. Se o tipo de t é Task ou ValueTask, o tipo de await t é void. Em ambos os casos, se t lança uma exceção, await t relança a exceção.

Fluxos assíncronos e descartáveis

Use a instrução para consumir um fluxo assíncrono await foreach de dados. Para obter mais informações, consulte a foreach seção de instrução do artigo Instruções de iteração.

Você usa a await using instrução para trabalhar com um objeto descartável assincronamente, ou seja, um objeto de um tipo que implementa uma IAsyncDisposable interface. Para obter mais informações, consulte a seção Usando assíncrono descartável do artigo Implementar um método DisposeAsync.

await operador no método Main

O Main método serve como ponto de entrada para a aplicação. Pode devolver Task ou Task<int>, o que o torna assíncrono. Ao tornar o Main método assíncrono, pode usar o await operador no seu corpo. Em versões anteriores de C#, para garantir que o Main método espera a conclusão de uma operação assíncrona, recupera o valor da Task<TResult>.Result propriedade da Task<TResult> instância que o método assíncrono correspondente devolve. Para operações assíncronas que não produzem valor, chame o Task.Wait método. Para obter informações sobre como selecionar a versão de idioma, consulte Versão de idioma C#.

Especificação da linguagem C#

Para obter mais informações, consulte a seção Await expressions da especificação da linguagem C#.

Consulte também

• Operadores e expressões C#
• assíncrono
• Modelo de programação assíncrona de tarefas
• Programação assíncrona
• Passo a passo: acessando a Web usando async e await
• Tutorial: Gerar e consumir fluxos assíncronos
• Blog do .NET: Como async/await realmente funciona em C#