Await, opérateur (Visual Basic)Await Operator (Visual Basic)

Vous appliquez l' Await opérateur à 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.You apply the Await operator to an operand in an asynchronous method or lambda expression to suspend execution of the method until the awaited task completes. La tâche représente un travail en cours.The task represents ongoing work.

La méthode dans laquelle Await est utilisé doit avoir un modificateur Async .The method in which Await is used must have an Async modifier. 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.Such a method, defined by using the Async modifier, and usually containing one or more Await expressions, is referred to as an async method.

Notes

Les mots clés Async et Await ont été introduits dans Visual Studio 2012.The Async and Await keywords were introduced in Visual Studio 2012. Pour une introduction à la programmation asynchrone, consultez programmation asynchrone avec Async et await.For an introduction to async programming, see Asynchronous Programming with Async and Await.

En général, la tâche à laquelle vous appliquez Await l’opérateur est la valeur de retour d’un appel à une méthode qui implémente le modèle asynchrone basé sur des tâches, Task c’est-à-dire Task<TResult>, ou.Typically, the task to which you apply the Await operator is the return value from a call to a method that implements the Task-Based Asynchronous Pattern, that is, a Task or a Task<TResult>.

Dans le code suivant, la HttpClient méthode GetByteArrayAsync retourne getContentsTask, a Task(Of Byte()).In the following code, the HttpClient method GetByteArrayAsync returns getContentsTask, a Task(Of Byte()). La tâche est une promesse de produire le tableau d’octets réel lorsque l’opération est terminée.The task is a promise to produce the actual byte array when the operation is complete. L'opérateur Await est appliqué à getContentsTask pour suspendre l'exécution dans SumPageSizesAsync jusqu'à ce que getContentsTask soit terminé.The Await operator is applied to getContentsTask to suspend execution in SumPageSizesAsync until getContentsTask is complete. Entre-temps, le contrôle revient à l'appelant de SumPageSizesAsync.In the meantime, control is returned to the caller of SumPageSizesAsync. Quand getContentsTask est terminé, l'expression Await s'évalue en tableau d'octets.When getContentsTask is finished, the Await expression evaluates to a byte array.

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 un exemple complet, consultez Procédure pas à pas : Accès au web avec Async et Await.For the complete example, see Walkthrough: Accessing the Web by Using Async and Await. Vous pouvez télécharger l’exemple à partir des exemples de code pour les développeurs sur le site web de Microsoft.You can download the sample from Developer Code Samples on the Microsoft website. L'exemple est dans le projet AsyncWalkthrough_HttpClient.The example is in the AsyncWalkthrough_HttpClient project.

Si Await est appliqué au résultat d’un appel de méthode qui retourne un Task(Of TResult), le type de l' Await expression est TResult.If Await is applied to the result of a method call that returns a Task(Of TResult), the type of the Await expression is TResult. Si Await est appliqué au résultat d’un appel de méthode qui retourne un Task, l' Await expression ne retourne pas de valeur.If Await is applied to the result of a method call that returns a Task, the Await expression doesn't return a value. L'exemple suivant illustre la différence.The following example illustrates the difference.

' 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 Await expression ou une instruction ne bloque pas le thread sur lequel elle s’exécute.An Await expression or statement does not block the thread on which it is executing. Au lieu de cela, il force le compilateur à inscrire le reste de la méthode Async, Await après l’expression, en tant que continuation sur la tâche attendue.Instead, it causes the compiler to sign up the rest of the async method, after the Await expression, as a continuation on the awaited task. Le contrôle revient alors à l'appelant de la méthode async.Control then returns to the caller of the async method. 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.When the task completes, it invokes its continuation, and execution of the async method resumes where it left off.

Une Await expression peut se produire uniquement dans le corps d’une méthode immédiatement englobante ou d’une expression lambda qui est Async marquée par un modificateur.An Await expression can occur only in the body of an immediately enclosing method or lambda expression that is marked by an Async modifier. Le terme await sert de mot clé uniquement dans ce contexte.The term Await serves as a keyword only in that context. Partout ailleurs, il est interprété en tant qu'identificateur.Elsewhere, it is interpreted as an identifier. Dans une méthode Async ou une expression lambda, Await une expression ne peut pas se produire dans une expression catch de finally requête, dans le bloc ou d’une tentative... Catch... Finally , dans l’expression de variable de contrôle de For boucle For Each d’une boucle ou, ou dans le corps d’une instruction SyncLock .Within the async method or lambda expression, an Await expression cannot occur in a query expression, in the catch or finally block of a Try…Catch…Finally statement, in the loop control variable expression of a For or For Each loop, or in the body of a SyncLock statement.

ExceptionsExceptions

La plupart des méthodes async retournent un Task ou Task<TResult>.Most async methods return a Task or 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.The properties of the returned task carry information about its status and history, such as whether the task is complete, whether the async method caused an exception or was canceled, and what the final result is. L'opérateur Await accède à ces propriétés.The Await operator accesses those properties.

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.If you await a task-returning async method that causes an exception, the Await operator rethrows the exception.

Si vous attendez une méthode Async retournant des tâches qui est annulée, Await l’opérateur lève de nouveau OperationCanceledExceptionune exception.If you await a task-returning async method that is canceled, the Await operator rethrows an OperationCanceledException.

Une tâche qui se trouve dans un état d’erreur peut refléter plusieurs exceptions.A single task that is in a faulted state can reflect multiple exceptions. Par exemple, la tâche peut être le résultat d'un appel à Task.WhenAll.For example, the task might be the result of a call to Task.WhenAll. Quand vous attendez une telle tâche, l’opération await lève à nouveau une seule des exceptions.When you await such a task, the await operation rethrows only one of the exceptions. Toutefois, vous ne pouvez pas prédire laquelle de ces exceptions est de nouveau levée.However, you can't predict which of the exceptions is rethrown.

Pour obtenir des exemples de gestion des erreurs dans les méthodes Async, consultez try... Catch... Finally, instruction.For examples of error handling in async methods, see Try...Catch...Finally Statement.

ExemplesExample

L'exemple Windows Forms suivant illustre l'utilisation de Await dans une méthode async, WaitAsynchronouslyAsync.The following Windows Forms example illustrates the use of Await in an async method, WaitAsynchronouslyAsync. Comparez le comportement de cette méthode avec celui de WaitSynchronously.Contrast the behavior of that method with the behavior of WaitSynchronously. Sans opérateur, WaitSynchronously s’exécute de manière synchrone en Async dépit de l’utilisation du modificateur dans sa définition et d' Thread.Sleep un appel à dans son corps. AwaitWithout an Await operator, WaitSynchronously runs synchronously despite the use of the Async modifier in its definition and a call to Thread.Sleep in its body.

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 aussiSee also