Await, opérateur (Visual Basic)

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

La méthode dans laquelle Await est utilisé doit avoir un modificateur asynchrone. Cette méthode, définie à l’aide du modificateur Async et contenant généralement une ou plusieurs expressions Await, est appelée méthode async.

En règle générale, la tâche à laquelle vous appliquez l’opérateur Await 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<TResult>.

Dans le code suivant, la méthode HttpClientGetByteArrayAsync renvoie un getContentsTask, un Task(Of Byte()). La tâche est une promesse de produire le tableau d’octets réel quand l’opération est terminée. L'opérateur Await est appliqué à getContentsTask pour suspendre l'exécution dans SumPageSizesAsync jusqu'à ce que getContentsTask soit terminé. Entre-temps, le contrôle revient à l'appelant de SumPageSizesAsync. Quand getContentsTask est terminé, l'expression Await s'évalue en 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

Si Await est appliqué au résultat d’un appel de méthode qui retourne un Task(Of TResult), le type de l’expression Await est TResult. Si Await est appliqué au résultat d’un appel de méthode qui retourne un Task, l’expression Await ne retourne pas de valeur. L'exemple suivant illustre la différence.

' 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 une instruction Await ne bloque pas le thread sur lequel elle s'exécute. Elle indique plutôt au compilateur de signer le reste de la méthode async, après l’expression Await, comme une continuation sur la tâche attendue. Le contrôle revient alors à l'appelant de la méthode async. Quand la tâche est terminée, elle appelle sa continuation et l'exécution de la méthode async reprend là où elle s'était arrêtée.

Une expression Await peut se produire uniquement dans le corps d'une méthode immédiatement englobante, une expression lambda marquée par un modificateur Async. Le terme Await sert de mot clé uniquement dans ce contexte. Partout ailleurs, il est interprété en tant qu'identificateur. Dans la méthode Async ou l’expression lambda, une expression Await ne peut pas se produire dans une expression de requête, dans le bloc Catch ou Finally d’une instruction Try... Catch...Finally, dans l’expression de 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 un Task ou Task<TResult>. Les propriétés de la tâche retournée comportent des informations sur son état et son historique. Celles-ci indiquent notamment si la tâche est terminée ou non, si la méthode async a levé une exception ou a été annulée et quel est le résultat final. L'opérateur Await accède à ces propriétés.

Si vous attendez une méthode async retournant des tâches qui lève une exception, l’opérateur Await lève de nouveau l’exception.

Si vous attendez une méthode async retournant des tâches qui est annulée, l’opérateur Await lève de nouveau un OperationCanceledException.

Une tâche qui se trouve dans un état d’erreur peut refléter plusieurs exceptions. Par exemple, la tâche peut être le résultat d'un appel à Task.WhenAll. Quand vous attendez une telle tâche, l’opération await lève à nouveau une seule des exceptions. Toutefois, vous ne pouvez pas prédire laquelle de ces exceptions est de nouveau levée.

Pour obtenir des exemples de gestion des erreurs dans les méthodes asynchrones, consultez l’instruction Try... Catch...Finally.

Exemple

L'exemple Windows Forms suivant illustre l'utilisation de Await dans une méthode async, WaitAsynchronouslyAsync. Comparez le comportement de cette méthode avec celui de WaitSynchronously. Sans opérateur Await, WaitSynchronously s’exécute de façon synchrone en dépit de l’utilisation du modificateur Async dans sa définition et d’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

• Programmation asynchrone avec Async et Await
• Procédure pas à pas : accès au web avec Async et Await
• Asynchrone