async (odwołanie w C#)async (C# Reference)

Użyj modyfikatora, aby określić, że metoda, wyrażenie lambdalub Metoda anonimowa jest asynchroniczna. asyncUse the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Jeśli używasz tego modyfikatora w metodzie lub wyrażeniu, jest on nazywany metodą Async.If you use this modifier on a method or expression, it's referred to as an async method. W poniższym przykładzie zdefiniowano metodę asynchroniczną ExampleMethodAsynco nazwie:The following example defines an async method named ExampleMethodAsync:

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

Jeśli dopiero zaczynasz programowanie asynchroniczne lub nie wiesz, w jaki sposób Metoda async używa await operatora , aby wykonać potencjalnie długotrwałą działanie bez blokowania wątku wywołującego, przeczytaj wprowadzenie do programowania asynchronicznego przy użyciu Async i await.If 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. Poniższy kod znajduje się w metodzie asynchronicznej i wywołuje HttpClient.GetStringAsync metodę:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Metoda async jest uruchamiana synchronicznie do momentu, await aż osiągnie swoje pierwsze wyrażenie, w którym momencie Metoda jest wstrzymana do momentu ukończenia zadania.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. W międzyczasie sterowanie jest przekazywane do obiektu wywołującego metody, tak jak pokazano w przykładzie w następnej sekcji.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Jeśli metoda modyfikowana przez async słowo kluczowe nie await zawiera wyrażenia lub instrukcji, metoda jest wykonywana synchronicznie.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Ostrzeżenie kompilatora ostrzega użytkownika o wszelkich metodach asynchronicznych, które await nie zawierają instrukcji, ponieważ taka sytuacja może wskazywać na błąd.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Zobacz Ostrzeżenie kompilatora (poziom 1) CS4014.See Compiler Warning (level 1) CS4014.

async Słowo kluczowe jest kontekstowe, ponieważ jest słowem kluczowym tylko wtedy, gdy modyfikuje metodę, wyrażenie lambda lub metodę anonimową.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. W innych kontekstach jest interpretowane jako identyfikator.In all other contexts, it's interpreted as an identifier.

PrzykładExample

Poniższy przykład pokazuje strukturę i przepływ kontroli między obsługą StartButton_Clickzdarzeń asynchronicznych, i ExampleMethodAsyncmetodę asynchroniczną.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. Wynikiem metody asynchronicznej jest liczba znaków strony sieci Web.The result from the async method is the number of characters of a web page. Kod jest odpowiedni dla aplikacji Windows Presentation Foundation (WPF) lub aplikacji ze sklepu Windows, którą tworzysz w programie Visual Studio; Zobacz komentarze do kodu dotyczące konfigurowania aplikacji.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.

Ten kod można uruchomić w programie Visual Studio jako aplikacja Windows Presentation Foundation (WPF) lub aplikacja ze sklepu Windows.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Potrzebujesz formantu Button o nazwie StartButton i kontrolki TextBox o nazwie. ResultsTextBoxYou need a Button control named StartButton and a Textbox control named ResultsTextBox. Pamiętaj, aby ustawić nazwy i obsługę, tak aby wyglądały następująco: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"/>  

Aby uruchomić kod jako aplikację WPF:To run the code as a WPF app:

  • Wklej ten kod do MainWindow klasy w MainWindow.XAML.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Dodaj odwołanie do systemu .NET. http.Add a reference to System.Net.Http.
  • using Dodaj dyrektywę dla systemu .NET. http.Add a using directive for System.Net.Http.

Aby uruchomić kod jako aplikację ze sklepu Windows:To run the code as a Windows Store app:

  • Wklej ten kod do MainPage klasy w MainPage.XAML.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Dodaj dyrektywy using dla systemu .NET. http i 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  

Ważne

Aby uzyskać więcej informacji o zadaniach i kodzie, który jest wykonywany podczas oczekiwania na zadanie, zobacz programowanie asynchroniczne z Async i await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Aby zapoznać się z pełnym przykładem WPF, który używa podobnych elementów, zobacz Przewodnik: Uzyskiwanie dostępu do sieci Web za pomocąAsync i await.For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Typy zwracaneReturn Types

Metoda asynchroniczna może mieć następujące zwracane typy:An async method can have the following return types:

  • Task
  • Task<TResult>
  • typ void.void. async voidmetody są generalnie odradzane dla kodu innego niż programy obsługi zdarzeń, ponieważ obiekty wywołujące nie mogą await być tymi metodami i muszą implementować inny mechanizm, aby zgłosić pomyślne zakończenie lub błędy.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.
  • Począwszy od C# 7,0, dowolnego typu, który ma dostępną GetAwaiter metodę.Starting with C# 7.0, any type that has an accessible GetAwaiter method. System.Threading.Tasks.ValueTask<TResult> Typ to taka implementacja.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Jest on dostępny przez dodanie pakietu System.Threading.Tasks.ExtensionsNuGet.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

Metoda async nie może deklarować żadnych parametrów in, ref ani out ani nie może mieć wartości zwracanej przez odwołanie, ale może wywoływać metody, które mają takie 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.

Należy określić Task<TResult> jako zwracany typ metody asynchronicznej, jeśli instrukcja Return metody określa argument operacji 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. Należy użyć Task , jeśli podczas kończenia metody nie zostanie zwrócona wartość znacząca.You use Task if no meaningful value is returned when the method is completed. Oznacza to, Taskże wywołanie metody zwraca, ale Task po zakończeniu, dowolne await wyrażenie, voidktóre oczekuje Task na wartości.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.

Typ void zwracany jest używany głównie do definiowania programów obsługi zdarzeń, które wymagają tego typu zwracanego.You use the void return type primarily to define event handlers, which require that return type. Obiekt wywołujący metodę voidasynchroniczną zwracającą wartość, której nie może oczekiwać i nie może przechwytywać wyjątków zgłaszanych przez metodę.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

Począwszy od C# 7,0, zwracany jest inny typ, zazwyczaj typ wartości, który ma GetAwaiter metodę, aby zminimalizować alokacje pamięci w sekcjach o krytycznym znaczeniu dla wydajności kodu.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.

Aby uzyskać więcej informacji i przykładów, zobacz asynchroniczne typy zwracane.For more information and examples, see Async Return Types.

Zobacz takżeSee also