await (Référence C#)

Article
06/10/2015

L'opérateur await est appliqué à une tâche dans une méthode asynchrone pour interrompre l'exécution de la méthode jusqu'à ce que la tâche attendue se termine. La tâche représente le travail en cours.

La méthode asynchrone dans laquelle await est utilisé doit être modifiée par le mot clé async. Une telle méthode, définie en utilisant le modificateur async, et contenant généralement une ou plusieurs expressions await, est appelée méthode asynchrone.

Notes

Les mots clés async et await ont été introduits dans Visual Studio 2012.Pour une présentation de la programmation asynchrone, consultez Programmation asynchrone avec Async et Await (C# et Visual Basic).

La tâche à laquelle l'opérateur await est appliqué est généralement la valeur de retour d'un appel à une méthode qui implémente le modèle asynchrone basé sur des tâches. Les exemples incluent des valeurs de type Task ou Task.

Dans le code suivant, la méthode HttpClient GetByteArrayAsync retourne Task<byte[]>, getContentsTask. La tâche est la promesse de produire le tableau d'octets réel lorsque la tâche est terminée. L'opérateur await est appliqué à getContentsTask pour interrompre l'exécution dans SumPageSizesAsync jusqu'à ce que getContentsTask soit terminé. Dans le même temps, le contrôle retourne à l'appelant de SumPageSizesAsync, . Lorsque getContentsTask est terminé, l'expression await correspond à un tableau d'octets.

private async Task SumPageSizesAsync()
{
    // To use the HttpClient type in desktop apps, you must include a using directive and add a 
    // reference for the System.Net.Http namespace.
    HttpClient client = new HttpClient();
    // . . .
    Task<byte[]> getContentsTask = client.GetByteArrayAsync(url);
    byte[] urlContents = await getContentsTask;

    // Equivalently, now that you see how it works, you can write the same thing in a single line.
    //byte[] urlContents = await client.GetByteArrayAsync(url);
    // . . .
}

Important

Pour obtenir un exemple complet, consultez Procédure pas à pas : accès au Web avec Async et Await (C# et Visual Basic).Vous pouvez télécharger l'exemple à partir de Exemples de code du développeur sur le site Web Microsoft.L'exemple se trouve dans le projet AsyncWalkthrough_HttpClient.

Comme indiqué dans l'exemple précédent, si await est appliqué au résultat d'un appel de méthode qui retourne un Task<TResult>, le type de l'expression d' await est alors TResult. Si await est appliqué au résultat d'un appel de méthode qui retourne Task, le type de l'expression await est void. La différence est illustrée dans l'exemple suivant.

// Keyword await used with a method that returns a Task<TResult>.
TResult result = await AsyncMethodThatReturnsTaskTResult();

// Keyword await used with a method that returns a Task.
await AsyncMethodThatReturnsTask();

Une expression await ne bloque pas le thread sur lequel elle s'exécute. À la place, il provoque la connexion du compilateur au reste de la méthode async comme une continuation sur la tâche attendue. Contrôle, puis retourne à l'appelant de la méthode async. Lorsque la tâche se termine, elle appelle sa continuation, et l'exécution de la méthode async reprend où elle a été arrêtée.

Une expression await ne peut se produire que dans le corps d'une méthode immédiatement englobante, d'une expression lambda, ou d'une méthode anonyme qui est marquée par un modificateur async. Le terme await sert de mot clé uniquement dans ce contexte. Ailleurs, il est interprété comme un identificateur. Dans la méthode, l'expression lambda ou la méthode anonyme, une expression await ne peut pas se produire dans le corps d'une fonction asynchrone, dans une expression de requête, dans le bloc catch ou finally d'une instruction de gestion des exceptions, dans le bloc d'une instruction lock ou dans un contexte unsafe.

Exceptions

La plupart des méthodes async retournent Task ou Task. Les propriétés de la tâche retournée contiennent des informations sur son état et son historique, par exemple si la tâche est terminée, si la méthode async a provoqué une exception ou a été annulée ainsi que le résultat final. L'opérateur await accède à ces propriétés.

Si vous attendez une méthode asynchrone de retour de tâche qui provoque une exception, l'opérateur await relève l'exception.

Si vous attendez une méthode asynchrone de retour de tâche qui est annulée, l'opérateur await relève OperationCanceledException.

Une tâche unique avec un état d'erreur peut refléter plusieurs exceptions. Par exemple, la tâche peut être le résultat d'un appel à Task.WhenAll. Lorsque vous attendez une telle tâche, l'opération await lève à nouveau une seule des exceptions. Toutefois, vous ne pouvez pas prédire quelles exceptions seront immédiatement levées.

Pour obtenir des exemples de gestion des erreurs dans des méthodes async, consultez try-catch (référence C#).

Exemple

L'exemple Windows Forms suivant illustre l'utilisation d'await dans une méthode async, WaitAsynchronouslyAsync. Comparez le comportement de cette méthode avec le comportement de WaitSynchronously. Sans un opérateur await appliqué à une tâche, WaitSynchronously s'exécute de façon synchrone malgré l'utilisation du modificateur async dans sa définition et un appel à Thread.Sleep dans son corps.

private async void button1_Click(object sender, EventArgs e)
{
    // Call the method that runs asynchronously.
    string result = await WaitAsynchronouslyAsync();

    // Call the method that runs synchronously.
    //string result = await WaitSynchronously ();

    // Display the result.
    textBox1.Text += result;
}

// The following method runs asynchronously. The UI thread is not
// blocked during the delay. You can move or resize the Form1 window 
// while Task.Delay is running.
public async Task<string> WaitAsynchronouslyAsync()
{
    await Task.Delay(10000);
    return "Finished";
}

// The following method runs synchronously, despite the use of async.
// You cannot move or resize the Form1 window while Thread.Sleep
// is running because the UI thread is blocked.
public async Task<string> WaitSynchronously()
{
    // Add a using directive for System.Threading.
    Thread.Sleep(10000);
    return "Finished";
}

Voir aussi

Partager via

await (Référence C#)

Exceptions

Exemple

Voir aussi

Tâches

Référence

Concepts

Ressources supplémentaires