async (C#-Referenz)async (C# Reference)

Mit dem async-Modifizierer können Sie angeben, dass eine Methode, ein Lambdaausdruck oder eine anonyme Methode asynchron ist.Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Wenn Sie diesen Modifizierer auf Methoden oder Ausdrücke anwenden, wird dies als asynchrone Methode bezeichnet.If you use this modifier on a method or expression, it's referred to as an async method. Im folgenden Beispiel wird eine asynchrone Methode mit dem Namen ExampleMethodAsync definiert:The following example defines an async method named ExampleMethodAsync:

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

Wenn Sie mit der asynchronen Programmierung noch nicht vertraut sind oder nicht wissen, wie eine asynchrone Methode das await-Schlüsselwort verwendet, um Aufgaben mit potenziell langer Laufzeit auszuführen, ohne den Thread des Aufrufers zu blockieren, können Sie die Einführung unter Asynchrone Programmierung mit Async und Await lesen.If you're new to asynchronous programming or do not understand how an async method uses the await keyword to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. Der folgende Code befindet sich in einer asynchronen Methode und ruft die HttpClient.GetStringAsync-Methode auf:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Eine asynchrone Methode wird bis zum ersten await-Ausdruck synchron ausgeführt. Dann wird die Methode angehalten, bis die erwartete Aufgabe abgeschlossen ist.An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. In der Zwischenzeit wird die Steuerung an den Aufrufer der Methode zurückgegeben, wie das Beispiel in nächsten Thema zeigt.In the meantime, control returns to the caller of the method, as the example in the next section shows.

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.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Mit einer Compilerwarnung werden Sie auf alle asynchronen Methoden hingewiesen, die keine await-Anweisungen enthalten, da dies möglicherweise auf einen Fehler hindeutet.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Siehe Compilerwarnung (Stufe 1) CS4014.See Compiler Warning (level 1) CS4014.

Das async-Schlüsselwort ist insofern kontextabhängig, dass es nur dann ein Schlüsselwort ist, wenn mit ihm eine Methode, ein Lambda-Ausdruck oder eine anonyme Methode geändert wird.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. In allen anderen Kontexten wird es als Bezeichner interpretiert.In all other contexts, it's interpreted as an identifier.

BeispielExample

Im folgenden Beispiel werden die Struktur und Ablaufsteuerung zwischen einem asynchronen Ereignishandler, StartButton_Click, und einer asynchronen Methode, ExampleMethodAsync, veranschaulicht.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. Das Ergebnis der asynchronen Methode ist die Anzahl von Zeichen einer Webseite.The result from the async method is the number of characters of a web page. Der Code ist für eine Windows Presentation Foundation (WPF)- oder Windows Store-Anwendung geeignet, die Sie in Visual Studio erstellen. Informationen zum Einrichten der Anwendung finden Sie in den Codekommentaren.The code is suitable for a Windows Presentation Foundation (WPF) app or Windows Store app that you create in Visual Studio; see the code comments for setting up the app.

Sie können diesen Code in Visual Studio als Windows Presentation Foundation (WPF)-App oder Windows Store-App ausführen.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Sie benötigen ein Schaltflächen-Steuerelement mit dem Namen StartButton und ein Textfeldsteuerelement mit dem Namen ResultsTextBox.You need a Button control named StartButton and a Textbox control named ResultsTextBox. Denken Sie daran, die Namen und den Handler so festzulegen, dass es in etwa wie folgt aussieht:Remember to set the names and handler so that you have something like this:

<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:To run the code as a WPF app:

  • Fügen Sie diesen Code in die MainWindow-Klasse in „MainWindow.xaml.cs“ ein.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Fügen Sie einen Verweis auf „System.Net.Http“ hinzu.Add a reference to System.Net.Http.
  • Fügen Sie eine using-Anweisung für „System.Net.Http“ hinzu.Add a using directive for System.Net.Http.

So führen Sie den Code als Windows Store-App aus:To run the code as a Windows Store app:

  • Fügen Sie diesen Code in die MainPage-Klasse in „MainPage.xaml.cs“ ein.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Fügen Sie using-Anweisungen für „System.Net.Http“ und „System.Threading.Tasks“ hinzu.Add using directives for System.Net.Http and System.Threading.Tasks.
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.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Ein vollständiges Beispiel für WPF, das ähnliche Elemente verwendet, finden Sie unter Exemplarische Vorgehensweise: Zugreifen auf das Web durch Verwenden von Async und Await.For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

RückgabetypenReturn Types

Eine asynchrone Methode kann folgende Rückgabetypen haben:An async method can have the following return types:

  • Task
  • Task<TResult>
  • void, der nur für Ereignishandler verwendet werden sollte.void, which should only be used for event handlers.
  • Ab C# 7: Jeder Typ, der über eine zugängliche GetAwaiter-Methode verfügt.Starting with C# 7, any type that has an accessible GetAwaiter method. Der Typ System.Threading.Tasks.ValueTask<TResult> ist eine solche Implementierung.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Er ist verfügbar, wenn Sie das NuGet-Paket System.Threading.Tasks.Extensions hinzufügen.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

Mit der asynchronen Methode können keine ref- oder out-Parameter deklariert werden und sie kann auch keinen Verweisrückgabewert aufweisen, es können mit ihr jedoch Methoden aufgerufen werden, die solche Parameter aufweisen.The async method can't declare any ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

Task<TResult> wird als Rückgabetyp einer Async-Methode angegeben, wenn mit der return-Anweisung der Methode ein Operand vom Typ TResult angegeben wird.You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. Task wird verwendet, falls kein sinnvoller Wert zurückgegeben wird, wenn die Methode abgeschlossen ist.You use Task if no meaningful value is returned when the method is completed. 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.That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

Der Rückgabetyp void wird hauptsächlich zum Definieren von Ereignishandlern verwendet, die diesen Rückgabetyp erfordern.You use the void return type primarily to define event handlers, which require that return type. 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.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

Ab C# 7 wird ein anderer Typ zurückgegeben, üblicherweise ein Werttyp, der über eine GetAwaiter-Methode verfügt, um Speicherreservierungen in Codeabschnitten zu minimieren, die für die Leistung entscheidend sind.Starting with C# 7, you return another type, typically a value type, that has a GetAwaiter method to miminize memory allocations in performance-critical sections of code.

Weitere Informationen und Beispiele finden Sie unter Asynchrone Rückgabetypen.For more information and examples, see Async Return Types.

Siehe auchSee Also

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