Freigeben über

async (C#-Referenz)

Mit dem async-Modifizierer können Sie angeben, dass eine Methode, ein Lambdaausdruck oder eine anonyme Methode asynchron ist. Wenn Sie diesen Modifizierer für eine Methode oder einen Ausdruck verwenden, erstellen Sie eine asynchrone Methode. Im folgenden Beispiel wird eine asynchrone Methode mit dem Namen ExampleMethodAsync definiert:

public async Task<int> ExampleMethodAsync()
{
    //...
}

Die C#-Sprachreferenz dokumentiert die zuletzt veröffentlichte Version der C#-Sprache. Außerdem enthält sie eine erste Dokumentation zu Funktionen in der öffentlichen Vorschau für die kommende Sprachversion.

In der Dokumentation werden alle Features identifiziert, die in den letzten drei Versionen der Sprache oder in der aktuellen öffentlichen Vorschau eingeführt wurden.

Tipp

Informationen dazu, wann ein Feature erstmals in C# eingeführt wurde, finden Sie im Artikel zum Versionsverlauf der C#-Sprache.

Wenn Sie mit der asynchronen Programmierung noch nicht vertraut sind oder nicht verstehen, wie eine asynchrone Methode den await Operator verwendet, um potenziell lange ausgeführte Aufgaben auszuführen, ohne den Thread des Aufrufers zu blockieren, lesen Sie die Einführung in der asynchronen Programmierung mit asynchroner Programmierung und warten Sie. Der folgende Code befindet sich in einer asynchronen Methode und ruft die HttpClient.GetStringAsync-Methode auf:

string contents = await httpClient.GetStringAsync(requestUrl);

Eine asynchrone Methode wird synchron ausgeführt, bis sie den ersten await Ausdruck erreicht. Zu diesem Zeitpunkt wird die Methode angehalten, bis die erwartete Aufgabe abgeschlossen ist. In der Zwischenzeit wird die Steuerung an den Aufrufer der Methode zurückgegeben, wie das Beispiel in nächsten Thema zeigt.

Wenn die Methode, die mit dem async-Schlüsselwort geändert wird, keinen await-Ausdruck oder keine await-Anweisung enthält, wird die Methode synchron ausgeführt. Mit einer Compilerwarnung werden Sie auf alle asynchronen Methoden hingewiesen, die keine await-Anweisungen enthalten, da dies möglicherweise auf einen Fehler hindeutet. Siehe Compilerwarnung (Stufe 1) CS4014.

Das async Schlüsselwort ist kontextbezogen. Es handelt sich nur dann um ein Schlüsselwort, wenn sie eine Methode, einen Lambda-Ausdruck oder eine anonyme Methode ändert. In allen anderen Kontexten interpretiert der Compiler ihn als Bezeichner.

Im folgenden Beispiel werden die Struktur und Ablaufsteuerung zwischen einem asynchronen Ereignishandler, StartButton_Click, und einer asynchronen Methode, ExampleMethodAsync, veranschaulicht. Das Ergebnis der asynchronen Methode ist die Anzahl von Zeichen einer Webseite. Der Code eignet sich für eine Windows Presentation Foundation (WPF)-App oder Windows Store-App, die Sie in Visual Studio erstellen. Weitere Informationen zum Einrichten der App finden Sie in den Codekommentaren.

Sie können diesen Code in Visual Studio als Windows Presentation Foundation (WPF)-App oder Windows Store-App ausführen. Sie benötigen ein Schaltflächen-Steuerelement mit dem Namen StartButton und ein Textfeldsteuerelement mit dem Namen ResultsTextBox. Denken Sie daran, die Namen und den Handler so festzulegen, dass es in etwa wie folgt aussieht:

<Button Content="Button" HorizontalAlignment="Left" Margin="88,77,0,0" VerticalAlignment="Top" Width="75"
        Click="StartButton_Click" Name="StartButton"/>
<TextBox HorizontalAlignment="Left" Height="137" Margin="88,140,0,0" TextWrapping="Wrap"
         Text="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>

So führen Sie den Code als WPF-App aus:

  • Fügen Sie diesen Code in die MainWindow-Klasse in „MainWindow.xaml.cs“ ein.
  • Fügen Sie einen Verweis auf „System.Net.Http“ hinzu.
  • Fügen Sie eine using-Anweisung für „System.Net.Http“ hinzu.

So führen Sie den Code als Windows Store-App aus:

  • Fügen Sie diesen Code in die MainPage-Klasse in „MainPage.xaml.cs“ ein.
  • Fügen Sie using-Direktiven für System.Net.Http und System.Threading.Tasks hinzu.
private async void StartButton_Click(object sender, RoutedEventArgs e)
{
    // ExampleMethodAsync returns a Task<int>, which means that the method
    // eventually produces an int result. However, ExampleMethodAsync returns
    // the Task<int> value as soon as it reaches an await.
    ResultsTextBox.Text += "\n";

    try
    {
        int length = await ExampleMethodAsync();
        // Note that you could put "await ExampleMethodAsync()" in the next line where
        // "length" is, but due to when '+=' fetches the value of ResultsTextBox, you
        // would not see the global side effect of ExampleMethodAsync setting the text.
        ResultsTextBox.Text += String.Format("Length: {0:N0}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("http://msdn.microsoft.com")).Length;
    ResultsTextBox.Text += "Preparing to finish ExampleMethodAsync.\n";
    // After the following return statement, any method that's awaiting
    // ExampleMethodAsync (in this case, StartButton_Click) can get the
    // integer result.
    return exampleInt;
}
// The example displays the following output:
// Preparing to finish ExampleMethodAsync.
// Length: 53292

Wichtig

Weitere Informationen zu Aufgaben und zum Code, der während des Wartens auf eine Aufgabe ausgeführt wird, finden Sie unter Asynchrone Programmierung mit async und await. Ein vollständiges Konsolenbeispiel, das ähnliche Elemente verwendet, finden Sie unter Mehrere asynchrone Aufgaben starten und nach Abschluss verarbeiten (C#).

Rückgabetypen

Eine asynchrone Methode kann folgende Rückgabetypen haben:

  • Task
  • Task<TResult>
  • void. Vermeiden Sie im Allgemeinen die Verwendung von async void Methoden für andere Code als Ereignishandler, da Aufrufer diese Methoden nicht await verwenden können und einen anderen Mechanismus implementieren müssen, um erfolgreiche Abschluss- oder Fehlerbedingungen zu melden.
  • Jeder Typ verfügt über eine zugängliche GetAwaiter-Methode. Der Typ System.Threading.Tasks.ValueTask<TResult> ist eine solche Implementierung. Sie ist verfügbar, indem Sie das NuGet-Paket System.Threading.Tasks.Extensionshinzufügen.

Die asynchrone Methode kann keine Parameter outrefref readonlydeklarieren inoder keinen Verweis-Rückgabewert aufweisen. Sie kann jedoch Methoden aufrufen, die über solche Parameter verfügen.

Geben Sie Task<TResult> als Rückgabetyp einer asynchronen Methode an, wenn die Rückgabe-Anweisung der Methode einen Operanden vom Typ TResultangibt. Verwenden Sie Task , wenn die Methode nach Abschluss des Vorgangs keinen aussagekräftigen Wert zurückgibt. Das bedeutet, dass ein Aufruf der Methode einen Task zurückgibt. Wenn der Task aber abgeschlossen ist, wird jeder await-Ausdruck, der auf den Task wartet, als void ausgewertet. Verwenden Sie den void Rückgabetyp in erster Linie, um Ereignishandler zu definieren, die diesen Rückgabetyp erfordern. Der Aufrufer einer Async-Methode, die void zurückgibt, kann auf ihn nicht warten und keine Ausnahmen auffangen, die von der Methode ausgelöst werden. Gibt einen anderen Typ zurück, in der Regel ein Werttyp, der über eine GetAwaiter Methode verfügt, um Speicherzuweisungen in leistungskritischen Codeabschnitten zu minimieren.

Weitere Informationen und Beispiele finden Sie unter Asynchrone Rückgabetypen.

Siehe auch

  • Last updated on