Getting Started with the Service Bus Samples for Windows 8

As part of the Windows Azure Toolkit for Windows 8, we recently released a sample library for accessing Service Bus from Windows 8 metro style applications and a sample metro app demonstrating how to use some basic Service Bus functionality. In this post, we’ll take a quick tour around the sample app, get an introduction to the sample library and examine in detail how the sample library works.

Service Bus Sample Browser for Windows 8

To help make getting started really easy, we’ve built the Service Bus Sample Browser for Windows 8 – this simple metro style application lets you explore and learn about service bus functionality interactively and always keeps you close to the code.

In every sample, bringing up the AppBar in the sample browser (Right Click with a Mouse, or swipe up from the bottom bezel with touch) will allow you to Copy Source Code from the sample to the clipboard for use in Visual Studio.

When you launch the sample browser, you’ll find 3 simple samples included:

Simple Queues
Service Bus Queues are durable First In, First Out message queues that permit communication between distributed applications or components. You can learn more about Service Bus queues on WindowsAzure.com. The pattern for using queues is straightforward: someone sends a message to the queue, someone else receives the message later.

In the Simple Queues sample, you can follow a simple example of how to use this messaging pattern within a Windows 8 metro style application. 

Simple Topics
Topics and Subscriptions in Service Bus support a publish/subscribe communication model – messages are Sent to a single topic and can then be Received by multiple subscribers. You can learn more about Service Bus Topics on WindowsAzure.com. Using topics is as simple as using queues – someone sends a message to the topic and each subscriber is able to receive a copy of that message later.

In the Simple Topics sample you’ll create a Topic, add one or more subscribers to it then send and receive messages.

Peek Lock, Abandon and Complete
Both Queues and Subscriptions support to different ways to receive messages. The first, Receive and Delete, removes the message from the queue or subscription when it is received – if the receiver fails to process the message, then its content is lost. The second, Peek Lock, makes the Receive and Delete operations two separate operations – first a messages is Peeked from the queue by the receiver, later the receiver can Complete the message (deleting it from the queue or subscription and marking it as processed) or Abandon the message (marking it as not completed or unprocessed). A message is returned to the queue or subscription if it is abandoned of its peek-lock times out (by default, the peek lock timeout is 30 seconds).

In the Peek Lock Sample, you try out peek locking yourself. Click each of the shapes to send it to a queue and then try receiving. When you’ve received a shape, select it to Complete or Abandon the message – Completed messages do not return to the Queue, while abandoned ones do. If you neither complete or abandon a message, you’ll observe that it’s lock expires and it is automatically returned to the queue. 

Sample Service Bus Library for Windows 8 – Microsoft.Samples.ServiceBus

To get started download the Windows Azure Toolkit for Windows 8.

To make it easier to consume the Service Bus REST API, we’ve built a sample library for Windows 8 which wraps common Service Bus primitives like Queue, Topic and Subscription – let’s dive straight into some code to illustrate creating a queue, sending a message, receiving the message and deleting the queue. If you are new to the Service Bus, take a look at these how-to articles on Service Bus Queues and Service Bus Topics.

Since we’ll be calling Service Bus over HTTP, we need to consider a couple of things:

1. Request the Internet (Client) capability in your package manifest: Service Bus is on the internet, so you’ll need to make sure your application has permissions to access the network.
2. Calls to the network should always be asynchronous: since a network call could take a little time to complete, you’ll always want to use asynchronous IO. The Sample Service Bus Library helps out by exposing simple asynchronous methods for every operation. 

First up, we need a Token Provider. Token Providers are used by the library to request an authorization token from the Access Control Service (ACS) and attach that token to requests made to Service Bus. You can think of the Token Provider like a set of credentials – it specifies ‘who’ is trying to perform an action on a service bus resource: 

TokenProvider tokenProvider = TokenProvider.CreateSharedSecretTokenProvider(
            serviceNamespace: “Your Service Bus Namespace Name, e.g. contoso”,
            issuerName: “owner”,
            issuerSecret: “Your Service Bus Issuer Secret, e.g. b66Gxx…”);

Next we’ll create a queue – this super-simple call specifies the path of the queue to create and uses the default queue description. If you want to tweak the settings on the queue you’re creating, you’ll find a helpful overload accepting a Queue Description as a parameter:

Queue myQueue = await Queue.CreateAsync(“MyQueue”, tokenProvider);

With the queue created in Service Bus, we can go ahead and send a message. The samples library makes it simple to send plain text messages or messages whose body is a JSON formatted object. Here, we’re just going to asynchronously send a plain text string as the body of the message:

await myQueue.SendAsync(“Hello World!”);

Receiving a message is just a simple – we’ll attempt to receive from the queue using Receive and Delete semantics. If you want to use Peek Lock semantics, you’ll find the PeekLockAsync method nearby. Having received the message, we’ll extract the plain-text body:

