Compartilhar via


async (Referência de C#)

Use o modificador async para especificar que um método, expressão lambda ou método anônimo é assíncrono. Se você usar esse modificador em um método ou expressão, ele será referido como um método assíncrono.

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

Se você for iniciante em programação assíncrona ou não compreender como um método assíncrono usa a palavra-chave 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 (C# e Visual Basic).

string contents = await contentsTask;

O método 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. Enquanto isso, o controle será retornado ao chamador do método, como exibido no exemplo da próxima seção.

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. Um aviso do compilador o alertará sobre quaisquer métodos assíncronos que não contenham await, pois essa situação poderá indicar um erro. Consulte Aviso do compilador (nível 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. Em todos os outros contextos, ela será interpretada como um identificador.

Exemplo

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. O resultado do método assíncrono é o comprimento de um site baixado. O código será adequado para um aplicativo do Windows Presentation Foundation (WPF) ou da Windows Store que você criar no Visual Studio 2013; consulte os comentários do código para configurar o aplicativo.

// You can run this code in Visual Studio 2013 as a WPF app or a Windows Store app.
// You need a button (StartButton) and a textbox (ResultsTextBox).
// 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="TextBox" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>
        
// To run the code as a WPF app:
//    paste this code into the MainWindow class in MainWindow.xaml.cs,
//    add a reference to System.Net.Http, and
//    add a using directive for System.Net.Http.

// To run the code as a Windows Store app:
//    paste this code into the MainPage class in MainPage.xaml.cs, and
//    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}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("https://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;
}
// Output:
// Preparing to finish ExampleMethodAsync.
// Length: 53292

Importante

Para obter mais informações sobre as tarefas e o código executado enquanto aguarda uma tarefa, consulte Programação assíncrona com Async e Await (C# e Visual Basic). Para obter um exemplo completo do WPF que use elementos semelhantes, consulte Instruções passo a passo: acessando a Web e usando Async e Await (C# e Visual Basic).É possível baixar o código passo a passo de Exemplos de código do desenvolvedor.

Tipos de Retorno

Um método assíncrono pode conter um tipo de retorno Task, Task ou void. O método não pode declarar quaisquer parâmetros ref ou out, mas pode chamar métodos com tais parâmetros.

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. Você usará Task se nenhum valor significativo for retornado quando o método for concluído. 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.

O tipo de retorno void é usado principalmente para definir manipuladores de eventos que exigem esse tipo de retorno. O chamador de um método assíncrono de retorno void não pode aguardá-lo e capturar exceções acionadas pelo método.

Para obter mais informações e exemplos, consulte Tipos de retorno assíncronos (C# e Visual Basic).

Consulte também

Tarefas

Instruções passo a passo: acessando a Web e usando Async e Await (C# e Visual Basic)

Referência

await (Referência de C#)

AsyncStateMachineAttribute

Conceitos

Programação assíncrona com Async e Await (C# e Visual Basic)