Last month, in "How to Use Windows Azure AppFabric Service Bus Brokered Messaging," I introduced the key concepts and
features of Windows Azure AppFabric Service Bus Brokered Messaging. Now it's time to get our hands dirty and see how we can program against this
messaging infrastructure. In this article, I will present the basics of using the Service Bus Brokered Messaging APIs to manage messaging entities
(such as queues, topics, and subscriptions) and for communications by sending and receiving messages in Azure-based applications.
A Tale of Two APIs
Service Bus Brokered Messaging offers two flavors of API. One is delivered in managed form as the Microsoft.ServiceBus.dll assembly that is a part of
the AppFabric SDK 1.5, and the other API is simply available for REST-aware clients to use. Managed clients communicate with the Service Bus
infrastructure using TCP and the Service Bus client protocol, and REST clients, naturally, use HTTP. One key item to note in restricted networking
environments is that the Service Bus Client Protocol by default requires firewalls to allow outbound TCP port 9354.
For purposes of basic messaging (e.g., sending and receiving messages), these APIs provide identical functionality. In this article, I'll show usage of
the two APIs in parallel to familiarize you with both so that you are comfortable in using the one that best fits your needs. For brevity, I will refer
to the managed API that uses the Service Bus Client Protocol simply as the SBCP API or managed API and the REST interface as the REST API.
Getting Set Up
To use either API with the Service Bus, you will need to create a namespace within the Azure Management Portal. The procedure for doing this is well
documented on MSDN.
Once you've created the namespace, you will want to capture the issuer name (which is "owner" by default), the issuer key (which is akin to the
password), and of course, the namespace name. All these values are available within the portal, by clicking on your namespace and examining the
Properties pane on the right for Name and Default Key. You will use the issuer name, issuer key, and namespace name values in authenticating with the
Service Bus.
Authenticating
All communication with the Service Bus is authenticated. How you authenticate varies depending on which API you use. If you are using the SBCP API,
then you need to create a TokenProvider from the issuer name and issuer password you acquired from the portal, then pass this TokenProvider instance to
any operations that require it, such as in the creation of a NamespaceManager or MessagingFactory. Figure 1 shows how to create the
SharedSecretTokenProvider that is appropriate for this type of credential.
The TokenProvider effectively abstracts you from what is going on under the hood -- a request against the Access Control Service (ACS) that includes,
among other things, your credentials. ACS replies with a token that needs to be included with any requests against the Service Bus. The SBCP API
handles requesting and including the token, as well as renewing it, for you automatically.
Things are a little bit more manual when using REST, as you have to make a POST request against the ACS, providing the credentials as a name/value
collection in the request body, then parse the token from the response, as Figure 2 shows.
With the TokenProvider instance (SBCP API) or the token string (REST API) in hand, you are now ready to start interacting with the Service Bus.
Creating Messaging Entities
Before you can start sending messages to a queue, you need to have a queue in place. The creation of messaging entities (queues, topics, and
subscriptions) is performed by a NamespaceManager (within the Microsoft.ServiceBus namespace) in the SBCP API, and by constructing the appropriate PUT
requests for the REST API.
Depending on the particular entity you are trying to create, different properties can be specified in the configuration, as Figure 3 shows, and it can
be helpful to keep in mind the differences between the messaging entities:
-
Topics do not support the system-provided dead-letter subqueue. Hence, only queues and topics can be configured to automatically dead-letter a
message whose time-to-live has expired.
-
Similarly, only subscriptions support filters, and so only they provide support for automatic dead-lettering of messages that have an exception
when the filter is evaluated.
-
Topics are not used to receive messages, whereas queues and subscriptions are. Thus topics cannot be configured with a Lock Duration (how long a
peek/lock received message is held invisible), Max Delivery Count (how many times a message is received before being considered poisonous), or a
Requires Session (enabling retrieval of messages grouped by a session).
-
By contrast, only queues and topics can be used to send messages to them. Subscriptions, which cannot be sent messages, naturally do not have
configurations for Requires Duplicate Detection (which detects and ignores duplicate messages sent in) and Duplicate Detection History Time Window
(which controls the window of time for which a duplicate of a message already received is monitored).
-
Queues and topics are identified by a path (which allows for labels with multiple segments, like /subpath1/subpath2/myqueue), whereas
subscriptions cannot use a path and must use a simple single segment name like "mysubscription."
Figure 3: Messaging entity configuration-related properties
With these properties in mind, let us take a look at how to create each type of messaging entity.
Creating a Queue
Creating a queue with the SBCP API is a matter of creating a NamespaceManager instance, then using the CreateQueue method on that instance, passing in
either a queue path (in which case the defaults are taken for all other settings) or a QueueDescription (which enables you to specify values for the
settings in Figure 3). You construct a NamespaceManager instance by building the URI to your Service Bus namespace using the
ServiceBusEnvironment.CreateServiceUri static method, and instantiate your NamespaceManager using its constructor that takes the URI and the previously
acquired TokenProvider. Figure 4 shows how to create a queue with a path of "MyFirstQueue" and the default settings for the QueueDescription.