Skip to content
Tutorials Center
My learning

Topics

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.

C#
string text = await File.ReadAllTextAsync(path);

Try it

C# Awaiting results and exceptions

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.

C# Sequential and concurrent awaits

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

C#
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

  • await does 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 .Result or .Wait() in code that may run under a synchronization context (UI, old ASP.NET). It can deadlock. Use await.
  • 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 void methods cannot be awaited and swallow errors into the context. Use them only for event handlers.
  • await cannot appear inside a lock block, an unsafe context or a ref struct-based catch filter. Use SemaphoreSlim.WaitAsync instead of lock.
  • Within catch and finally blocks await is allowed (since C# 6).
  • ValueTask avoids an allocation when the result is often available synchronously. Await it only once.
  • The compiler turns an async method into a state machine. Many sequential await calls do not make a deep stack.
  • Top-level statements are an async context, so await works directly in Main-less programs.