async (odwołanie w C#)

Modyfikator async umożliwia określenie, że metoda, wyrażenie lambda lub metoda anonimowa jest asynchroniczna.Metoda lub wyrażenie, w której jest używany ten modyfikator, jest nazywana metodą asynchroniczną.

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

Jeśli nie znasz się na programowaniu asynchronicznym lub nie wiesz, w jaki sposób metoda asynchroniczna używa słowa kluczowego await w celu wykonywania potencjalnie długotrwałych zadań bez blokowania wątku obiektu wywołującego, przeczytaj wprowadzenie w artykule Programowanie asynchroniczne z Async i Await (C# i Visual Basic).

string contents = await contentsTask;

Metoda działa synchronicznie, dopóki nie napotka pierwszego wyrażenia await. W tym punkcie wykonywanie metody jest wstrzymywane do czasu ukończenia zadania, na które oczekuje metoda.W międzyczasie sterowanie jest przekazywane do obiektu wywołującego metody, tak jak pokazano w przykładzie w następnej sekcji.

Jeśli metoda modyfikowana przez słowo kluczowe async nie zawiera wyrażenia lub instrukcji await, metoda jest wykonywana synchronicznie.Ostrzeżenie kompilatora ostrzega przed wszystkimi metodami asynchronicznymi, które nie zawierają słowa kluczowego await, ponieważ taka sytuacja może wskazywać na błąd.Zobacz Ostrzeżenie kompilatora (poziom 1) CS4014.

Słowo kluczowe async jest kontekstowe w tym sensie, że jest słowem kluczowym tylko wtedy, gdy modyfikuje metodę, wyrażenie lambda lub metodę anonimową.W innych kontekstach jest interpretowane jako identyfikator.

Przykład

W poniższym przykładzie pokazano strukturę i przepływ sterowania między programem obsługi zdarzeń asynchronicznych StartButton_Click a metodą asynchroniczną ExampleMethodAsync.Wynikiem wykonania metody asynchronicznej jest długość pobranej witryny sieci web.Kod jest odpowiedni dla aplikacji programu Windows Presentation Foundation (WPF) lub aplikacji do Sklepu Windows tworzonej w programie Visual Studio 2013; instrukcje konfiguracji aplikacji znajdują się w komentarzach w kodzie.

// You can run this code in Visual Studio 2013 as a WPF app or a Windows Store app.
// You need a button (StartButton) and a textbox (ResultsTextBox).
// 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="TextBox" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>
        
// To run the code as a WPF app:
//    paste this code into the MainWindow class in MainWindow.xaml.cs,
//    add a reference to System.Net.Http, and
//    add a using directive for System.Net.Http.

// To run the code as a Windows Store app:
//    paste this code into the MainPage class in MainPage.xaml.cs, and
//    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}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("https://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;
}
// Output:
// Preparing to finish ExampleMethodAsync.
// Length: 53292

Ważne

Aby uzyskać więcej informacji dotyczących zadań i kodu, który jest wykonywany podczas oczekiwania na zadanie, zobacz Programowanie asynchroniczne z Async i Await (C# i Visual Basic). Aby zapoznać się z pełnym przykładem WPF, w którym są używane podobne elementy, zobacz Wskazówki: uzyskiwanie dostępu do sieci za pomocą Async i Await (C# i Visual Basic).Przykładowy kod można pobrać z witryny Przykłady kodu dla deweloperów.

Typy zwracane

Typem zwracanym metody asynchronicznej może być typ Task, Task lub void.Metoda nie może deklarować parametrów ref i out, ale może wywoływać metody, które mają takie parametry.

Jako zwracany typ metody asynchronicznej należy określić typ Task<TResult>, jeśli instrukcja return metody określa argument operacji typu TResult.Jeśli po ukończeniu wykonywania metody nie jest zwracana żadna mająca znaczenie wartość, należy użyć typu Task.Oznacza to, że wywołanie tej metody powoduje zwrócenie obiektu Task, ale po ukończeniu wykonywania zadania określonego przez obiekt Task nie ma wyrażenia await, które oczekuje na wykonanie zadania Task i zwrócenie wartości void.

Typ zwracany void jest używany głównie do definiowania programów obsługi zdarzeń, które wymagają typów zwracanych.Obiekt wywołujący metodę asynchroniczną zwracającą wartość void nie może oczekiwać na jej ukończenie, ani nie może przechwytywać zgłaszanych przez nią wyjątków.

Aby uzyskać więcej informacji i przykładów, zobacz Asynchroniczne typy zwracane (C# i Visual Basic).

Zobacz też

Zadania

Wskazówki: uzyskiwanie dostępu do sieci za pomocą Async i Await (C# i Visual Basic)

Informacje

await (odwołanie w C#)

AsyncStateMachineAttribute

Koncepcje

Programowanie asynchroniczne z Async i Await (C# i Visual Basic)