async (odwołanie w C#)

  • Artykuł

async Użyj modyfikatora, aby określić, że metoda, wyrażenie lambda lub metoda anonimowa jest asynchroniczna. Jeśli używasz tego modyfikatora w metodzie lub wyrażeniu, jest ona nazywana metodą asynchronikową. W poniższym przykładzie zdefiniowano metodę asynchroniową o nazwie ExampleMethodAsync:

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

Jeśli dopiero zaczynasz programować asynchroniczne lub nie rozumiesz, w jaki sposób metoda asynchroniczna używa await operatora do potencjalnie długotrwałej pracy bez blokowania wątku obiektu wywołującego, przeczytaj wprowadzenie do programowania asynchronicznego za pomocą asynchronicznego i oczekiwania. Poniższy kod znajduje się wewnątrz metody asynchronicznej i wywołuje metodę HttpClient.GetStringAsync :

string contents = await httpClient.GetStringAsync(requestUrl);

Metoda asynchroniczna jest uruchamiana synchronicznie do momentu osiągnięcia pierwszego await wyrażenia, w którym momencie metoda jest zawieszona do momentu ukończenia oczekiwanego zadania. 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, którą async modyfikuje słowo kluczowe, nie zawiera await wyrażenia lub instrukcji, metoda wykonuje synchronicznie. Ostrzeżenie kompilatora ostrzega o wszelkich metodach asynchronicznych, które nie zawierają await instrukcji, ponieważ taka sytuacja może wskazywać na błąd. Zobacz Ostrzeżenie kompilatora (poziom 1) CS4014.

Słowo async kluczowe jest kontekstowe, ponieważ 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 kontroli między asynchroniową procedurą obsługi zdarzeń, StartButton_Clicki metodą ExampleMethodAsyncasynchroniową . Wynikiem metody asynchronicznej jest liczba znaków strony internetowej. Kod jest odpowiedni dla aplikacji Windows Presentation Foundation (WPF) lub aplikacji ze Sklepu Windows utworzonej w programie Visual Studio; Zobacz komentarze dotyczące kodu służące do konfigurowania aplikacji.

Ten kod można uruchomić w programie Visual Studio jako aplikacji Windows Presentation Foundation (WPF) lub aplikacji ze Sklepu Windows. Potrzebujesz kontrolki Przycisk o nazwie StartButton i kontrolce Pole tekstowe o nazwie ResultsTextBox. Pamiętaj, aby ustawić nazwy i procedurę obsługi, aby mieć coś takiego:

<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"/>

Aby uruchomić kod jako aplikację WPF:

  • Wklej ten kod do MainWindow klasy w MainWindow.xaml.cs.
  • Dodaj odwołanie do pliku System.Net.Http.
  • Dodaj dyrektywę using System.Net.Http.

Aby uruchomić kod jako aplikację ze Sklepu Windows:

  • Wklej ten kod do MainPage klasy w MainPage.xaml.cs.
  • Dodaj dyrektywy using dla systemów.Net.Http i 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

Ważne

Aby uzyskać więcej informacji o zadaniach i kodzie wykonywanym podczas oczekiwania na zadanie, zobacz Programowanie asynchroniczne z asynchronicznym i await. Aby zapoznać się z pełnym przykładem konsoli, który używa podobnych elementów, zobacz Przetwarzanie zadań asynchronicznych po zakończeniu (C#).

Typy zwracane

Metoda asynchronizna może mieć następujące typy zwracane:

  • Task
  • Task<TResult>
  • void. async void Metody są zwykle zniechęcane do kodu innego niż programy obsługi zdarzeń, ponieważ wywołujące nie mogą await tych metod i muszą zaimplementować inny mechanizm zgłaszania pomyślnych warunków ukończenia lub błędu.
  • Dowolny typ, który ma dostępną GetAwaiter metodę. Typ System.Threading.Tasks.ValueTask<TResult> jest jedną z takich implementacji. Jest on dostępny przez dodanie pakietu System.Threading.Tasks.ExtensionsNuGet .

Metoda asynchronizna nie może zadeklarować żadnych parametrów w parametrach ref lub out ani nie może mieć wartości zwracanej odwołania, ale może wywoływać metody, które mają takie parametry.

Należy określić Task<TResult> jako zwracany typ metody asynchronicznej, jeśli instrukcja return metody określa operand typu TResult. Task Jeśli po zakończeniu metody nie zostanie zwrócona żadna zrozumiała wartość. Oznacza to, że wywołanie metody zwraca Taskwartość , ale po zakończeniu Task dowolnego await wyrażenia, które oczekuje na Task wynik .void

Typ zwracany void jest używany głównie do definiowania procedur obsługi zdarzeń, które wymagają tego typu zwracanego. Obiekt wywołujący voidmetody -zwracającej asynchroniczne nie może jej oczekiwać i nie może przechwycić wyjątków zgłaszanych przez metodę.

Zwracany jest inny typ, zazwyczaj typ wartości, który ma metodę GetAwaiter minimalizowania alokacji pamięci w sekcjach kodu o krytycznym znaczeniu dla wydajności.

Aby uzyskać więcej informacji i przykładów, zobacz Async Return Types (Typy zwracane asynchroniczne).

Zobacz też