The await keyword simplifies the attaching of continuations. Starting with a basic scenario, the compiler expands:

var result = await expression;
statement(s);

into something functionally similar to:

var awaiter = expression.GetAwaiter();
awaiter.OnCompleted (() =>
{
  var result = awaiter.GetResult();
  statement(s);
);

Hence, we can call the ComplexCalculationAsync method we defined previously, like this:

int result = await ComplexCalculationAsync();
Console.WriteLine (result);

In order to compile, we need to add the async modifier to the containing method:

async void Test()
{
  int result = await ComplexCalculationAsync();
  Console.WriteLine (result);
}

The async modifier tells the compiler to treat await as a keyword rather than an identifier should an ambiguity arise within that method (this ensures that code written prior to C# 5.0 that might use await as an identifier will still compile without error). The async modifier can be applied only to methods (and lambda expressions) that return void or (as we’ll see later) a Task or Task<TResult>.

Methods with the async modifier are called asynchronous functions, because they themselves are typically asynchronous. To see why, let’s look at how execution proceeds through an asynchronous function.

Upon encountering an await expression, execution (normally) returns to the caller—rather like with yield return in an iterator. But before returning, the runtime attaches a continuation to the awaited task, ensuring that when the task completes, execution jumps back into the method and continues where it left off. If the task faults, its exception is rethrown (by virtue of calling GetResult); otherwise, its return value is assigned to the await expression.

The expression upon which you await is typically a task; however, any object with a GetAwaiter method that returns an awaitable object—implementing INotifyCompletion.OnCompleted and with an appropriately typed GetResult method (and a bool IsCompleted property which tests for synchronous completion)—will satisfy the compiler.

Notice that our await expression evaluates to an int type; this is because the expression that we awaited was a Task<int> (whose GetAwaiter().GetResult() method returns an int).

Awaiting a nongeneric task is legal and generates a void expression:

await Task.Delay (5000);
Console.WriteLine ("Five seconds passed!");

Task.Delay is a static method that returns a Task that completes in the specified number of milliseconds. The synchronous equivalent of Task.Delay is Thread.Sleep.

Task is the nongeneric base class of Task<TResult> and is functionally equivalent to Task<TResult> except that it has no result.

The real power of await expressions is that they can appear almost anywhere in code. Specifically, an await expression can appear in place of any expression (within an asynchronous function) except for inside a catch or finally block, a lock expression, an unsafe context, or an executable’s entry point (main method).

In the following example, we await inside a loop:

async void Test()
{
  for (int i = 0; i < 10; i++)
  {
    int result = await ComplexCalculationAsync();
    Console.WriteLine (result);
  }
}

Upon first executing ComplexCalculationAsync, execution returns to the caller by virtue of the await expression. When the method completes (or faults), execution resumes where it left off, with the values of local variables and loop counters preserved. The compiler achieves this by translating such code into a state machine, like it does with iterators.

Without the await keyword, the manual use of continuations means that you must write something equivalent to a state machine. This is traditionally what makes asynchronous programming difficult.

With any asynchronous function, you can replace the void return type with a Task to make the method itself usefully asynchronous (and awaitable). No further changes are required:

async Task PrintAnswerToLife()
{
  await Task.Delay (5000);
  int answer = 21 * 2;
  Console.WriteLine (answer);
}

Notice that we don’t explicitly return a task in the method body. The compiler manufactures the task, which it signals upon completion of the method (or upon an unhandled exception). This makes it easy to create asynchronous call chains:

async Task Go()
{
  await PrintAnswerToLife();
  Console.WriteLine ("Done");
}

(And because Go returns a Task, Go itself is awaitable.) The compiler expands asynchronous functions that return tasks into code that (indirectly) leverages TaskCompletionSource to create a task that it then signals or faults.

The aim is to ensure that when a task-returning asynchronous method finishes, execution can jump back to whoever awaited it, via a continuation.

async Task<int> GetAnswerToLife()
{
  await Task.Delay (5000);
  int answer = 21 * 2;
  // answer is int so our method returns Task<int>
  return answer;
}

async Task Go()
{
  await PrintAnswerToLife();
  Console.WriteLine ("Done");
}
async Task PrintAnswerToLife()
{
  int answer = await GetAnswerToLife();
  Console.WriteLine (answer);
}
async Task<int> GetAnswerToLife()
{
  await Task.Delay (5000);
  int answer = 21 * 2;
  return answer;
}

void Go()
{
  PrintAnswerToLife();
  Console.WriteLine ("Done");
}
void PrintAnswerToLife()
{
  int answer = GetAnswerToLife();
  Console.WriteLine (answer);
}
int GetAnswerToLife()
{
  Thread.Sleep (5000);
  int answer = 21 * 2;
  return answer;
}

We’ve just demonstrated the most common pattern, which is to await task-returning functions right after calling them. This results in sequential program flow that’s logically similar to the synchronous equivalent.

Calling an asynchronous method without awaiting it allows the code that follows to execute in parallel. For example, the following executes PrintAnswerToLife twice, concurrently:

var task1 = PrintAnswerToLife();
var task2 = PrintAnswerToLife();
await task1; await task2;

By awaiting both operations afterward, we “end” the parallelism at that point (and rethrow any exceptions from those tasks). The Task class provides a static method called WhenAll to achieve the same result slightly more efficiently. WhenAll returns a task that completes when all of the tasks that you pass to it complete:

await Task.WhenAll (PrintAnswerToLife(),
                    PrintAnswerToLife());

WhenAll is a called task combinator. (The Task class also provides a task combinator called WhenAny, which completes when any of the tasks provided to it complete.) We cover the task combinators in detail in C# 5.0 in a Nutshell.

Just as ordinary named methods can be asynchronous:

async Task NamedMethod()
{
  await Task.Delay (1000);
  Console.WriteLine ("Foo");
}

so can unnamed methods (lambda expressions and anonymous methods), if preceded by the async keyword:

Func<Task> unnamed = async () =>
{
  await Task.Delay (1000);
  Console.WriteLine ("Foo");
};

We can call and await these in the same way:

await NamedMethod();
await unnamed();

Asynchronous lambda expressions can be used when attaching event handlers:

myButton.Click += async (sender, args) =>
{
  await Task.Delay (1000);
  myButton.Content = "Done";
};

This is more succinct than the following, which has the same effect:

myButton.Click += ButtonHandler;
...
async void ButtonHander (object sender, EventArgs args)
{
  await Task.Delay (1000);
  myButton.Content = "Done";
};

Asynchronous lambda expressions can also return Task<TResult>:

Func<Task<int>> unnamed = async () =>
{
  await Task.Delay (1000);
  return 123;
};
int answer = await unnamed();