async (Referenční dokumentace jazyka C#)

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átora 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 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, kdy se metoda pozastaví, dokud nebude 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 upraví, 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 události a StartButton_Clickasynchronní 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 Windows Store, kterou vytvoříte v Visual Studio; podívejte se na komentáře ke kódu pro nastavení aplikace.

Tento kód můžete spustit v Visual Studio jako aplikaci Windows Presentation Foundation (WPF) nebo aplikaci Windows Storu. 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 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 úkol, naleznete v části Asynchronní programování pomocí async 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 se obecně nedoporučuje 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.
  • Počínaje jazykem C# 7.0 je jakýkoli typ, který má přístupnou GetAwaiter metodu. Typ System.Threading.Tasks.ValueTask<TResult> je jednou z těchto 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 používáte primárně k definování obslužných rutin událostí, které vyžadují tento návratový typ. Volající voidmetody -returning async ji nemůže očekávat a nemůže zachytit výjimky, které metoda vyvolá.

Počínaje jazykem C# 7.0 vrátíte jiný typ, obvykle typ hodnoty, který má metodu GetAwaiter minimalizace přidělení paměti v částech kódu kritických pro výkon.

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

Viz také