Partager via

async (référence C#)

Utilisez le modificateur async pour spécifier qu’une méthode, une expression lambda ou une méthode anonyme sont asynchrones. Si vous utilisez ce modificateur sur une méthode ou une expression, vous créez une méthode asynchrone. L’exemple suivant définit une méthode async nommée ExampleMethodAsync :

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

La documentation de référence du langage C# décrit la version la plus récente du langage C#. Il contient également la documentation initiale des fonctionnalités dans les préversions publiques pour la prochaine version du langage.

La documentation identifie toute fonctionnalité introduite en premier dans les trois dernières versions de la langue ou dans les préversions publiques actuelles.

Conseil / Astuce

Pour savoir quand une fonctionnalité a été introduite en C#, consultez l’article sur l’historique des versions du langage C#.

Si vous débutez avec la programmation asynchrone ou que vous ne comprenez pas comment une méthode asynchrone utilise l’opérateurawait pour effectuer un travail potentiellement long sans bloquer le thread de l’appelant, lisez l’introduction de la programmation asynchrone avec async et await. Le code suivant se trouve dans une méthode async et appelle la méthode HttpClient.GetStringAsync :

string contents = await httpClient.GetStringAsync(requestUrl);

Une méthode asynchrone s’exécute de manière synchrone jusqu’à ce qu’elle atteigne sa première await expression. À ce stade, la méthode est suspendue jusqu’à ce que la tâche attendue soit terminée. 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.

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. 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. Consultez Avertissement du compilateur (niveau 1) CS4014.

Le async mot clé est contextuel. Il s’agit d’un mot clé uniquement lorsqu’il modifie une méthode, une expression lambda ou une méthode anonyme. Dans tous les autres contextes, le compilateur l’interprète en tant qu’identificateur.

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. Le résultat de la méthode async est le nombre de caractères d’une page web. Le code convient pour une application Windows Presentation Foundation (WPF) ou une application du Windows Store que vous créez dans Visual Studio. Consultez les commentaires de code pour configurer l’application.

Vous pouvez exécuter ce code dans Visual Studio en tant qu’application Windows Presentation Foundation (WPF) ou qu’application du Windows Store. Vous avez besoin d’un contrôle Button nommé StartButton et d’un contrôle Textbox nommé ResultsTextBox. N’oubliez pas de définir les noms et le gestionnaire afin d’obtenir un résultat semblable à ceci :

<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 :

  • Collez ce code dans la classe MainWindow dans MainWindow.xaml.cs.
  • Ajoutez une référence à System.Net.Http.
  • Ajoutez une directive using à System.Net.Http.

Pour exécuter le code comme une application du Windows Store :

  • Collez ce code dans la classe MainPage dans MainPage.xaml.cs.
  • Ajouter des directives using pour System.Net.Http et 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. Pour obtenir un exemple de console complète qui utilise des éléments similaires, consultez Traiter les tâches asynchrones à mesure qu’elles se terminent (C#).

Types de retour

Une méthode async peut avoir les types de retour suivants :

  • Task
  • Task<TResult>
  • void. En règle générale, évitez d’utiliser async void des méthodes pour du code autre que les gestionnaires d’événements, car les appelants ne peuvent pas await ces méthodes et doivent implémenter un mécanisme différent pour signaler la réussite de la saisie semi-automatique ou des conditions d’erreur.
  • Tout type qui a une méthode accessible GetAwaiter. Le type System.Threading.Tasks.ValueTask<TResult> est une implémentation de ce genre. Il est disponible en ajoutant le package System.Threading.Tasks.ExtensionsNuGet .

La méthode asynchrone ne peut pas déclarer de paramètres, refref readonlyni out déclarer inde valeur de retour de référence. Toutefois, il peut appeler des méthodes qui ont de tels paramètres.

Spécifiez Task<TResult> comme type de retour d’une méthode asynchrone si l’instruction return de la méthode spécifie un opérande de type TResult. Utilisez Task si la méthode ne retourne aucune valeur significative lorsqu’elle est terminée. 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. Utilisez le void type de retour principalement pour définir des gestionnaires d’événements, qui nécessitent ce type de retour. 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. Retournez un autre type, généralement un type valeur, qui a une GetAwaiter méthode pour réduire les allocations de mémoire dans les sections critiques de performances du code.

Pour obtenir plus d’informations et des exemples, consultez Types de retour Async.

Voir aussi

  • Last updated on