async (Riferimenti per C#)async (C# Reference)

Usare il modificatore async per specificare che un metodo, un'espressione lambda o un metodo anonimo sia asincrono.Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Se si usa questo modificatore in un metodo o in un'espressione, viene indicato come metodo asincrono.If you use this modifier on a method or expression, it's referred to as an async method. L'esempio seguente definisce un metodo asincrono denominato ExampleMethodAsync:The following example defines an async method named ExampleMethodAsync:

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

Se non si ha esperienza di programmazione asincrona o non si sa in che modo un metodo asincrono usa la parola chiave await per eseguire attività potenzialmente prolungate senza bloccare il thread del chiamante, leggere l'introduzione in Programmazione asincrona con async e await.If you're new to asynchronous programming or do not understand how an async method uses the await keyword to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. Il codice seguente si trova all'interno di un metodo asincrono e chiama il metodo HttpClient.GetStringAsync:The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Un metodo asincrono viene eseguito in modo sincrono finché non raggiunge la prima espressione await. A quel punto, il metodo viene sospeso fino al completamento dell'attività attesa.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. Nel frattempo il controllo torna al chiamante del metodo, come illustrato nell'esempio della sezione successiva.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Il metodo modificato dalla parola chiave async viene eseguito in modo sincrono se non contiene un'espressione o un'istruzione await.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Un avviso del compilatore segnala eventuali metodi asincroni che non contengono istruzioni await, perché questa situazione potrebbe indicare un errore.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Vedere Avviso del compilatore (livello 1) CS4014.See Compiler Warning (level 1) CS4014.

La parola chiave async è contestuale, in quanto è una parola chiave solo quando modifica un metodo, un'espressione lambda o un metodo anonimo.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. In tutti gli altri contesti, viene interpretato come identificatore.In all other contexts, it's interpreted as an identifier.

EsempioExample

Nell'esempio seguente vengono illustrati la struttura e il flusso di controllo tra un gestore eventi asincrono, StartButton_Click, e un metodo asincrono, ExampleMethodAsync.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. Il risultato ottenuto dal metodo asincrono è il numero di caratteri di una pagina Web.The result from the async method is the number of characters of a web page. Il codice è adatto per un'applicazione Windows Presentation Foundation (WPF) o un'app di Windows Store creata in Visual Studio. Vedere i commenti del codice per l'installazione dell'applicazione.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.

È possibile eseguire questo codice in Visual Studio come un'app Windows Presentation Foundation (WPF) o un'app di Windows Store.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Sono necessari un controllo Button denominato StartButton e un controllo Textbox denominato ResultsTextBox.You need a Button control named StartButton and a Textbox control named ResultsTextBox. Ricordare di impostare i nomi e il gestore in modo da ottenere codice simile al seguente: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"/>  

Per eseguire il codice come app WPF:To run the code as a WPF app:

  • Incollare il codice nella classe MainWindow in MainWindow.xaml.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Aggiungere un riferimento a System.Net.Http.Add a reference to System.Net.Http.
  • Aggiungere una direttiva using per System.Net.Http.Add a using directive for System.Net.Http.

Per eseguire il codice come app di Windows Store:To run the code as a Windows Store app:

  • Incollare questo codice nella classe MainPage in MainPage.xaml.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Aggiungere direttive using per System.Net.Http e 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  

Importante

Per altre informazioni sulle attività e sul codice eseguito in attesa di un'attività, vedere Programmazione asincrona con async e await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Per un esempio di WPF completo che usa elementi simili, vedere Procedura dettagliata: accesso al Web tramite async e await.For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Tipi restituitiReturn Types

Un metodo asincrono può avere i tipi restituiti seguenti:An async method can have the following return types:

  • Task
  • Task<TResult>
  • void, che deve essere usato solo per i gestori eventi.void, which should only be used for event handlers.
  • A partire da C# 7, qualsiasi tipo con un metodo GetAwaiter accessibile.Starting with C# 7, any type that has an accessible GetAwaiter method. Il tipo System.Threading.Tasks.ValueTask<TResult> è una di queste implementazioniThe System.Threading.Tasks.ValueTask<TResult> type is one such implementation. ed è disponibile aggiungendo il pacchetto NuGet System.Threading.Tasks.Extensions.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

Un metodo asincrono non può dichiarare parametri in, ref o out e nemmeno avere un valore di riferimento restituito , ma può chiamare metodi con tali parametri.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.

Specificare Task<TResult> come tipo restituito di un metodo asincrono se l'istruzione return del metodo specifica un operando di tipo 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. Utilizzare Task se non viene restituito alcun valore significativo al completamento del metodo.You use Task if no meaningful value is returned when the method is completed. Ciò significa che una chiamata al metodo restituisce Task, ma al completamento di Task, qualsiasi espressione await in attesa di Task restituisce void.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.

Utilizzare il tipo restituito void principalmente per definire gestori eventi, che richiedono tale tipo restituito.You use the void return type primarily to define event handlers, which require that return type. Il chiamante di un metodo asincrono che restituisce void non può attendere il metodo e non può acquisire eccezioni generate dal metodo.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

A partire da C# 7, si restituisce a un altro tipo, in genere un tipo valore, che ha un metodo GetAwaiter per ridurre al minimo le allocazioni di memoria nelle sezioni del codice critiche per le prestazioni.Starting with C# 7, you return another type, typically a value type, that has a GetAwaiter method to miminize memory allocations in performance-critical sections of code.

Per altre informazioni ed esempi, vedere Tipi restituiti asincroni.For more information and examples, see Async Return Types.

Vedere ancheSee Also

AsyncStateMachineAttribute
awaitawait
Procedura dettagliata: Accesso al Web tramite Async e AwaitWalkthrough: Accessing the Web by Using Async and Await
Programmazione asincrona con async e awaitAsynchronous Programming with async and await