async (référence C#)async (C# Reference)

Utilisez le modificateur async pour spécifier qu’une méthode, une expression lambda ou une méthode anonyme sont asynchrones.Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. Si vous utilisez ce modificateur sur une méthode ou une expression, il s’agit d’une méthode async.If you use this modifier on a method or expression, it's referred to as an async method. L’exemple suivant définit une méthode async nommée ExampleMethodAsync :The following example defines an async method named ExampleMethodAsync:

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

Si vous débutez en programmation asynchrone ou que vous ne comprenez pas comment une méthode async utilise le mot clé await pour un travail potentiellement long sans bloquer le thread de l’appelant, lisez l’introduction dans Programmation asynchrone avec async et 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. Le code suivant se trouve dans une méthode async et appelle la méthode HttpClient.GetStringAsync :The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

Une méthode async s’exécute de façon synchrone jusqu’à ce qu’elle atteigne sa première expression await, où elle est suspendue jusqu’à ce que la tâche attendue soit terminée.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. Dans le même temps, le contrôle retourne à l'appelant de la méthode, comme le montre l'exemple indiqué dans la section suivante.In the meantime, control returns to the caller of the method, as the example in the next section shows.

Si la méthode que le mot clé async modifie ne contient pas une expression ou une instruction await, la méthode s'exécute de façon synchrone.If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. Un avertissement du compilateur vous signale toutes les méthodes async qui ne contiennent pas d’instructions await, car cette situation peut indiquer une erreur.A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. Consultez Avertissement du compilateur (niveau 1) CS4014.See Compiler Warning (level 1) CS4014.

Le mot clé async est contextuel, car il est un mot clé uniquement lorsqu'il modifie une méthode, une expression lambda ou une méthode anonyme.The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. Dans tous les autres contextes, il est interprété comme un identificateur.In all other contexts, it's interpreted as an identifier.

ExempleExample

L'exemple suivant montre la structure et le flux de contrôle entre un gestionnaire d'événements asynchrones, StartButton_Click, et une méthode async, ExampleMethodAsync.The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. Le résultat de la méthode async est le nombre de caractères d’une page web.The result from the async method is the number of characters of a web page. Le code convient pour une application WPF (Windows Presentation Foundation) ou une application du Windows Store que vous créez dans Visual Studio ; consultez les commentaires du code pour configurer l’application.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.

Vous pouvez exécuter ce code dans Visual Studio en tant qu’application Windows Presentation Foundation (WPF) ou qu’application du Windows Store.You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. Vous avez besoin d’un contrôle Button nommé StartButton et d’un contrôle Textbox nommé ResultsTextBox.You need a Button control named StartButton and a Textbox control named ResultsTextBox. N’oubliez pas de définir les noms et le gestionnaire afin d’obtenir un résultat semblable à ceci :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"/>  

Pour exécuter le code en tant qu’application WPF :To run the code as a WPF app:

  • Collez ce code dans la classe MainWindow dans MainWindow.xaml.cs.Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • Ajoutez une référence à System.Net.Http.Add a reference to System.Net.Http.
  • Ajoutez une directive using à System.Net.Http.Add a using directive for System.Net.Http.

Pour exécuter le code comme une application du Windows Store :To run the code as a Windows Store app:

  • Collez ce code dans la classe MainPage dans MainPage.xaml.cs.Paste this code into the MainPage class in MainPage.xaml.cs.
  • Ajouter des directives using pour System.Net.Http et 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  

Important

Pour plus d’informations sur les tâches et sur le code qui s’exécute en attendant une tâche, consultez Programmation asynchrone avec async et await.For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. Pour obtenir un exemple WPF complet qui utilise des éléments similaires, consultez Procédure pas à pas : accès au web avec Async et Await.For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

Types de retoursReturn Types

Une méthode async peut avoir les types de retour suivants :An async method can have the following return types:

  • Task
  • Task<TResult>
  • void, qui doit être utilisé uniquement pour les gestionnaires d’événements.void, which should only be used for event handlers.
  • À compter de C# 7, tout type ayant une méthode GetAwaiter accessible.Starting with C# 7, any type that has an accessible GetAwaiter method. Le type System.Threading.Tasks.ValueTask<TResult> est une implémentation de ce genre.The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. Il est disponible en ajoutant le package NuGet System.Threading.Tasks.Extensions.It is available by adding the NuGet package System.Threading.Tasks.Extensions.

La méthode async ne peut déclarer aucun paramètre in, ref ou out, ni avoir une valeur de retour de référence, mais elle peut appeler des méthodes qui ont ces paramètres.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.

Vous spécifiez Task<TResult> comme type de retour d’une méthode async si l’instruction return de la méthode spécifie un opérande de type 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. Utilisez Task si aucune valeur significative n'est retournée lorsque la méthode est terminée.You use Task if no meaningful value is returned when the method is completed. En d'autres termes, un appel à la méthode retourne Task, mais lorsque Task est terminé, toute expression await qui attend Task prend la valeur 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.

Vous utilisez le type de retour void principalement pour définir les gestionnaires d'événements, qui ont besoin de ce type de retour.You use the void return type primarily to define event handlers, which require that return type. L'appelant d'une méthode async retournant void ne peut pas l'attendre et ne peut pas intercepter les exceptions levées par la méthode.The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

À compter de C# 7, vous retournez un autre type, en général un type valeur, qui a une méthode GetAwaiter pour limiter les allocations de mémoire dans les sections de code critiques pour les performances.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.

Pour obtenir plus d’informations et des exemples, consultez Types de retour Async.For more information and examples, see Async Return Types.

Voir aussiSee Also

AsyncStateMachineAttribute
awaitawait
Procédure pas à pas : accès au web avec Async et AwaitWalkthrough: Accessing the Web by Using Async and Await
Programmation asynchrone avec Async et AwaitAsynchronous Programming with async and await