Await-Operator (Visual Basic)Await Operator (Visual Basic)

Sie wenden den Operator Await auf einen Operanden in einer asynchronen Methode oder einem Lambda-Ausdruck an, um die Ausführung der Methode anzuhalten, bis die erwartete Aufgabe ausgeführt wurde.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. Die Aufgabe stellt derzeit ausgeführte Arbeit dar.The task represents ongoing work.

Die Methode in der Await wird verwendet, muss ein Async Modifizierer.The method in which Await is used must have an Async modifier. Eine solche mit dem Async-Modifizierer definierte Methode, die in der Regel mindestens einen Await-Ausdruck enthält, wird als async-Methode bezeichnet.Such a method, defined by using the Async modifier, and usually containing one or more Await expressions, is referred to as an async method.

Hinweis

Die Schlüsselwörter Async und Await wurden in Visual Studio 2012 eingeführt.The Async and Await keywords were introduced in Visual Studio 2012. Eine Einführung in die asynchrone Programmierung, finden Sie unter asynchrone Programmierung mit Async und Await.For an introduction to async programming, see Asynchronous Programming with Async and Await.

In der Regel die Aufgabe, die auf die Sie anwenden der Await Operator ist der Rückgabewert von einem Aufruf einer Methode, die die aufgabenbasierte asynchrone Muster, d. h. eine Task oder ein Task<TResult>.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>.

Im folgenden Code gibt die HttpClient-Methode GetByteArrayAsyncgetContentsTask, eine Task(Of Byte()) zurück.In the following code, the HttpClient method GetByteArrayAsync returns getContentsTask, a Task(Of Byte()). Die Aufgabe enthält das Versprechen, das tatsächliche Bytearray zu erzeugen, wenn die Operation abgeschlossen ist.The task is a promise to produce the actual byte array when the operation is complete. Der Operator Await wird auf getContentsTask angewendet, um die Ausführung in SumPageSizesAsync anzuhalten, bis getContentsTask abgeschlossen wurde.The Await operator is applied to getContentsTask to suspend execution in SumPageSizesAsync until getContentsTask is complete. In der Zwischenzeit wird die Steuerung wieder an den Aufrufer von SumPageSizesAsync übergeben.In the meantime, control is returned to the caller of SumPageSizesAsync. Wenn getContentsTask beendet ist, wird der Await-Ausdruck in ein Bytearray ausgewertet.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  

Wichtig

Das vollständige Beispiel finden Sie unter Exemplarische Vorgehensweise: Zugreifen auf das Web mit Async und Await.For the complete example, see Walkthrough: Accessing the Web by Using Async and Await. Sie können das Beispiel aus den Codebeispielen für Entwickler der Microsoft-Website herunterladen.You can download the sample from Developer Code Samples on the Microsoft website. Das Beispiel befindet sich im AsyncWalkthrough_HttpClient-Projekt.The example is in the AsyncWalkthrough_HttpClient project.

Wenn Await auf das Ergebnis eines Methodenaufrufs angewendet wird, der eine Task(Of TResult) zurückgibt, ist der Typ des Await-Ausdrucks 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. Wenn Await auf das Ergebnis eines Methodenaufrufs angewendet wird, der eine Task zurückgibt, gibt der Await-Ausdruck keinen Wert zurück.If Await is applied to the result of a method call that returns a Task, the Await expression doesn't return a value. Der Unterschied wird im folgenden Beispiel veranschaulicht.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()  

Ein Await-Ausdruck oder eine Await-Anweisung blockiert nicht den Thread, auf dem sie ausgeführt wird.An Await expression or statement does not block the thread on which it is executing. Stattdessen wird damit verursacht, dass der Compiler den Rest der asynchronen Methode nach dem Await-Ausdruck als Fortsetzung der erwarteten Aufgabe registriert.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. Die Steuerung wird dann wieder an den Aufrufer der Async-Methode übergeben.Control then returns to the caller of the async method. Wenn die Aufgabe abgeschlossen ist, löst sie ihre Fortsetzung aus, und die Ausführung der asynchronen Methode wird da fortgesetzt, wo sie angehalten wurde.When the task completes, it invokes its continuation, and execution of the async method resumes where it left off.

