Der Operator „await“ (C#-Referenz)await operator (C# reference)

Der Operator await hält die Auswertung der einschließenden async-Methode an, bis der asynchrone Vorgang abgeschlossen ist, der durch seinen Operanden dargestellt wird.The await operator suspends evaluation of the enclosing async method until the asynchronous operation represented by its operand completes. Sobald der asynchrone Vorgang abgeschlossen ist, gibt der Operator await ggf. das Ergebnis des Vorgangs zurück.When the asynchronous operation completes, the await operator returns the result of the operation, if any. Wenn der Operator await auf den Operanden angewendet wird, der einen bereits abgeschlossenen Vorgang darstellt, wird das Ergebnis des Vorgangs sofort zurückgegeben, ohne dass die einschließende Methode angehalten wird.When the await operator is applied to the operand that represents an already completed operation, it returns the result of the operation immediately without suspension of the enclosing method. Der Operator await blockiert nicht den Thread, der die Async-Methode auswertet.The await operator doesn't block the thread that evaluates the async method. Wenn der Operator await die einschließende asynchrone Methode anhält, wird das Steuerelement an den Aufrufer der Methode zurückgegeben.When the await operator suspends the enclosing async method, the control returns to the caller of the method.

Im folgenden Beispiel gibt die Methode HttpClient.GetByteArrayAsync die Instanz Task<byte[]> zurück, die einen asynchronen Vorgang darstellt, der ein Bytearray erzeugt, wenn er abgeschlossen wird.In the following example, the HttpClient.GetByteArrayAsync method returns the Task<byte[]> instance, which represents an asynchronous operation that produces a byte array when it completes. Der Operator await hält so lange die Methode DownloadDocsMainPageAsync an, bis der Vorgang abgeschlossen ist.Until the operation completes, the await operator suspends the DownloadDocsMainPageAsync method. Wenn DownloadDocsMainPageAsync angehalten wird, wird die Steuerung an die Methode Main zurückgegeben. Bei dieser handelt es sich um den Aufrufer von DownloadDocsMainPageAsync.When DownloadDocsMainPageAsync gets suspended, control is returned to the Main method, which is the caller of DownloadDocsMainPageAsync. Die Methode Main wird so lange ausgeführt, bis sie das Ergebnis des asynchronen Vorgangs benötigt, der von der Methode DownloadDocsMainPageAsync ausgeführt wird.The Main method executes until it needs the result of the asynchronous operation performed by the DownloadDocsMainPageAsync method. Wenn GetByteArrayAsync alle Bytes abruft, wird der Rest der Methode DownloadDocsMainPageAsync ausgewertet.When GetByteArrayAsync gets all the bytes, the rest of the DownloadDocsMainPageAsync method is evaluated. Danach wird der Rest der Methode Main ausgewertet.After that, the rest of the Main method is evaluated.

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class AwaitOperator
{
    public static async Task Main()
    {
        Task<int> downloading = DownloadDocsMainPageAsync();
        Console.WriteLine($"{nameof(Main)}: Launched downloading.");

        int bytesLoaded = await downloading;
        Console.WriteLine($"{nameof(Main)}: Downloaded {bytesLoaded} bytes.");
    }

    private static async Task<int> DownloadDocsMainPageAsync()
    {
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: About to start downloading.");

        var client = new HttpClient();
        byte[] content = await client.GetByteArrayAsync("https://docs.microsoft.com/en-us/");

        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: Finished downloading.");
        return content.Length;
    }
}
// Output similar to:
// DownloadDocsMainPageAsync: About to start downloading.
// Main: Launched downloading.
// DownloadDocsMainPageAsync: Finished downloading.
// Main: Downloaded 27700 bytes.

Im vorangehenden Beispiel wird die asynchrone Main-Methode verwendet. Dies ist ab C# 7.1 möglich.The preceding example uses the async Main method, which is possible beginning with C# 7.1. Weitere Informationen finden Sie im Abschnitt Der Operator „await“ in der Methode „Main“.For more information, see the await operator in the Main method section.

Hinweis

Eine Einführung in die asynchrone Programmierung finden Sie unter Asynchrone Programmierung mit „async“ und „await“.For an introduction to asynchronous programming, see Asynchronous programming with async and await. Die asynchrone Programmierung mit async und await folgt dem aufgabenbasierten asynchronen Muster.Asynchronous programming with async and await follows the task-based asynchronous pattern.

Der Operator await kann nur in einer Methode, einem Lambdaausdruck oder einer anonymen Methode verwendet werden, die von dem Schlüsselwort async geändert wird.You can use the await operator only in a method, lambda expression, or anonymous method that is modified by the async keyword. Innerhalb einer Async-Methode können Sie den Operator await nicht im Text einer synchronen Funktion, innerhalb des Blocks einer Lock-Anweisung oder in einem unsicheren Kontext verwenden.Within an async method, you can't use the await operator in the body of a synchronous function, inside the block of a lock statement, and in an unsafe context.

Der Operand des Operators await gehört normalerweise einem der folgenden .NET-Typen an: Task, Task<TResult>, ValueTask oder ValueTask<TResult>.The operand of the await operator is usually of one of the following .NET types: Task, Task<TResult>, ValueTask, or ValueTask<TResult>. Allerdings kann es sich bei jedem Awaitable-Ausdruck um den Operanden des Operators await handeln.However, any awaitable expression can be the operand of the await operator. Weitere Informationen finden Sie im Abschnitt Awaitable-Ausdrücke der C#-Sprachspezifikation.For more information, see the Awaitable expressions section of the C# language specification.

Der Ausdruck await t ist vom Typ TResult, wenn der Ausdruck t vom Typ Task<TResult> oder ValueTask<TResult> ist.The type of expression await t is TResult if the type of expression t is Task<TResult> or ValueTask<TResult>. Wenn der Ausdruck t vom Typ Task oder ValueTask ist, ist await t vom Typ void.If the type of t is Task or ValueTask, the type of await t is void. In beiden Fällen löst await t die Ausnahme erneut aus, wenn t eine Ausnahme auslöst.In both cases, if t throws an exception, await t rethrows the exception. Weitere Informationen zur Bearbeitung von Ausnahmen finden Sie im Abschnitt Ausnahmen in Async-Methoden des Artikels Try-catch-Anweisung.For more information about exception handling, see the Exceptions in async methods section of the try-catch statement article.

Die Schlüsselwörter async und await sind in C# 5 und höher verfügbar.The async and await keywords are available in C# 5 and later.

Asynchrone Datenströme und verwerfbare ObjekteAsynchronous streams and disposables

Ab C# 8.0 können Sie asynchrone Datenströme und verwerfbare Elemente verwenden.Beginning with C# 8.0, you can work with asynchronous streams and disposables.

Sie können die await foreach-Anweisung verwenden, um einen asynchronen Datenstrom zu verarbeiten.You use the await foreach statement to consume an asynchronous stream of data. Weitere Informationen finden Sie im Artikel foreach-Anweisung und im Abschnitt Asynchrone Datenströme des Artikels Neues in C# 8.0.For more information, see the foreach statement article and the Asynchronous streams section of the What's new in C# 8.0 article.

Sie können die await using-Anweisung nutzen, um ein asynchron verwerfbares Objekt zu nutzen, d. h. ein Objekt eines Typs, der eine IAsyncDisposable-Schnittstelle implementiert.You use the await using statement to work with an asynchronously disposable object, that is, an object of a type that implements an IAsyncDisposable interface. Weitere Informationen erhalten Sie im Abschnitt Verwenden von asynchron verwerfbar des Artikels Implementieren einer DisposeAsync-Methode.For more information, see the Using async disposable section of the Implement a DisposeAsync method article.

Der Operator „await“ in der Methode „Main“await operator in the Main method

Ab C# 7.1 kann die Methode Main, die den Einstiegspunkt der Anwendung darstellt, Task oder Task<int> zurückgeben. Deshalb muss es sich um eine asynchrone Methode handeln, damit Sie den Operator await im Text verwenden können.Beginning with C# 7.1, the Main method, which is the application entry point, can return Task or Task<int>, enabling it to be async so you can use the await operator in its body. In früheren C#-Versionen können Sie den Wert der Eigenschaft Task<TResult>.Result der Instanz Task<TResult> abrufen, die von der entsprechenden Async-Methode zurückgegeben wird, um sicherzustellen, dass die Methode Main darauf wartet, dass ein asynchroner Vorgang abgeschlossen wird.In earlier C# versions, to ensure that the Main method waits for the completion of an asynchronous operation, you can retrieve the value of the Task<TResult>.Result property of the Task<TResult> instance that is returned by the corresponding async method. Für asynchrone Vorgänge, für die kein Wert zurückgegeben wird, können Sie die Methode Task.Wait aufrufen.For asynchronous operations that don't produce a value, you can call the Task.Wait method. Informationen zum Auswählen der Sprachversion finden Sie unter Auswählen der C#-Sprachversion.For information about how to select the language version, see C# language versioning.

C#-SprachspezifikationC# language specification

Weitere Informationen finden Sie im Abschnitt Await-Ausdrücke der C#-Sprachspezifikation.For more information, see the Await expressions section of the C# language specification.

Siehe auchSee also