BrokeredMessage message = await myQueue.ReceiveAndDeleteAsync();
string greeting = message.GetBody<string>();

Finally, we’re going to clean up after ourselves and delete the queue:

await Queue.DeleteAsync(“MyQueue”, tokenProvider); 

So, there we go – just a few lines of code to create, send, receive and delete entities in Service Bus. In the Sample Service Bus Library for Windows 8, we’ve tried to ensure you have a simple API surface area to get started with and the full power of our REST API surface available when you want it. We’re shipping this library as an open source licensed sample to give you the freedom and flexibility to dive deep into the code if you want to and tweak to your heart’s content! 

We’re hopeful that the simplified API surface in the Sample Service Bus Library for Windows 8 makes it easy to get started building great Metro Style Apps that are connected with Service Bus – we’ve tried to reduce the total number of concepts you need to become familiar with to achieve typical scenarios and make it easier to learn about our advanced features as you need them – we’re always keen to hear your feedback on how useful this sample library is to you, please let us know you thoughts on the discussion list for Windows Azure Toolkit for Windows 8.

Going Deep: How the Sample Service Bus Library for Windows 8 Works

Service bus operations fall into one of two classes: Management or Runtime. Management operations are used to Create, Enumerate, Get and Delete service bus entities like Queues, Topics and Subscriptions; Runtime operations are used to Send and Receive messages. Firstly we’ll dive deep into how the Sample Service Bus Library for Windows 8 implements Management Operations, and then we’ll take a look at how Runtime Operations are implemented.

Management Operations: Create, Get, Enumerate and Delete
The service bus namespace can be thought of as a set of ATOM Feeds, each describing entities that exist at paths beneath it. For example, if a Queue called ‘Foo’ exists at the Uri: https://contoso.servicebus.windows.net/Foo then we would find an atom entry like this at that address:

Quickly looking over the markup, you’ll notice the address of the queue (line 3), the name of the queue (line 4) and the description of the queue that exists here (line 12-25). This pattern is true throughout the namespace – all entities are represented as an XML Entity Description wrapped in an Atom Entry.

Managing service bus entities is achieved by performing RESTful operations on these feeds within a service bus namespace over HTTPS: To create an entity we issue an HTTP PUT, to get an entity we issue an HTTP GET and to delete an entity we issue an HTTP DELETE. Enumeration is performed by issuing an HTTP GET within the reserved $Resources collection at the root of the namespace (for example, /$Resources/Queues).

Each type of entity and sub entity that you can create is represented in a hierarchy of Resource Descriptions. These include the familiar Queue, Topic and Subscription Descriptions and more advanced entities like Rule Description, Rule Filter and Rule Action:

The Resource Description types encapsulate the Content of an Atom entry that represents a service bus entity – when serialized to XML (using the DataContractSerializer) and wrapped in an Atom entry, these types can be used to create, delete, list and represent entities in service bus.

Within the Sample Service Bus Library for Windows 8, a Resource Description can be expressed as an Atom Entry by calling the AsSyndicationItem() method; the SyndicationItem type is within System.ServiceModel.Syndication namespace which provides classes to work with both RSS and ATOM feeds. Similarly, a Resource Description can be extracted from an Atom Entry by using the static ResourceDescription.Create(SyndicationItem) method and specifying the expected resource type as the type parameter, T (for example, T could be QueueDescription). 

Understanding how we model the descriptions of various service bus entities (as ResourceDescriptions) and how we convert those descriptions to and from Atom (using the ResourceDescription.AsSyndicationItem() and ResourceDescription.Create(SyndicationItem item) methods) we’re well prepared to see how the Create, Get, List and Delete operations are implemented. We’ll use Queues to examine how management operations are implemented, but the logic for Topics, Subscriptions and Rules is extremely similar.

Let’s take a look at creating a Queue: 

Queue myQueue = await Queue.CreateAsync(“Foo”, tokenProvider); 

When we call Queue.CreateAsync, we’re going to perform the following operations:

1. Create an instance of QueueDescription and specify “Foo” as the path;
2. Create a NamespaceManager for the service bus namespace specified in the tokenProvider;
3. Request that the NamespaceManager create a new Queue with the specified QueueDescription;
4. Within the NamespaceManager, wrap the QueueDescription in Atom by calling AsSyndicationItem();
5. Request that a SyndicationClient create a new resource with the specified SyndicationItem;
6. The SyndicationClient requests an Authorization Token with the TokenProvider;
7. The SyndicationClient issues an HTTP PUT with the SyndicationItem as its body and the Authorization Token as a header;
8. The HTTP Response is read and loaded into a SyndicationItem by the SyndicationClient;
9. The SyndicationItem is returned to the NamespaceManager;
10. The NamespaceManager extracts the Content of the SyndicationItem as a QueueDescription;
11. The QueueDescription is returned to the calling Queue.CreateAsync method;
12. An instance of a Queue is created to encapsulate the newly created QueueDescription.

