await (odwołanie w C#)

Operator await jest stosowany do zadania w metodzie asynchronicznej, aby wstrzymać wykonywanie tej metody, dopóki nie zakończy się oczekiwane zadanie.Zadanie reprezentuje pracę w toku.

Metoda asynchroniczna, w której jest używane słowo kluczowe await musi zostać zmodyfikowana przez słowo kluczowe async.Taka metoda, zdefiniowana za pomocą modyfikatora async i zwykle zawierająca jedno lub więcej wyrażeń await, jest nazywana metodą asynchroniczną.

[!UWAGA]

Słowa kluczowe async i await wprowadzono w programie Visual Studio 2012.Aby przeczytać wprowadzenie do programowania asynchronicznego, zobacz Programowanie asynchroniczne z Async i Await (C# i Visual Basic).

Zadanie, do którego jest stosowany operator await, jest zwykle wartością zwracaną przez wywołanie metody, która implementuje wzorzec asynchroniczny oparty na zadaniu.Przykładami są wartości typu Task lub Task.

W następującym kodzie HttpClient metoda GetByteArrayAsync zwraca Task<byte[]>, getContentsTask.Zadanie jest obietnicą utworzenia rzeczywistej tablicy bajtowej na zakończenie zadania.Operator await jest stosowany do metody getContentsTask w celu wstrzymania wykonywania w metodzie SumPageSizesAsync, dopóki nie zostanie zakończona metoda getContentsTask.W międzyczasie formant zostaje zwrócony do obiektu wywołującego SumPageSizesAsync, .Po zakończeniu getContentsTask wyrażenie await daje w wyniku tablicę bajtów.

private async Task SumPageSizesAsync()
{
    // To use the HttpClient type in desktop apps, you must include a using directive and add a 
    // reference for the System.Net.Http namespace.
    HttpClient client = new HttpClient();
    // . . .
    Task<byte[]> getContentsTask = client.GetByteArrayAsync(url);
    byte[] urlContents = await getContentsTask;

    // Equivalently, now that you see how it works, you can write the same thing in a single line.
    //byte[] urlContents = await client.GetByteArrayAsync(url);
    // . . .
}

Ważne
Aby zobaczyć kompletny przykład, zobacz Wskazówki: uzyskiwanie dostępu do sieci za pomocą Async i Await (C# i Visual Basic).Można ściągnąć próbkę z na witrynie Microsoft.Przykład znajduje się w projekcie AsyncWalkthrough_HttpClient.

Jak to już ukazał poprzedni przykład, jeśli await jest stosowany dla wyniku wywołania metody, która zwraca Task<TResult>, to typ wyrażenia await to TResult.Jeśli operator await jest stosowany do wyniku wywołania metody, które zwraca element Task, typ wyrażenia await jest pusty.Poniższy przykład ilustruje tę różnicę.

// Keyword await used with a method that returns a Task<TResult>.
TResult result = await AsyncMethodThatReturnsTaskTResult();

// Keyword await used with a method that returns a Task.
await AsyncMethodThatReturnsTask();

Wyrażenie await nie blokuje wątku, w którym jest wykonywane.Zamiast tego powoduje, że kompilator zapisuje pozostałą metodę asynchronicznej jako kontynuację w zadaniu oczekiwania.Formant powraca do obiektu wywołującego metody asynchronicznej.Po zakończeniu zadania wywołuje jego kontynuację, a wykonywanie metody asynchronicznej zostaje wznowione w miejscu, w którym zostało przerwane.

Wyrażenie await może wystąpić tylko w treści bezpośrednio otaczającej metody, wyrażenia lambda lub metody anonimowej, oznaczonej przez modyfikator async.Termin await służy jako słowo kluczowe tylko w tym kontekście.Gdzie indziej jest interpretowane jako identyfikator.W ramach tej metody, wyrażenia lambda lub metody anonimowej wyrażenie await nie może wystąpić w treści funkcji synchronicznej, w wyrażeniu kwerendy w bloku catch lub finally w instrukcji obsługi wyjątków, w bloku instrukcji „zablokuj” lub w niebezpiecznym kontekście.

Wyjątki

Większości metod asynchronicznych zwraca Task lub Task.Właściwości zwracanego zadania przenoszą informacje o jego stanie i historii, np., czy zadanie zostało ukończone, czy metoda async spowodowała wyjątek lub została anulowana i jaki jest wynik końcowy.Operator await uzyskuje dostęp do tych właściwości.

Jeśli włączysz oczekiwanie na metodę asynchroniczną zwracającą zadanie, która powoduje wyjątek, operator await ponownie zgłosi wyjątek.

Jeśli włączysz oczekiwanie na metodę asynchroniczną zwracającą zadanie, która została anulowana, operator await ponownie zgłosi wyjątek OperationCanceledException.

Pojedyncze zadanie w stanie błędnym może odzwierciedlać wiele wyjątków.Na przykład zadanie może być rezultatem wywołania funkcji Task.WhenAll.W przypadku użycia operacji await w zadaniu operacja ta zgłasza tylko jeden z wyjątków.Jednak nie można przewidzieć, który z tych wyjątków zostanie ponownie zgłoszony.

Aby uzyskać przykłady obsługi błędów w metodach asynchronicznych, zobacz try-catch (odwołanie w C#).

Przykład

Poniższy przykład formularzy Windows Forms ilustruje użycie operatora await w metodzie asynchronicznej WaitAsynchronouslyAsync.Porównaj zachowanie tej metody z zachowaniem WaitSynchronously.Bez operatora await zastosowanego do zadania, opcja WaitSynchronously jest uruchamiana synchronicznie, mimo zastosowania modyfikatora async w jej definicji i wywołania Thread.Sleep w jej treści.

private async void button1_Click(object sender, EventArgs e)
{
    // Call the method that runs asynchronously.
    string result = await WaitAsynchronouslyAsync();

    // Call the method that runs synchronously.
    //string result = await WaitSynchronously ();

    // Display the result.
    textBox1.Text += result;
}

// The following method runs asynchronously. The UI thread is not
// blocked during the delay. You can move or resize the Form1 window 
// while Task.Delay is running.
public async Task<string> WaitAsynchronouslyAsync()
{
    await Task.Delay(10000);
    return "Finished";
}

// The following method runs synchronously, despite the use of async.
// You cannot move or resize the Form1 window while Thread.Sleep
// is running because the UI thread is blocked.
public async Task<string> WaitSynchronously()
{
    // Add a using directive for System.Threading.
    Thread.Sleep(10000);
    return "Finished";
}

Zobacz też

Zadania

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

Informacje

async (odwołanie w C#)

Koncepcje

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