C# Reference ยท Operators and Expressions
The await operator
Reference for the C# await operator: what it does to a Task, how exceptions and results flow, the awaitable pattern, ConfigureAwait and await foreach.
await pauses an async method until an asynchronous operation finishes, without blocking the thread. When the operation is not complete yet, the method returns to its caller; when it completes, the rest of the method continues where it left off, and the await expression produces the result.
You can only use await inside a method, lambda or anonymous method marked async, or in top-level statements. Its operand is usually a Task or Task<T>, but any type with the right members (the awaitable pattern) works, such as ValueTask.
string text = await File.ReadAllTextAsync(path);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
var result = await expression; await expression; await foreach (var item in asyncSequence) { ... } await using var resource = ...;
| Name | Description |
|---|---|
expression |
A Task, Task<T>, ValueTask, ValueTask<T> or any type with a GetAwaiter() method that follows the awaitable pattern. |
Returns: the T of a Task<T>, or nothing (void) for a Task.
Errors: if the awaited operation faulted, the original exception is rethrown at the await (only the first exception of an aggregate). If it was canceled, OperationCanceledException is thrown. Using await outside an async context in an ordinary method is error CS4032.
Usage notes
awaitdoes not start work. The task is already running (or finished) when you get it. Await only waits for it.- Awaiting one after another runs operations in sequence. To overlap them, start the tasks first and await later, or use
Task.WhenAll. - Never block on a task with
.Resultor.Wait()in code that may run under a synchronization context (UI, old ASP.NET). It can deadlock. Useawait. - By default, the continuation resumes on the captured context. In library code add
.ConfigureAwait(false)when you do not need it. ASP.NET Core has no such context, so it matters little there. async voidmethods cannot be awaited and swallow errors into the context. Use them only for event handlers.awaitcannot appear inside alockblock, an unsafe context or aref struct-basedcatchfilter. UseSemaphoreSlim.WaitAsyncinstead oflock.- Within
catchandfinallyblocksawaitis allowed (since C# 6). ValueTaskavoids an allocation when the result is often available synchronously. Await it only once.- The compiler turns an
asyncmethod into a state machine. Many sequentialawaitcalls do not make a deep stack. - Top-level statements are an
asynccontext, soawaitworks directly inMain-less programs.