Opérateur await (informations de référence sur C#)await operator (C# reference)

L’opérateur await suspend l’évaluation de la méthode async englobante jusqu’à ce que l’opération asynchrone représentée par son opérande se termine.The await operator suspends evaluation of the enclosing async method until the asynchronous operation represented by its operand completes. Une fois l’opération asynchrone terminée, l’opérateur await retourne le résultat de l’opération, le cas échéant.When the asynchronous operation completes, the await operator returns the result of the operation, if any. Quand l’opérateur await est appliqué à l’opérande qui représente l’opération déjà terminée, il retourne immédiatement le résultat de l’opération sans suspendre la méthode englobante.When the await operator is applied to the operand that represents already completed operation, it returns the result of the operation immediately without suspension of the enclosing method. L’opérateur await ne bloque pas le thread qui évalue la méthode async.The await operator doesn't block the thread that evaluates the async method. Quand l’opérateur await suspend la méthode englobante, le contrôle retourne à l’appelant de la méthode.When the await operator suspends the enclosing method, the control returns to the caller of the method.

Dans l’exemple suivant, la méthode HttpClient.GetByteArrayAsync retourne l’instance Task<byte[]>, qui représente une opération asynchrone qui produit un tableau d’octets au moment où elle se termine.In the following example, the HttpClient.GetByteArrayAsync method returns the Task<byte[]> instance, which represents an asynchronous operation that produces a byte array when it completes. Tant que l’opération n’est pas terminée, l’opérateur await suspend la méthode DownloadDocsMainPageAsync.Until the operation completes, the await operator suspends the DownloadDocsMainPageAsync method. Quand la méthode DownloadDocsMainPageAsync est suspendue, le contrôle est retourné à la méthode Main, qui est l’appelant de DownloadDocsMainPageAsync.When DownloadDocsMainPageAsync gets suspended, control is returned to the Main method, which is the caller of DownloadDocsMainPageAsync. La méthode Main s’exécute jusqu’à ce qu’elle ait besoin du résultat de l’opération asynchrone effectuée par la méthode DownloadDocsMainPageAsync.The Main method executes until it needs the result of the asynchronous operation performed by the DownloadDocsMainPageAsync method. Une fois que tous les octets ont été obtenus par GetByteArrayAsync, le reste de la méthode DownloadDocsMainPageAsync est évalué.When GetByteArrayAsync gets all the bytes, the rest of the DownloadDocsMainPageAsync method is evaluated. Après cela, le reste de la méthode Main est évalué.After that, the rest of the Main method is evaluated.

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class AwaitOperator
{
    public static async Task Main()
    {
        Task<int> downloading = DownloadDocsMainPageAsync();
        Console.WriteLine($"{nameof(Main)}: Launched downloading.");

        int bytesLoaded = await downloading;
        Console.WriteLine($"{nameof(Main)}: Downloaded {bytesLoaded} bytes.");
    }

    private static async Task<int> DownloadDocsMainPageAsync()
    {
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: About to start downloading.");
        
        var client = new HttpClient();
        byte[] content = await client.GetByteArrayAsync("https://docs.microsoft.com/en-us/");
        
        Console.WriteLine($"{nameof(DownloadDocsMainPageAsync)}: Finished downloading.");
        return content.Length;
    }
}
// Output similar to:
// DownloadDocsMainPageAsync: About to start downloading.
// Main: Launched downloading.
// DownloadDocsMainPageAsync: Finished downloading.
// Main: Downloaded 27700 bytes.

L’exemple précédent utilise la méthode async Main, ce qui est possible depuis C# 7.1.The preceding example uses the async Main method, which is possible starting with C# 7.1. Pour plus d’informations, consultez la section Opérateur await dans la méthode Main.For more information, see the await operator in the Main method section.

Notes

Pour obtenir une introduction à la programmation asynchrone, consultez Programmation asynchrone avec async et await.For an introduction to asynchronous programming, see Asynchronous programming with async and await. La programmation asynchrone avec async et await suit le modèle asynchrone basé sur les tâches.Asynchronous programming with async and await follows the task-based asynchronous pattern.

Vous pouvez utiliser l’opérateur await uniquement dans une méthode, une expression lambda ou une méthode anonyme modifiée par le mot clé async.You can use the await operator only in a method, lambda expression, or anonymous method that is modified by the async keyword. Dans une méthode async, vous ne pouvez pas utiliser l’opérateur await dans le corps d’une fonction synchrone, à l’intérieur du bloc d’une instruction lock et dans un contexte unsafe.Within an async method, you cannot use the await operator in the body of a synchronous function, inside the block of a lock statement, and in an unsafe context.

L’opérande de l’opérateur await est généralement un des types .NET suivants : Task, Task<TResult>, ValueTask ou ValueTask<TResult>.The operand of the await operator is usually of one of the following .NET types: Task, Task<TResult>, ValueTask, or ValueTask<TResult>. Cependant, n’importe quelle expression awaitable peut être l’opérande de l’opérateur await.However, any awaitable expression can be the operand of the await operator. Pour plus d’informations, consultez la section Expressions awaitable de la spécification du langage C#.For more information, see the Awaitable expressions section of the C# language specification.

Le type d’expression await t est TResult si le type d’expression t est Task<TResult> ou ValueTask<TResult>.The type of expression await t is TResult if the type of expression t is Task<TResult> or ValueTask<TResult>. Si le type de t est Task ou ValueTask, le type de await t est void.If the type of t is Task or ValueTask, the type of await t is void. Dans les deux cas, si t lève une exception, await t lève à nouveau l’exception.In both cases, if t throws an exception, await t rethrows the exception. Pour plus d’informations sur le gestion des exceptions, consultez la section Exceptions dans les méthodes async de l’article Instruction try-catch.For more information about exception handling, see the Exceptions in async methods section of the try-catch statement article.

Les mots clés async et await sont disponibles depuis C# 5.The async and await keywords are available starting with C# 5.

Opérateur await dans la méthode Mainawait operator in the Main method

Depuis C# 7.1, la méthode Main, qui est le point d’entrée de l’application, peut retourner Task ou Task<int>, ce qui lui permet d’être asynchrone. Vous pouvez ainsi utiliser l’opérateur await dans son corps.Starting with C# 7.1, the Main method, which is the application entry point, can return Task or Task<int>, enabling it to be async so you can use the await operator in its body. Dans les versions antérieures de C#, pour être certain que la méthode Main attend la fin d’une opération asynchrone, vous pouvez récupérer la valeur de la propriété Task<TResult>.Result de l’instance Task<TResult> retournée par la méthode asyn correspondante.In earlier C# versions, to ensure that the Main method waits for the completion of an asynchronous operation, you can retrieve the value of the Task<TResult>.Result property of the Task<TResult> instance that is returned by the corresponding async method. Pour les opérations asynchrones qui ne produisent pas de valeur, vous pouvez appeler la méthode Task.Wait.For asynchronous operations that don't produce a value, you can call the Task.Wait method. Pour savoir comment sélectionner la version du langage, voir Sélectionner la version du langage C#.For information about how to select the language version, see Select the C# language version.

spécification du langage C#C# language specification

Pour plus d’informations, consultez la section Expressions await de la spécification du langage C#.For more information, see the Await expressions section of the C# language specification.

Voir aussiSee also