category: Advanced

The latest version of the C# language – version 5 – introduced two new keywords to express asynchronous operations: async and await. These keywords let you write simple code that doesn't block compute resources when waiting for external resources or long running operations (database access or web service requests for instance). The Stormancer platform is built with non-blocking constructs at its core, and makes heavy use of asynchronous Tasks. This enable Stormancer backends to optimize available resources, and handle much more concurrent requests than synchronous platforms.

Our async support brings the ease of use of C# async to developers that want to easily create and evolve responsive server applications.

Overview

This document introduces the new async and await keywords then walks through some simple examples implementing asynchronous methods in Stormancer.

For a more complete discussion of the new asynchronous features of C# 5 (including lots of samples and different usage scenarios) refer to the MSDN documentation Asynchronous Programming with Async and Await.

The sample Stormancer application uses the bing translator web API to translate chat messages to the language of the user. By calling the translator API asynchronously, the application can process more requests while waiting for the API calls to complete.

Using async & await

async and await are new C# language features that work in conjunction with the Task Parallel Library to make it easy to write threaded code to perform long-running tasks without blocking the main thread of your application.

async

Declaration

The async keyword is placed in a method declaration (or on a lambda or anonymous method) to indicate that it contains code that can run asynchronously, ie. not block the caller’s thread.

A method marked with async should contain at least one await expression or statement. If no awaits are present in the method then it will run synchronously (the same as if there were no async modifier). This will also result in a compiler warning (but not an error).

Return Types

An async method should return a Task, Task or void.

Specify the Task return type if the method does not return any other value.

Specify Task if the method needs to return a value, where TResult is the type being returned (such as an int, for example).

The void return type is used mainly for event handlers which require it. Code that calls void-returning asynchronous methods can’t await on the result.

Parameters

Asynchronous methods cannot declare ref or out parameters.

await

The await operator can be applied to a Task inside a method marked as async. It causes the method to stop execution at that point and wait until the task completes.

Using await does not block the caller’s thread – rather control is returned to the caller. This means that the calling thread is not blocked, so for example the user interface thread would not be blocked when awaiting a task.

When the task completes, the method resumes executing at the same point in the code. This includes returning to the try scope of a try-catch-finally block (if one is present). await cannot be used in a catch or finally block.

Read more about await on MSDN.

Exception Handling

Exceptions that occur inside an async method are stored in the task and thrown when the task is awaited. These exceptions can be caught and handled inside a try-catch block.

An asynchronous task may also be cancelled, in which case an OperationCanceledException will be thrown when the task is awaited. Details on how to cancel an asynchronous task are available on MSDN.

Example