async (Referenční dokumentace jazyka C#)

  • Článek

Pomocí modifikátoru async určete, že metoda, výraz lambda nebo anonymní metoda je asynchronní. Pokud tento modifikátor použijete u metody nebo výrazu, označuje se jako asynchronní metoda. Následující příklad definuje asynchronní metodu s názvem ExampleMethodAsync:

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

Pokud s asynchronním programováním teprve začínáte nebo nerozumíte tomu, jak asynchronní metoda používá await operátor k provádění potenciálně dlouhotrvající práce bez blokování vlákna volajícího, přečtěte si úvod do asynchronního programování pomocí asynchronního programování a operátorem await. Následující kód se nachází uvnitř asynchronní metody a volá metodu HttpClient.GetStringAsync :

string contents = await httpClient.GetStringAsync(requestUrl);

Asynchronní metoda se spouští synchronně, dokud nedosáhne prvního await výrazu, v jakém okamžiku je metoda pozastavena, dokud není dokončena očekávaná úloha. Během této doby se ovládací prvek vrátí volajícímu metody, stejně jako v příkladu v následující části.

Pokud metoda, kterou async klíčové slovo modifikuje neobsahuje await výraz nebo příkaz, metoda se provede synchronně. Upozornění kompilátoru vás upozorní na všechny asynchronní metody, které neobsahují await příkazy, protože tato situace může znamenat chybu. Viz Upozornění kompilátoru (úroveň 1) CS4014.

Klíčové async slovo je kontextové v tom, že se jedná o klíčové slovo pouze v případě, že upravuje metodu, výraz lambda nebo anonymní metodu. Ve všech ostatních kontextech je interpretováno jako identifikátor.

Příklad

Následující příklad ukazuje strukturu a tok řízení mezi asynchronní obslužnou rutinou StartButton_Clickudálosti a asynchronní metodou, ExampleMethodAsync. Výsledkem asynchronní metody je počet znaků webové stránky. Kód je vhodný pro aplikaci Windows Presentation Foundation (WPF) nebo aplikaci pro Windows Store, kterou vytvoříte v sadě Visual Studio; viz komentáře ke kódu pro nastavení aplikace.

Tento kód můžete spustit v sadě Visual Studio jako aplikaci WPF (Windows Presentation Foundation) nebo aplikaci pro Windows Store. Potřebujete ovládací prvek Tlačítko s názvem StartButton a ovládací prvek Textové pole s názvem ResultsTextBox. Nezapomeňte nastavit názvy a obslužnou rutinu tak, abyste měli něco takového:

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

Spuštění kódu jako aplikace WPF:

  • Vložte tento kód do MainWindow třídy v MainWindow.xaml.cs.
  • Přidejte odkaz na System.Net.Http.
  • Přidání direktivy using pro System.Net.Http

Spuštění kódu jako aplikace pro Windows Store:

  • Vložte tento kód do MainPage třídy v MainPage.xaml.cs.
  • Přidejte direktivy using pro System.Net.Http a 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

Důležité

Další informace o úkolech a kódu, který se spouští při čekání na úlohu, najdete v tématu Asynchronní programování s asynchronní a await. Úplný příklad konzoly, který používá podobné prvky, najdete v tématu Zpracování asynchronních úloh při jejich dokončení (C#).

Návratové typy

Asynchronní metoda může mít následující návratové typy:

  • Task
  • Task<TResult>
  • void. async void Metody jsou obecně nedoporučujeme pro kód jiné než obslužné rutiny událostí, protože volající nemohou await tyto metody implementovat a musí implementovat jiný mechanismus pro hlášení úspěšných dokončení nebo chybových podmínek.
  • Libovolný typ, který má přístupnou GetAwaiter metodu. Typ System.Threading.Tasks.ValueTask<TResult> je jedním z takových implementací. Je k dispozici přidáním balíčku System.Threading.Tasks.ExtensionsNuGet .

Asynchronní metoda nemůže deklarovat žádné parametry, ref nebo out, ani nemůže mít návratovou hodnotu odkazu, ale může volat metody, které mají takové parametry.

Jako návratový typ asynchronní metody zadáte Task<TResult> , pokud návratový příkaz metody určuje operand typu TResult. Použijete Task , pokud se po dokončení metody nevrátí žádná smysluplná hodnota. To znamená, že volání metody vrátí Task, ale po Task dokončení, jakýkoli await výraz, který čeká na Task vyhodnocení void.

Návratový void typ se používá především k definování obslužných rutin událostí, které vyžadují tento návratový typ. Volající voidasynchronní metody nemůže očekávat a nemůže zachytit výjimky, které metoda vyvolá.

Vrátíte jiný typ, obvykle typ hodnoty, který má metodu GetAwaiter pro minimalizaci přidělení paměti v důležitých oddílech výkonu kódu.

Další informace a příklady najdete v tématu Asynchronní návratové typy.

Viz také