You can visualize the Queue, NamespaceManager and SyndicationClient as each adding a layer of information to the original intent to create a queue called foo before handing the request off to service bus:

The Queue is a convenience class that encapsulates a Queue’s description and also operations like Send/Receive in one place. The Queue type uses a NamespaceManager to Create, List, Get and Delete entities in a Service Bus namespace. The NamespaceManager is responsible for figuring out the full URI that an HTTP Request should be issued against (using the ServiceBusEnvironment) and wrapping Resource Descriptions in Atom (using the AsSyndicationItem method) before using a SyndicationClient to create HTTP Calls. The SyndicationClient is responsible for getting an authorization token (using a TokenProvider) and making HTTP calls (using HTTPClient). 

All management operations happen the same way – they’re first issued against a high-level abstraction like Queue, Topic or Subscription, passed down to a Namespace Manager for addressing and conversion to Atom then handled by a Syndication Client to perform the actual raw HTTP Request against service bus.

Runtime Operations: Send, Receive, Peek Lock, Abandon and Complete
Sending and receiving messages over HTTP is really simple. To send a message you issue an HTTP POST to the ‘messages’ collection of a Queue or Topic and to Receive (in receive and delete mode) you issue an HTTP DELETE to the head of the ‘messages’ collection of a Queue or Subscription. Peek locking is similarly achieved by issuing an HTTP POST to the head of  the messages collection to create the peek lock; issuing an HTTP PUT to the lock location to abandon the message and issuing an HTTP DELETE to the lock location.

Service Bus Messages have Headers (like Sent Time, Message Id and Time-to-Live); user-specified message Properties and a body. Over HTTP, Headers are encapsulated as a JSON formatted structure in a reserved HTTP Header named BrokerProperties; user-specified message properties are encapsulated as plain HTTP Headers and the body of the service bus message is – you guessed it – the body of the HTTP Message.  Sending a message to a queue is as simple as invoking SendAsync on that queue:

await myQueue.SendAsync(“Hello, World!”); 

Let’s take a look at a the HTTP trace for sending this message to get a better idea of what it looks like:

POST https://contoso.servicebus.windows.net/Foo/Messages HTTP/1.1
Host: contoso.servicebus.windows.net
Authorization: WRAP access_token=”…”
Content-Type: text/plain
Content-Length: 13

Hello, World!

Receiving a message is similarly straightforward – this time we’ll Receive and Delete from the head of the Queue:

BrokeredMessage message = await myQueue.ReceiveAndDeleteAsync();

And here’s the corresponsing HTTP request and response traces:

DELETE https://contoso.servicebus.windows.net/Foo/Messages/Head?timeout=30 HTTP/1.1
Host: contoso.servicebus.windows.net
Authorization: WRAP access_token=”…”
Content-Length: 0

–

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/plain
Server: Microsoft-HTTPAPI/2.0
BrokerProperties: {“DeliveryCount”:1,”MessageId”:”62a7eceab7eb4d52ac741af5f44393ce”,”SequenceNumber”:1,”TimeToLive”:922337203685.47754}
Date: Mon, 04 Aug 2015 16:23:42 GMT

Hello, World!

You can see here the simple format of a service bus message over HTTP and start to identify some of the metadata available in the BrokerProperties header. Within the Sample Service Bus Library for Windows 8, the type BrokeredMessage is used as an encapsulation for a service bus message, its headers, properties and body. Let’s walk through how the call to SendAsync actually works:

1. SendAsync(string …) is called indicating that a plain-text service bus message should be sent;
2. A new BrokeredMessage is constructed and writes the body of the message to a Stream;
3. The Queue calls SendAsync(BrokeredMessage) on a MessageSender with the newly constructed message;
4. The MessageSender requests an Authorization Token with the TokenProvider;
5. The MessageSender issues an HTTP POST specifying the BrokeredMessage’s BodyStream as its body;
6. HTTP Headers, including any BrokerProperties, user-specified message properties and the Authorization Header are appended to the request.
7. The HTTP Response is checked for an OK (200) status code.

The message sender also supports sending more complex types as the body of a message by serializing them to JSON. A MessageReceiver is used in a similar fashion to receive messages from a Queue or Subscription.

Hopefully this quick whirlwind-tour of the Sample Service Bus Library for Windows 8 gives you some pointers to get started. We’re really excited to hear your feedback on the library and see the awesome connected apps you build with it – lets us know what you’re up to on the discussion list for Windows Azure Toolkit for Windows 8.