Await, opérateur (Visual Basic)

Vous appliquez l'opérateur d'un Await à un opérande dans une méthode asynchrone ou une expression lambda pour interrompre l'exécution de la méthode jusqu'à ce que la tâche attendue se termine. La tâche représente le travail en cours.

La méthode dans laquelle Await est utilisé doit avoir un modificateur d' Async. Une telle méthode, définie en utilisant le modificateur Async, et contenant généralement une ou plusieurs expressions Await, est appelée méthode asynchrone.

Notes

Les mots clés Async et Await ont été introduits dans Visual Studio 2012.Pour une présentation de la programmation asynchrone, consultez Programmation asynchrone avec Async et Await (C# et Visual Basic).

Généralement, la tâche à laquelle l'opérateur Await est appliqué est la valeur de retour d'un appel à une méthode qui implémente le modèle asynchrone basé sur des tâches, c'est à dire, un Task ou un Task.

Dans le code suivant, la méthode HttpClient GetByteArrayAsync retourne getContentsTask, une Task(Of Byte()). La tâche est la promesse de produire le tableau d'octets réel lorsque l'opération est terminée. L'opérateur Await est appliqué à getContentsTask pour interrompre l'exécution dans SumPageSizesAsync jusqu'à ce que getContentsTask soit terminé. Dans le même temps, le contrôle retourne à l'appelant de SumPageSizesAsync, . Lorsque getContentsTask est terminé, l'expression Await correspond à un tableau d'octets.

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

Important

Pour obtenir un exemple complet, consultez Procédure pas à pas : accès au Web avec Async et Await (C# et Visual Basic).Vous pouvez télécharger l'exemple à partir de Exemples de code du développeur sur le site Web Microsoft.L'exemple se trouve dans le projet AsyncWalkthrough_HttpClient.

Si Await est appliqué au résultat d'un appel de méthode qui retourne une Task(Of TResult), le type de l'expression Await est void. Si Await est appliqué au résultat d'un appel de méthode qui retourne une Task, l'expression Await ne retourne pas de valeur. La différence est illustrée dans l'exemple suivant.

' 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()

Une expression ou un état Await ne bloque pas le thread sur lequel elle s'exécute. À la place, cela provoque la connexion du compilateur au reste de la méthode async, après l'expression Await, comme une continuation sur la tâche attendue. Contrôle, puis retourne à l'appelant de la méthode async. Lorsque la tâche se termine, elle appelle sa continuation, et l'exécution de la méthode async reprend où elle a été arrêtée.

Une expression Await ne peut se produire que dans le corps d'une méthode immédiatement englobante, ou d'une expression lambda, ou d'une méthode anonyme qui est marquée par un modificateur Async. Le terme await sert de mot clé uniquement dans ce contexte. Ailleurs, il est interprété comme un identificateur. Dans la méthode async ou l'expression lambda, une expression Await ne peut pas apparaître dans une expression de requête, dans un bloc catch ou finally d'une instruction Try… Catch… Finally, dans l'expression variable de contrôle de boucle d'une boucle For ou For Each, ou dans le corps d'une instruction SyncLock.

Exceptions

La plupart des méthodes async retournent Task ou Task. Les propriétés de la tâche retournée contiennent des informations sur son état et son historique, par exemple si la tâche est terminée, si la méthode async a provoqué une exception ou a été annulée ainsi que le résultat final. L'opérateur Await accède à ces propriétés.

Si vous attendez une méthode asynchrone de retour de tâche qui provoque une exception, l'opérateur Await relève l'exception.

Si vous attendez une méthode asynchrone de retour de tâche qui est annulée, l'opérateur Await relève une OperationCanceledException.

Une tâche unique avec un état d'erreur peut refléter plusieurs exceptions. Par exemple, la tâche peut être le résultat d'un appel à Task.WhenAll. Lorsque vous attendez une telle tâche, l'opération await lève à nouveau une seule des exceptions. Toutefois, vous ne pouvez pas prédire quelles exceptions seront immédiatement levées.

Pour obtenir des exemples de gestion des erreurs dans des méthodes async, consultez Try...Catch...Finally, instruction (Visual Basic).

Exemple

L'exemple Windows Forms suivant illustre l'utilisation d'Await dans une méthode async, WaitAsynchronouslyAsync. Comparez le comportement de cette méthode avec le comportement de WaitSynchronously. Sans un opérateur Await appliqué à une tâche, WaitSynchronously s'exécute de façon synchrone malgré l'utilisation du modificateur Async dans sa définition et un appel à Thread.Sleep dans son corps.

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

Voir aussi

Tâches

Procédure pas à pas : accès au Web avec Async et Await (C# et Visual Basic)

Référence

Async (Visual Basic)

Concepts

Programmation asynchrone avec Async et Await (C# et Visual Basic)