Ein Await-Ausdruck kann nur im Text einer unmittelbar einschließenden Methode oder eines Lambda-Ausdrucks auftreten, die oder der durch einen Async-Modifizierer gekennzeichnet ist.An Await expression can occur only in the body of an immediately enclosing method or lambda expression that is marked by an Async modifier. Der Begriff "await" dient nur in diesem Kontext als Schlüsselwort.The term Await serves as a keyword only in that context. In anderen Kontexten wird er als Bezeichner interpretiert.Elsewhere, it is interpreted as an identifier. Innerhalb der asynchronen Methode oder einem Lambda-Ausdrucks kann ein Await Ausdruck kann nicht in einem Abfrageausdruck auftreten, der catch oder finally -Block eine versuchen... Catch... Schließlich -Anweisung in der Steuerelement-Schleifenausdruck der eine For oder For Each Schleife oder im Hauptteil einer SyncLock Anweisung.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.

AusnahmenExceptions

Die meisten asynchronen Methoden geben einen Task oder Task<TResult> zurück.Most async methods return a Task or Task<TResult>. Die Eigenschaften der zurückgegebenen Aufgabe enthalten Informationen über den Status und Verlauf, z. B. ob die Aufgabe abgeschlossen ist, ob die asynchrone Methode eine Ausnahme verursacht hat oder abgebrochen wurde, und was das Endergebnis ist.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. Der Operator Await greift auf diese Eigenschaften zu.The Await operator accesses those properties.

Wenn Sie auf eine asynchrone Methode warten, die eine Aufgabe zurückgibt und eine Ausnahme verursacht, löst der Operator Await die Ausnahme erneut aus.If you await a task-returning async method that causes an exception, the Await operator rethrows the exception.

Wenn Sie eine asynchrone Methode erwarten, die eine Aufgabe zurückgibt und abgebrochen wird, löst der Operator Await erneut eine OperationCanceledException aus.If you await a task-returning async method that is canceled, the Await operator rethrows an OperationCanceledException.

Eine einzelne Aufgabe, die einen Fehlerzustand aufweist, kann verschiedene Ausnahmen auslösen.A single task that is in a faulted state can reflect multiple exceptions. Beispielsweise kann die Aufgabe das Ergebnis eines Aufrufs an Task.WhenAll sein.For example, the task might be the result of a call to Task.WhenAll. Wenn Sie auf eine solche Aufgabe warten, löst die await-Operation nur eine der Ausnahmen erneut aus.When you await such a task, the await operation rethrows only one of the exceptions. Sie können jedoch nicht vorhersagen, welche der Ausnahmen erneut ausgelöst wird.However, you can't predict which of the exceptions is rethrown.

Beispiele für die Fehlerbehandlung in asynchronen Methoden finden Sie unter versuchen... Catch... Finally-Anweisung.For examples of error handling in async methods, see Try...Catch...Finally Statement.

BeispielExample

Im folgenden Windows Forms-Beispielen wird die Verwendung von Await in einer asynchronen Methode, WaitAsynchronouslyAsync, veranschaulicht.The following Windows Forms example illustrates the use of Await in an async method, WaitAsynchronouslyAsync. Vergleichen Sie das Verhalten der Methode mit dem Verhalten von WaitSynchronously.Contrast the behavior of that method with the behavior of WaitSynchronously. Ohne einen Await-Operator wird WaitSynchronously trotz der Verwendung des Async-Modifizierers in der Definition und in einem Aufruf von Thread.Sleep im Text synchron ausgeführt.Without 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  

Siehe auchSee Also

Asynchrone Programmierung mit Async und AwaitAsynchronous Programming with Async and Await
Exemplarische Vorgehensweise: Zugreifen auf das Web mit Async und AwaitWalkthrough: Accessing the Web by Using Async and Await
AsyncAsync