Partilhar via

assíncrono (referência a C#)

Use o async modificador para especificar que um método, expressão lambda ou método anônimo é assíncrono. Se usares este modificador num método ou expressão, crias um método assíncrono. O exemplo a seguir define um método assíncrono chamado ExampleMethodAsync:

public async Task<int> ExampleMethodAsync()
{
    //...
}

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.

Sugestão

Para saber quando uma funcionalidade foi introduzida pela primeira vez em C#, consulte o artigo sobre o histórico de versões da linguagem C#.

Se és novo na programação assíncrona ou não compreendes como um método assíncrono usa o await operador para realizar trabalhos potencialmente longos sem bloquear a thread do chamador, lê a introdução em Programação Assíncrona com assíncrono e await. O código a seguir é encontrado dentro de um método assíncrono e chama o HttpClient.GetStringAsync método:

string contents = await httpClient.GetStringAsync(requestUrl);

Um método assíncrono corre de forma síncrona até atingir a sua primeira await expressão. Nesse momento, o método é suspenso até que a tarefa aguardada seja concluída. Enquanto isso, o controle retorna ao chamador do método, como mostra o exemplo na próxima seção.

Se o método que a async palavra-chave modifica não contém uma await expressão ou instrução, o método é executado de forma síncrona. Um aviso do compilador alerta você para quaisquer métodos assíncronos que não contenham await instruções, porque essa situação pode indicar um erro. Consulte Aviso do compilador (nível 1) CS4014.

A async palavra-chave é contextual. É uma palavra-chave apenas quando modifica um método, uma expressão lambda ou um método anónimo. Em todos os outros contextos, o compilador interpreta-o como um identificador.

O exemplo a seguir mostra a estrutura e o fluxo de controle entre um manipulador StartButton_Clickde eventos assíncrono e um método assíncrono, ExampleMethodAsync. O resultado do método assíncrono é o número de caracteres de uma página da Web. O código é adequado para uma aplicação Windows Presentation Foundation (WPF) ou para uma aplicação da Windows Store que cria no Visual Studio. Veja os comentários do código para configurar a aplicação.

Você pode executar esse código no Visual Studio como um aplicativo do Windows Presentation Foundation (WPF) ou um aplicativo da Windows Store. Você precisa de um controle Button chamado StartButton e um controle Textbox chamado ResultsTextBox. Lembre-se de definir os nomes e o manipulador para que você tenha algo assim:

<Button Content="Button" HorizontalAlignment="Left" Margin="88,77,0,0" VerticalAlignment="Top" Width="75"
        Click="StartButton_Click" Name="StartButton"/>
<TextBox HorizontalAlignment="Left" Height="137" Margin="88,140,0,0" TextWrapping="Wrap"
         Text="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>

Para executar o código como um aplicativo WPF:

  • Cole MainWindow esse código na classe em MainWindow.xaml.cs.
  • Adicione uma referência a System.Net.Http.
  • Adicione uma using diretiva para System.Net.Http.

Para executar o código como um aplicativo da Windows Store:

  • Cole esse código na MainPage classe no MainPage.xaml.cs.
  • Adicione using diretivas para System.Net.Http e System.Threading.Tasks.
private async void StartButton_Click(object sender, RoutedEventArgs e)
{
    // ExampleMethodAsync returns a Task<int>, which means that the method
    // eventually produces an int result. However, ExampleMethodAsync returns
    // the Task<int> value as soon as it reaches an await.
    ResultsTextBox.Text += "\n";

    try
    {
        int length = await ExampleMethodAsync();
        // Note that you could put "await ExampleMethodAsync()" in the next line where
        // "length" is, but due to when '+=' fetches the value of ResultsTextBox, you
        // would not see the global side effect of ExampleMethodAsync setting the text.
        ResultsTextBox.Text += String.Format("Length: {0:N0}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("http://msdn.microsoft.com")).Length;
    ResultsTextBox.Text += "Preparing to finish ExampleMethodAsync.\n";
    // After the following return statement, any method that's awaiting
    // ExampleMethodAsync (in this case, StartButton_Click) can get the
    // integer result.
    return exampleInt;
}
// The example displays the following output:
// Preparing to finish ExampleMethodAsync.
// Length: 53292

Importante

Para obter mais informações sobre tarefas e o código que é executado enquanto aguarda uma tarefa, consulte Programação assíncrona com assíncrono e aguarda. Para obter um exemplo de console completo que usa elementos semelhantes, consulte Processar tarefas assíncronas à medida que são concluídas (C#).

Tipos de devolução

Um método assíncrono pode ter os seguintes tipos de retorno:

  • Task
  • Task<TResult>
  • void. De um modo geral, evite usar async void métodos para código que não sejam os gestores de eventos, pois os chamadores não await conseguem esses métodos e têm de implementar um mecanismo diferente para reportar conclusão bem-sucedida ou condições de erro.
  • Qualquer tipo que tenha um método acessível GetAwaiter . O System.Threading.Tasks.ValueTask<TResult> tipo é uma dessas implementações. Está disponível adicionando o pacote System.Threading.Tasks.ExtensionsNuGet.

O método assíncrono não pode declarar quaisquer in, ref, ref readonly, ou out parâmetros, nem pode ter um valor de retorno de referência. No entanto, pode chamar métodos que tenham tais parâmetros.

Especifique Task<TResult> como tipo de retorno de um método assíncrono se a instrução de retorno do método especificar um operando do tipo TResult. Use Task se o método não devolver valor significativo quando estiver concluído. Ou seja, uma chamada para o método retorna um Task, mas quando o Task é concluído, qualquer await expressão que está aguardando a Task avaliação para void. Use o void tipo de retorno principalmente para definir gestores de eventos, que requerem esse tipo de retorno. O chamador de um voidmétodo assíncrono -return não pode esperar e não pode capturar exceções que o método lança. Devolva outro tipo, tipicamente um tipo de valor, que tenha um GetAwaiter método para minimizar alocações de memória em secções de código críticas para o desempenho.

Para obter mais informações e exemplos, consulte Tipos de retorno assíncronos.

Consulte também

  • Last updated on