async (Referência de C#)async (C# Reference)

Use o modificador async para especificar que um método, uma expressão lambda ou um método anônimo é assíncrono.Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Se você usar esse modificador em um método ou expressão, ele será referido como um método assíncrono.If you use this modifier on a method or expression, it's referred to as an async method. O exemplo a seguir define um método assíncrono chamado ExampleMethodAsync:The following example defines an async method named ExampleMethodAsync:

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

Se você é iniciante em programação assíncrona ou não compreende como um método assíncrono usa o operador await para fazer trabalhos potencialmente longos sem bloquear o thread do chamador, leia a introdução em Programação assíncrona com async e await.If you're new to asynchronous programming or do not understand how an async method uses the await operator to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. O código a seguir é encontrado dentro de um método assíncrono e chama o método HttpClient.GetStringAsync:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Um método assíncrono será executado de forma síncrona até atingir sua primeira expressão await e, nesse ponto, ele será suspenso até que a tarefa aguardada seja concluída.An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. Enquanto isso, o controle será retornado ao chamador do método, como exibido no exemplo da próxima seção.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Se o método que a palavra-chave async modifica não contiver uma expressão ou instrução await, ele será executado de forma síncrona.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Um aviso do compilador o alertará sobre quaisquer métodos assíncronos que não contenham instruções await, pois essa situação poderá indicar um erro.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Consulte Aviso do compilador (nível 1) CS4014.See Compiler Warning (level 1) CS4014.

A palavra-chave async é contextual, pois ela será uma palavra-chave somente quando modificar um método, uma expressão lambda ou um método anônimo.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. Em todos os outros contextos, ela será interpretada como um identificador.In all other contexts, it's interpreted as an identifier.

ExemploExample

O exemplo a seguir mostra a estrutura e o fluxo de controle entre um manipulador de eventos assíncronos, StartButton_Click e um método assíncrono, ExampleMethodAsync.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. O resultado do método assíncrono é o número de caracteres de uma página da Web.The result from the async method is the number of characters of a web page. O código será adequado para um aplicativo do WPF (Windows Presentation Foundation) ou da Windows Store que você criar no Visual Studio, consulte os comentários do código para configurar o aplicativo.The code is suitable for a Windows Presentation Foundation (WPF) app or Windows Store app that you create in Visual Studio; see the code comments for setting up the app.

Você pode executar esse código no Visual Studio como um aplicativo do WPF (Windows Presentation Foundation) ou um aplicativo da Windows Store.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Você precisa de um controle de botão chamado StartButton e de um controle de caixa de texto chamado ResultsTextBox.You need a Button control named StartButton and a Textbox control named ResultsTextBox. Lembre-se de definir os nomes e o manipulador para que você tenha algo assim:Remember to set the names and handler so that you have something like this:

<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:To run the code as a WPF app:

  • Cole este código na classe MainWindow em MainWindow.xaml.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Adicione uma referência a System.Net.Http.Add a reference to System.Net.Http.
  • Adicione uma diretiva using a System.Net.Http.Add a using directive for System.Net.Http.

Para executar o código como um aplicativo da Windows Store:To run the code as a Windows Store app:

  • Cole este código na classe MainPage em MainPage.xaml.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Adicione usando diretivas para System.Net.Http e System.Threading.Tasks.Add using directives for System.Net.Http and 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 async e await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Para obter um exemplo completo do WPF que use elementos semelhantes, confira Instruções passo a passo: acessar a Web usando Async e Await.For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Tipos de RetornoReturn Types

Um método assíncrono pode conter os seguintes tipos de retorno:An async method can have the following return types:

  • Task
  • Task<TResult>
  • void.void. Os métodos async void geralmente são desencorajados para código que não são manipuladores de eventos, porque os chamadores não podem await esses métodos e devem implementar um mecanismo diferente para relatar a conclusão bem-sucedida ou condições de erro.async void methods are generally discouraged for code other than event handlers because callers cannot await those methods and must implement a different mechanism to report successful completion or error conditions.
  • Começando com o C# 7.0, qualquer tipo que tenha um método acessível GetAwaiter.Starting with C# 7.0, any type that has an accessible GetAwaiter method. O tipo System.Threading.Tasks.ValueTask<TResult> é um exemplo de uma implementação assim.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Ele está disponível ao adicionar o pacote NuGet System.Threading.Tasks.Extensions.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

O método assíncrono não pode declarar os parâmetros in, ref nem out e também não pode ter um valor retornado por referência, mas pode chamar métodos que tenham esses parâmetros.The async method can't declare any in, ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

Você especificará Task<TResult> como o tipo de retorno de um método assíncrono se a instrução return do método especificar um operando do tipo TResult.You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. Você usará Task se nenhum valor significativo for retornado quando o método for concluído.You use Task if no meaningful value is returned when the method is completed. Isto é, uma chamada ao método retorna uma Task, mas quando a Task for concluída, qualquer expressão await que esteja aguardando a Task será avaliada como void.That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

O tipo de retorno void é usado principalmente para definir manipuladores de eventos que exigem esse tipo de retorno.You use the void return type primarily to define event handlers, which require that return type. O chamador de um método assíncrono de retorno void não pode aguardá-lo e capturar exceções acionadas pelo método.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

A partir do C# 7.0, você retorna outro tipo, geralmente um tipo de valor, que tenha um método GetAwaiter para minimizar as alocações de memória nas seções do código críticas ao desempenho.Starting with C# 7.0, you return another type, typically a value type, that has a GetAwaiter method to minimize memory allocations in performance-critical sections of code.

Para obter mais informações e exemplos, consulte Tipos de retorno assíncronos.For more information and examples, see Async Return Types.

Consulte tambémSee also