To compile C# or Visual Basic projects which use the newer language support for asynchronous programming in Visual Studio 2010, the in-process compiler must be disabled. This is performed by manually editing the project file to include the following as the last element of the first <PropertyGroup> section in the project file.

<UseHostCompilerIfAvailable>false</UseHostCompilerIfAvailable>

Important
While the UseHostCompilerIfAvailable setting allows Visual Studio 2010 to compile C# and Visual Basic projects using async/await, the editor itself does not recognize these keywords. As a result, some functionality including but not limited to IntelliSense may not function if this option is used.

Exceptions thrown prior to the creation of the Task object representing the asynchronous operation must be caught directly by the calling code. For example, if the code throws an ArgumentNullException in this manner, the calling code would need to contain an exception handler for ArgumentNullException or ArgumentException to handle the exception.

try
{
    Task myTask = SomeOperationAsync();
}
catch (ArgumentException ex)
{
    // ex was thrown directly by SomeOperationAsync. This cannot occur if SomeOperationAsync is an async
    // function (§10.15 - C# Language Specification Version 5.0).
}

Try
    Dim myTask As Task = SomeOperationAsync()
Catch ex As ArgumentException
    ' ex was thrown directly by SomeOperationAsync. This cannot occur if SomeOperationAsync is an async method
    ' (§10.1.3 - Visual Basic Language Specification Version 11.0).
End Try

Exceptions thrown during the asynchronous execution of the task are wrapped in an AggregateException object and returned by the Exception property. Exceptions thrown in this manner must be handled either by a task continuation that checks the Exception property, or by calling Wait or checking the Result property within an exception handling block that includes a handler for AggregateException.

This library additionally ensures that exceptions thrown by asynchronous operations are not wrapped in multiple layers of AggregateException. In other words, an ArgumentException thrown during the asynchronous execution of a task will result in the Exception property returning an AggregateException, and that exception will not contain an nested instances of AggregateException in the InnerExceptions collection. In most cases, the AggregateException wraps exactly one inner exception, which is the original ArgumentException. This guarantee simplifies the use of the API is languages that support async/await, since those operators automatically unwrap the first layer of AggregateException.

try
{
    Task myTask = SomeOperationAsync();
    myTask.Wait();
}
catch (AggregateException wrapperEx)
{
    ArgumentException ex = wrapperEx.InnerException as ArgumentException;
    if (ex == null)
        throw;

    // ex was thrown during the asynchronous portion of SomeOperationAsync. This is always the case if
    // SomeOperationAsync is an async function (§10.15 - C# Language Specification Version 5.0).
}

Try
    Dim myTask As Task = SomeOperationAsync()
    myTask.Wait()
Catch wrapperEx As AggregateException
    Dim ex = TryCast(wrapperEx.InnerException, ArgumentException)
    If ex Is Nothing Then
        Throw
    End If

    ' ex was thrown during the asynchronous portion of SomeOperationAsync. This is always the case if
    ' SomeOperationAsync is an async method (§10.1.3 - Visual Basic Language Specification Version 11.0).
End Try

Applications implementing specialized handling for exception which occur during asynchronous calls have multiple options available for consistent handling. The simplest solution, when available, involves using async/await. These operators automatically unwrap the first exception instance in the InnerExceptions collection of an AggregateException, resulting in behavior that appears to calling code as though the exception was directly thrown by the invoked method. The second method involves treating the original call as a continuation of another task, ensuring that all exceptions are presented as an AggregateException to the exception handling code. The following code shows the application of this strategy to an existing asynchronous call. Note that the CompletedTask class and Then extension method are part of the Rackspace Threading Library separately from this SDK.

// original asynchronous method invocation
Task task1 = SomeOperationAsync();

// method invocation treated as a continuation
Task task2 = task1.ContinueWith(_ => SomeOperationAsync());

' original asynchronous method invocation
Dim task1 = SomeOperationAsync()

' method invocation treated as a continuation
Dim task2 = task1.ContinueWith(Function(task) SomeOperationAsync())

Code using the continuation strategy for consistent error handling may benefit from the use of the Catch methods, which are also part of the Rackspace Threading Library. This extension method behaves in a manner similar to await, automatically unwrapping the first exception instance in the InnerExceptions collection of an AggregateException before invoking the continuation function which handles the exception.