Editor’s Note: This post comes from Scott Seely, Developer on the Windows Azure Service Bus Team.

We recently released a new version of the Windows Azure Service Bus Client SDK via NuGet. Currently marked as v2.0.0-beta, the SDK APIs have improved to offer System.Threading.Tasks.Task based versions of all asynchronous APIs. This means that you can write asynchronous code that mere mortals can read. If you are curious about which classes got the treatment, the answer is simple: we updated everything! Anywhere you saw a Begin/End pair, you now also see an Async version of the method. The updated SDK is compiled against .NET 4.0, so it will work with Visual Studio 2010 as well as Visual Studio 2012.

In this short post, I want to cover a few basic things:

1. How to get the SDK
2. How to use the SDK with async/await
3. Talk a bit about when exceptions occur with Task

For users of the SDK, the big thing to know is that you can now write asynchronous, readable code with the Service Bus SDK.

Getting the Beta SDK

As of today, the 2.0 SDK is not considered a final product. That said, it contains a lot of things that you can use on your projects today as you build things that use the Windows Azure Service Bus. The package is only available via NuGet. To add this package to your project, you can go one of two ways:

1. Install via the NuGet GUI in Visual Studio
2. Install via the Package Manager Console in Visual Studio

These instructions assume you have a project opened in Visual Studio and that you want to add the Service Bus SDK to that project. For those who love the mouse, right-click on the project node or References node and select ‘Manage NuGet Packages…’. Make sure that you have selected Include Prerelease (the default is Stable Only). Then search for servicebus. Select Windows Azure Service Bus and click on Install.

From the Package Manager Console (available from ViewàOther WindowsàPackage Manager Console), you can install the new bits by typing in:

Install-Package -Id WindowsAzure.ServiceBus –IncludePrerelease

Make sure to include the -IncludePrelease flag or you will NOT get the version with the Task based APIs.

How to use the SDK with async/await

Let’s write a simple method that uses the Microsoft.ServiceBus.NamespaceManager and a Microsoft.ServiceBus.Messaging.QueueClient. We’ll check to see if the queue exists and create the queue if it does not exist. Then, we’ll send and receive a message from the queue. That’s right, we’ll write the Service Bus Hello, World. To show some of the benefits of simple async programming, we’ll have the message be delivered about 5 seconds after it is sent. The comments in the code explain what is going on.

What we see here is that while waiting for the send and receive to complete, we waited about 9 seconds. During that time, our client was able to do other things with the CPU instead of busily wait for the message to show up and return. You can also see that async code becomes as easy to read as synchronous code. For example of how hairy the Async Programming Model code can be just to check for an existing queue, look at this:

Exceptions and Explicit Task Usage

If you are an existing user of the Asynchronous Programming Model (all those Begin/End pairs), you may know that the Begin methods perform parameter validation. If your parameters have any issues, an exception may be thrown. After the processing was completed, other errors may have occurred. Because of this situation, you needed to catch exceptions on both the Begin and End methods. To simplify development for you, we chose to make it such that all exceptions only throw when the Task completes. What does this mean for you? It means that you catch exceptions in one place, not two or more. For example, if you have code that looks like this with the Asynchronous Programming Model:

and you choose to use the Task based APIs, your code will change to handle all exceptions in the ContinueWith block:

Alternatively, you may choose to hold on to the task and wait for it to complete, in which case your code becomes:

If you follow the happy path, the equivalent async/await exception handling code is even easier to read (and write!):

Closing Words

This is a feature that we are very excited to provide to our customers. We hope it makes your development much easier and brings a smile to anyone on your team that has to work with the Service Bus.