Operador Await (Visual Basic)

Você aplica o operador de Await a um operando em um método assíncrono ou na expressão lambda para suspender a execução do método até que a tarefa deve terminar. A tarefa representa um trabalho em andamento.

O método no qual Await é usado deve ter um modificador de Async . Esse método, definido usando o modificador de Async , e geralmente contendo uma ou mais expressões de Await , é conhecido como um método assíncrono.

Dica

As palavras-chave de Async e de Await foram introduzidas no Visual Studio 2012.Para uma introdução de programação async, consulte Programação assíncrona com Async e Await (C# e Visual Basic).

Normalmente, a tarefa para que você aplica o operador de Await é o valor de retorno de uma chamada a um método que implementa Padrão assíncrono baseado chave, isto é, Task ou Task.

No código a seguir, o método GetByteArrayAsync de HttpClient retorna getContentsTask, Task(Of Byte()). A tarefa é uma promessa de gerar a matriz real de bytes quando a operação é concluída. O operador de Await é aplicado a getContentsTask para suspender a execução em SumPageSizesAsync até que getContentsTask seja concluída. Enquanto isso, o controle é retornado ao chamador de SumPageSizesAsync. Quando getContentsTask termina, a expressão Await é avaliada como uma matriz de bytes.

Private Async Function SumPageSizesAsync() As Task

    ' To use the HttpClient type in desktop apps, you must include a using directive and add a 
    ' reference for the System.Net.Http namespace.
    Dim client As HttpClient = New HttpClient() 
    ' . . . 
    Dim getContentsTask As Task(Of Byte()) = client.GetByteArrayAsync(url)
    Dim urlContents As Byte() = Await getContentsTask

    ' Equivalently, now that you see how it works, you can write the same thing in a single line.
    'Dim urlContents As Byte() = Await client.GetByteArrayAsync(url)
    ' . . .
End Function

Importante

Para um exemplo completo, consulte Instruções passo a passo: acessando a Web e usando Async e Await (C# e Visual Basic).Você pode baixar o exemplo de Exemplos de código do desenvolvedor no site da Microsoft.O exemplo está no projeto de AsyncWalkthrough_HttpClient.

Se Await é aplicado ao resultado de uma chamada de método que retorna Task(Of TResult), o tipo da expressão de Await é TResult. Se Await é aplicado ao resultado de uma chamada de método que retorna Task, a expressão de Await não retorna um valor. O exemplo a seguir ilustra a diferença.

' Await used with a method that returns a Task(Of TResult).
Dim result As TResult = Await AsyncMethodThatReturnsTaskTResult()

' Await used with a method that returns a Task.
Await AsyncMethodThatReturnsTask()

Uma expressão ou uma declaração de Await não bloco o thread em que está executando. Em vez disso, faz com que o compilador assine anterior o restante do método de async, após a expressão de Await , como uma continuação na tarefa esperada. Então, o controle retorna para o chamador do método async. Quando a tarefa termina, ela chama sua continuação, e a execução do método de async continua onde parou.

Uma expressão de Await pode ocorrer apenas no corpo de um método imediatamente incluindo ou de expressão lambda que é sinalizado por um modificador de Async . O termo espera serve como uma palavra-chave somente nesse contexto. Em outro lugar, é interpretado como um identificador. No método de async ou da expressão lambda, uma expressão de Await não pode ocorrer em uma expressão de consulta, no bloco de catch ou de finally de uma instrução de Try… catch… finally , na expressão variável de controle de loop de um loop de For ou de For Each , ou no corpo de uma instrução de SyncLock .

Exceções

A maioria dos métodos assíncronos retornam Task ou Task. As propriedades da tarefa retornada transportam informações sobre seus status e histórico como, por exemplo, se a tarefa está concluída, se o método de async causou uma exceção ou foi cancelado, e o qual é o resultado final. O operador de Await acessa essas propriedades.

Se você aguardar um método assíncrono de retorno de tarefa que cause uma exceção, o operador Await relançará a exceção.

Se você pretende ajustar retornando um método de async que foi cancelado, a qual o operador de AwaitOperationCanceledException.

Uma única tarefa que apresentar defeito pode refletir em diversas exceções. Por exemplo, a tarefa pode ser resultado de uma chamada para Task.WhenAll. Quando você espera uma tarefa, a operação de espera relança apenas uma das exceções. No entanto, não é possível prever qual das exceções será lançada novamente.

Para exemplos de tratamento de erro em métodos assíncronos, consulte Instrução Try...Catch...Finally (Visual Basic).

Exemplo

O seguinte exemplo do Windows Forms ilustra o uso de Await em um método assíncrono, WaitAsynchronouslyAsync. Destaque o comportamento do método com o comportamento de WaitSynchronously. Sem um operador de Await , WaitSynchronously executa forma independentemente do modificador de Async em sua definição e em uma chamada a Thread.Sleep no corpo.

Private Async Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
    ' Call the method that runs asynchronously.
    Dim result As String = Await WaitAsynchronouslyAsync()

    ' Call the method that runs synchronously.
    'Dim result As String = Await WaitSynchronously()

    ' Display the result.
    TextBox1.Text &= result
End Sub

' The following method runs asynchronously. The UI thread is not
' blocked during the delay. You can move or resize the Form1 window 
' while Task.Delay is running.
Public Async Function WaitAsynchronouslyAsync() As Task(Of String)
    Await Task.Delay(10000)
    Return "Finished"
End Function

' The following method runs synchronously, despite the use of Async.
' You cannot move or resize the Form1 window while Thread.Sleep
' is running because the UI thread is blocked.
Public Async Function WaitSynchronously() As Task(Of String)
    ' Import System.Threading for the Sleep method.
    Thread.Sleep(10000)
    Return "Finished"
End Function

Consulte também

Tarefas

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

Referência

Async (Visual Basic)

Conceitos

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