async (Referenční dokumentace jazyka C#)async (C# Reference)

Použijte modifikátor k určení toho, že metoda, výraz lambdanebo anonymní metoda je asynchronní. asyncUse the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Použijete-li tento modifikátor na metodu nebo výraz, je označována jako asynchronní metoda.If you use this modifier on a method or expression, it's referred to as an async method. Následující příklad definuje asynchronní metodu s názvem ExampleMethodAsync:The following example defines an async method named ExampleMethodAsync:

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

Pokud začínáte s asynchronním programováním nebo nerozumíte, jak asynchronní metoda používá await operátor pro potenciálně dlouhotrvající práci bez blokování vlákna volajícího, přečtěte si Úvod do asynchronního programování s Async a awaitIf you're new to asynchronous programming or do not understand how an async method uses the await operator to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. Následující kód byl nalezen v asynchronní metodě a volá HttpClient.GetStringAsync metodu:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Asynchronní metoda běží synchronně, dokud nedosáhne svého prvního await výrazu, v tomto okamžiku je metoda pozastavena, dokud není dokončen očekávaný úkol.An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. 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.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Pokud metoda, kterou async klíčové slovo upravuje await , neobsahuje výraz nebo příkaz, metoda se provede synchronně.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Upozornění kompilátoru vás upozorní na jakékoli asynchronní metody, které neobsahují await příkazy, protože tato situace může znamenat chybu.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Viz Upozornění kompilátoru (úroveň 1) CS4014.See Compiler Warning (level 1) CS4014.

async Klíčové 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.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. Ve všech ostatních kontextech je interpretováno jako identifikátor.In all other contexts, it's interpreted as an identifier.

PříkladExample

Následující příklad ukazuje strukturu a tok řízení mezi obslužnou rutinou asynchronní události, StartButton_Clicka asynchronní ExampleMethodAsyncmetodou.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. Výsledek z asynchronní metody je počet znaků webové stránky.The result from the async method is the number of characters of a web page. Kód je vhodný pro aplikaci Windows Presentation Foundation (WPF) nebo aplikaci pro Windows Store, kterou vytvoříte v aplikaci Visual Studio; Podívejte se na komentáře ke kódu pro nastavení aplikace.The code is suitable for a Windows Presentation Foundation (WPF) app or Windows Store app that you create in Visual Studio; see the code comments for setting up the app.

Tento kód můžete spustit v aplikaci Visual Studio jako aplikaci Windows Presentation Foundation (WPF) nebo aplikace pro Windows Store.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Potřebujete ovládací prvek tlačítko s názvem StartButton a ovládací prvek TextBox s ResultsTextBoxnázvem.You need a Button control named StartButton and a Textbox control named ResultsTextBox. Nezapomeňte nastavit názvy a obslužné rutiny tak, abyste měli něco podobného: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="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>  

Spuštění kódu jako aplikace WPF:To run the code as a WPF app:

  • Vložte tento kód do MainWindow třídy v MainWindow.XAML.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Přidejte odkaz na System .NET. http.Add a reference to System.Net.Http.
  • using Přidejte direktivu pro System .NET. http.Add a using directive for System.Net.Http.

Spuštění kódu jako aplikace pro Windows Store:To run the code as a Windows Store app:

  • Vložte tento kód do MainPage třídy v MainPage.XAML.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Přidejte direktivy using pro System .NET. http a System. Threading. Tasks.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: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 úlohách a kódu, který se spouští při čekání na úlohu, naleznete v tématu asynchronní programování s modifikátorem Async a await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Úplný příklad WPF, který používá podobné prvky, naleznete v tématu Návod: Přístup k webu pomocí modifikátoru Async aoperátoru awaitFor a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Návratové typyReturn Types

Asynchronní metoda může mít následující návratové typy:An async method can have the following return types:

  • Task
  • Task<TResult>
  • void.void. async voidmetody se obecně nedoporučují pro jiný kód než obslužné rutiny událostí, protože await volající nemůžou tyto metody a musí implementovat jiný mechanismus, aby hlásili úspěšné dokončení nebo chybové stavy.async void methods are generally discouraged for code other than event handlers because callers cannot await those methods and must implement a different mechanism to report successful completion or error conditions.
  • Počínaje C# 7,0, jakýkoli typ, který má přístupnou GetAwaiter metodu.Starting with C# 7.0, any type that has an accessible GetAwaiter method. System.Threading.Tasks.ValueTask<TResult> Typ představuje jednu takovou implementaci.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Je k dispozici přidáním balíčku System.Threading.Tasks.ExtensionsNuGet.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

Asynchronní metoda nemůže deklarovat jakýkoli parametr in, ref nebo out , ani nemůže mít odkazovou návratovou hodnotu, ale může volat metody, které mají tyto parametry.The async method can't declare any in, ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

Zadáte Task<TResult> jako návratový typ asynchronní metody, pokud příkaz return metody určuje operand typu TResult.You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. Použijete Task , pokud není vrácena žádná smysluplná hodnota po dokončení metody.You use Task if no meaningful value is returned when the method is completed. To znamená, Taskže volání metody vrátí, ale Task po dokončení je libovolný await výraz void, který čeká Task na vyhodnotit.That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

Pro definování obslužných rutin událostí, které vyžadují návratový typ, použijte void primárně návratový typ.You use the void return type primarily to define event handlers, which require that return type. Volající voidasynchronní metody vracející výjimku nemůže očekávat a zachytit výjimky, které metoda vyvolá.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

Počínaje C# 7,0 vrátíte jiný typ, obvykle hodnotový typ, který má GetAwaiter metodu pro minimalizaci přidělení paměti v částech v kódu kritickém pro výkon.Starting with C# 7.0, you return another type, typically a value type, that has a GetAwaiter method to minimize memory allocations in performance-critical sections of code.

Další informace a příklady naleznete v tématu Async Return Types.For more information and examples, see Async Return Types.

Viz také:See also