await (Référence C#)

Article
03/12/2013

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

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

[!REMARQUE]

Les mots clés d' async et d' await ont été introduits dans Visual Studio 2012.Pour plus d'informations sur les nouvelles fonctionnalités dans cette version, consultez Nouveautés de Visual Studio 2012.

Pour une introduction à l'async programmation, consultez l' Programmation asynchrone avec Async et Await (C# et Visual Basic).

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

Dans le code suivant, la méthode GetByteArrayAsync d' HttpClient retourne Task<byte[]>, getContentsTask.La tâche est une promesse de produire un tableau d'octets réel lorsque la tâche est terminée.L'opérateur d' await est appliqué à getContentsTask pour interrompre l'exécution dans SumPageSizesAsync jusqu'à ce qu' getContentsTask terminé.Dans le même temps, le contrôle est retourné à l'appelant d' SumPageSizesAsync.Lorsque getContentsTask est terminé, l'expression d' 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 de provenant Exemples de code de développement sur le site Web Microsoft.L'exemple se trouve dans le projet d'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 Task<TResult>, le type de l'expression d' await est TResult.Si await est appliqué au résultat d'un appel de méthode qui retourne Task, le type de l'expression d' await est void.L'exemple suivant illustre la différence.

// 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 d' await ne bloque pas le thread sur lequel il s'exécute.À la place, il effectue enregistrer le compilateur le reste de la méthode async comme une suite de la tâche attendue.Le contrôle retourne ensuite à 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 continue où il a été arrêté.

Une expression d' await peut se produire 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 d' async .Le terme attendent sert de mot clé uniquement dans ce contexte.Ailleurs, il est interprète comme identificateur.Dans la méthode, l'expression lambda, ou la méthode anonyme, une expression d' await ne peut pas se produire dans le corps d'une fonction synchrones, dans une expression de requête, dans le bloc d' catch ou d' finally d' instruction de gestion des exceptions, dans le bloc d' instruction lock, ou dans un contexte d' unsafe .

Exceptions

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

Si vous attendez une méthode tâche- se retournante async qui provoque une exception, le rethrows d'opérateur d' await l'exception.

Si vous attendez une méthode tâche- se retournante async qui est annulée, les rethrows d'opérateur d' awaitOperationCanceledException.

Une tâche unique qui est dans un état censuré 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, les rethrows un seul d'opération d'attente des exceptions.Toutefois, vous ne pouvez pas prédire lesquelles les exceptions sont à nouveau levée.

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

Exemple

L'exemple suivant Windows Forms illustre l'utilisation d' await dans une méthode async, WaitAsynchronouslyAsync.Comparez le comportement de cette méthode avec le comportement d' WaitSynchronously.Sans opérateur d' await appliqué à une tâche, WaitSynchronously fonctionne de façon synchrone en dépit de l'utilisation du modificateur d' async dans sa définition et un appel à Thread.Sleep à 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