Introduction

WARNING

Due to the breaking changes introduced by the production version of the Service Bus Messaging API with respect to the CTP version, this version of the Service Bus Explorer tool doesn’t compile against the API contained in the Windows Azure AppFabric SDK V1.5 and cannot be used to managed entities in a Service Bus namespace in production. I published a new version of the Service Bus Explorer tool on MSDN and the related code on MSDN Code Gallery.

The Community Technology Preview (CTP) of Windows Azure AppFabric that was released in May 2011 introduced Queues and Topics that constitute the foundation of a new cloud-based messaging and integration infrastructure that provides reliable message queuing and durable publish/subscribe messaging capabilities to both cloud and on-premises applications based on Microsoft and non-Microsoft technologies. The new messaging functionality can be seamlessly accessed by .NET applications via a brand-new managed API (Microsoft.ServiceBus.Messaging) or WCF thanks to a new binding (ServiceBusMessagingBinding) as well as by any Microsoft or non-Microsoft applications that support HTTP requests via a REST API over HTTPS. In order to exploit the messaging capabilities introduced by Queues and Topics, it’s necessary to create a namespace on the Windows Azure Management Portal. However, the latter does not provide any user interface to administer, create and delete Topic and Queue entities. To accomplish this task, you can use both the .NET API or the REST-style interface exposed by the new messaging platform. For this reason, I decided to build a Windows Forms application that allows to connect to a given Service Bus namespace to create, delete and test messaging entities. This post is the first of a multi-part article where I will explain the functioning and implementation details of my tool whose source code is available on MSDN Archive for use or modification by any developer. In particular, in the first part I will explain how to use my tool to manage and test  Queues and Topics whereas in the second post I will go through the code and explain the approach I followed to realize the application.

The following section provides basic information on the Queue and Topic entities in Windows Azure AppFabric Service Bus. For more information, see the following articles:

• “Introducing the Windows Azure AppFabric Service Bus May 2011 CTP” article on the AppFabric Team Blog.
• “Understanding Windows Azure AppFabric Queues (and Topics)” video on the AppFabric Team Blog.
• “Announcing the Windows Azure AppFabric June CTP!” article on the AppFabric Team Blog.
• “An Introduction to Service Bus Queues” article on the AppFabric Team Blog.
• “An Introduction to Service Bus Topics” article on the AppFabric Team Blog.
• “Windows Azure AppFabric Service Bus Queues and Topics” on Neil Mackenzie's Blog.
• “Windows Azure AppFabric Learning Series” available on CodePlex.

Queues

Queues provide messaging capabilities that enable a large and heterogeneous class of applications running on premises or in the cloud to exchange messages in a flexible, secure and reliable fashion across network and trust boundaries.

Queues are hosted in Windows Azure by a replicated, durable store infrastructure. The maximum size of a queue during the CTP is 100MB, which is expected to rise to 1GB (or more) for production. The maximum message size is 256KB, but the use of sessions allows creating unlimited-size sequences of related messages. Queues functionality are accessible through the following APIs:

• The new messaging API available via the new  Microsoft.ServiceBus.Messaging assembly
• WCF via the new ServiceBusMessagingBinding
• An extension of the Service Bus REST API.

Queue entities provide the following capabilities:

• Session-based correlation, meaning that you can build multiplexed request/reply paths in a easy way.
• Reliable delivery patterns such as Peek/Lock.
• Transactions support to ensure batches of messaging operations (both send and receive) are committed atomically.
• Detection of inbound message duplicates, allowing clients to send the same message multiple times without adverse consequences.
• Dead-letter facility for messages that cannot be processed or expire before being received.
• Deferring messages for later processing. This functionality is particularly handy when messages are received out of the expected sequence and need to be safely put on the side while the process waits for a particular message to permit further progress or when messages need to be processed based on a set of properties that define their priority during a  traffic peak.

In the .NET API the message entity is modeled by the BrokeredMessage class that exposes various properties such as MessageId, SessionID and CorrelationId  that can be used to exploit capabilities such as automatic duplicate detection or session-enabled communications.  A QueueDescription object can be used to specify the metadata that models the behavior of the queue being created:

• The DefaultMessageTimeToLive property specifies the default message time to live value.
• The DuplicateDetectionHistoryTimeWindow property defines the duration of the duplicate detection history.
• The EnableDeadLetteringOnMessageExpiration property allows to enable\disable the dead-lettering on message expiration.
• The LockDuration property defines the duration of the lock used by a consumer when using the PeekLock receive mode. In the ReceiveAndDelete receive mode, a message is deleted from the queue as soon as it is read by a consumer. Conversely, in the PeekLock receive mode, a message is hidden from other receivers until the timeout defined by the LockDuration property expires. By that time the receiver should have deleted the message invoking the Complete method  on the BrokeredMessage object.
• The MaxQueueSizeInBytes property defines the maximum queue size in bytes.
• The RequiresDuplicateDetection property enables\disables duplicate message detection. Since metadata cannot be changed once a messaging entity is created, modifying the duplicate detection behavior requires deleting and recreating the queue. The same principle applies to any other metadata.
• The RequiresSession property enables\disables sessions.

The use of Queues permits to flatten a highly-variable traffic into a predictable stream of work and distribute the load across a set of worker processes which size can vary dynamically to accommodate the incoming message volume. In a Competing Consumers scenario, when a publisher writes a message to a queue, multiple consumers compete with each other to receive the message, but only one of them will receive and process the message in question.

In a service-oriented or a service bus architecture composed of multiple, heterogeneous systems, interactions between autonomous systems are asynchronous and loosely-coupled. In this context, the use of messaging entities like Queues and Topics (see the next section) allows to increase the agility, scalability and flexibility of the overall architecture and helps decreasing the loose coupling of individual systems.

For more information on Queues, see the following articles:

• “Introducing the Windows Azure AppFabric Service Bus May 2011 CTP” article on the AppFabric Team Blog.
• “Understanding Windows Azure AppFabric Queues (and Topics)” video on the AppFabric Team Blog.
• “An Introduction to Service Bus Queues” article on the AppFabric Team Blog.
• “Windows Azure AppFabric Service Bus Queues and Topics” on Neil Mackenzie's Blog.
• “Windows Azure AppFabric Learning Series” available on CodePlex.

Topics

Topics extends the messaging features provided by Queues with the addition of Publish-Subscribe capabilities.

A Topic entity consists of a sequential message store like a Queue, but it supports up to 2000 (this number is subject to vary in the future) concurrent and durable subscriptions which relay message copies to a poll of worker processes. Each Subscription can define one or multiple Rule entities. Each Rule specifies a filter expression that is used to filter messages that pass through the subscription and a filter action that can modify message properties. In particular, the SqlFilterExpression class allows to define a SQL92-like condition on message properties:

• OrderTotal > 5000 OR ClientPriority > 2
• ShipDestinationCountry = ‘USA’ AND ShipDestinationState = ‘WA’

Conversely, the SqlFilterAction class can be used to modify, add or remove properties, as the filter expression is true and the message selected, using a syntax similar to that used by the SET clause of an UPDATE SQL-command.

• SET AuditRequired = 1
• SET Priority = 'High', Severity = 1

Each matching rule generates a separate copy of the published message, so any subscription can potentially generate more copies of the same message, one for each matching rule. As Queues, Topics support a Competing Consumers scenario: in this context, a subscritpion can have a single consumer that receives all messages or a set of competing consumers that fetch messages on a first-come-first-served basis. Topics are the excellent messaging solution to broadcast messages to many consumer applications or distribute the work load across multiple sets of competing worker processes.

The following section provides basic information on the Queue and Topic entities in Windows Azure AppFabric Service Bus. For more information, see the following articles:

• “Introducing the Windows Azure AppFabric Service Bus May 2011 CTP” article on the AppFabric Team Blog.
• “Understanding Windows Azure AppFabric Queues (and Topics)” video on the AppFabric Team Blog.
• “An Introduction to Service Bus Topics” article on the AppFabric Team Blog.
• “Windows Azure AppFabric Service Bus Queues and Topics” on Neil Mackenzie's Blog.
• “Windows Azure AppFabric Learning Series” available on CodePlex.

Solution

As I mentioned in the introduction, today the Windows Azure Platform Management Portal provides the ability to create, modify and delete a Service Bus namespace but it doesn’t offer any GUI to manage Queues and Topics entities. 

A few months ago I created a Storage Services Explorer tool to handle Windows Azure Storage Services: Blobs, Queues and Tables, therefore I decided to undertake a similar project and develop a Service Bus Explorer to manage Topics and Queues. The following picture illustrates the architecture of the application:

In the remainder of the article I'll explain how to configure and use the Service Bus Explorer, whereas in the second part of this series I'll dive into the code and I'll provide technical details on the actual implementation.

Connecting to an existing Service Bus Namespace

When you launch the application, you can connect to an existing Service Bus namespace to manage its entities by choosing the Connect command under the File menu. This operation opens up a modal dialog shown in the picture below that allows you to enter the name of the Service Bus namespace that you want to connect to and the corresponding authentication credentials.

The Service Bus supports three different types of credential schemes: SAML, Shared Secret, and Simple Web Token, but this version of the Service Bus Explorer supports only Shared Secret credentials. However, you can easily extend my code to support other credential schemes. You can retrieve the issuer-secret key from the Windows Azure Platform Management Portal by clicking the View button highlighted in red in the picture below after selecting a certain namespace in the Service Bus section.

This opens up the modal dialog shown in the picture below where you can retrieve the key by clicking the Copy to Clipboard highlighted in red.

Note: by convention, the name of the Default Issuer is always owner.

For your convenience, the tool gives the possibility to define, in the configuration file, a connection string for the most frequently accessed namespaces. As you can see in the xml snippet below, each connection string is composed of 4 elements:

• namespace: this property defines the Service Bus namespace.
• servicePath: this property is optional and specifies the service path within the namespace.
• issuerName: this field contains the Issuer Name. As mentioned above, by convention, the default value for this field is owner.
• issuerSecret: this element contains the Issuer Secret that you can copy from the Windows Azure Platform Management Portal.

<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="serviceBusNamespaces" 
             type="System.Configuration.DictionarySectionHandler, 
                   System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
  </configSections>
  <system.diagnostics>
    <trace autoflush="true" indentsize="4">
      <listeners>
        <clear/>
        <add name="LogTraceListener"
             type="Microsoft.AppFabric.CAT.WindowsAzure.Samples.ServiceBusExplorer.LogTraceListener, 
                   ServiceBusExplorer"
             initializeData="" />
      </listeners>
    </trace>
  </system.diagnostics>
  <serviceBusNamespaces>
    <add key="Northwind" 
         value="namespace=northwind;servicePath=;issuerName=owner;issuerSecret=..."/>
    <add key="AdventureWorks" 
         value="namespace=adventureworks;servicePath=;issuerName=owner;issuerSecret=..."/>
  </serviceBusNamespaces>
  <appSettings>
    <add key="debug" value="true"/>
    <add key="scheme" value="sb"/>
  </appSettings>
  <system.net>
    <connectionManagement>
      <add address="*" maxconnection="50"/>
    </connectionManagement>
  </system.net>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0"/>
  </startup>
</configuration>

If you define one or more namespaces in the configuration file, this give you the possibility to select one of them from the corresponding drop-down list and the fields within the modal dialog will be automatically populated with the corresponding connection string data.

Graphical User Interface

The GUI of the Service Bus Explorer is composed of following parts:

1. The Service Bus Namespace Panel contains a TreeView control that allows to navigate, browse and select entity nodes. Each node is right-click enabled and offers the possibility to access a context-menu which commands depend on the selected entity.
2. The Main Panel displays the information for the selected entity. Based on the command selected by the user, it provides the ability to create, delete or test the current entity.
3. The Log Panel displays information and error messages. The log functionality comes in handy especially when you use the Service Bus Explorer to test existing Queue and Topic entities to trace down send and receive operations performed by publisher and consumer tasks. The Log Panel can be hidden by deselecting the Log Window option under the View menu. You can clear the log by selecting the Clear Log command under the Edit menu. Finally, you can save the log by selecting the Save Log As command under the Edit menu.
4. The Menu bar contains the main menu that allows you to select commands and options. In particular, the commands displayed by the Edit menu varies based on the selected entity.
5. The Status Bar shows the last message.

View a Queue

To view the properties of an existing queue in the Main Panel, you can just select the corresponding node in the TreeView.

As already mentioned above, the current version of the Service Bus (June 2011 CTP Refresh) does not allow to change the properties of an existing queue once created. The same principle applies to the other entities.

Create a Queue

To create a new queue in the current namespace, you can select the Queues node in the TreeView and then perform one of the following actions:

• Right-click the node and choose Create Queue from the context menu.
• Choose Create Queue command under the Edit menu.

This operation displays a custom control (see the picture below) in the Main Panel that allows you to specify the following properties for the new queue:

• Path: this field defines the path for the queue within the namespace.
• Max Queue Size In Bytes: this integer field provides the possibility to specify a value for the MaxQueueSizeInBytes property that defines the maximum queue size in bytes.
• Default Message Time To Live: this section gives the possibility to enter a TimeSpan value for the DefaultMessageTimeToLive property that specifies the default message time to live.
• Duplicate Detection History Time Window: this section gives the possibility to enter a TimeSpan value for the DuplicateDetectionHistoryTimeWindow property that defines the duration of the duplicate detection history.
• Lock Duration: this section gives the possibility to enter a TimeSpan value the LockDuration property that defines the duration of the lock used by a consumer when using the PeekLock receive mode. In the ReceiveAndDelete receive mode, a message is deleted from the queue as soon as it is read by a consumer. Conversely, in the PeekLock receive mode, a message is hidden from other receivers until the timeout defined by the LockDuration property expires. By that time the receiver should have deleted the message invoking the Complete method on the BrokeredMessage object.
• Enable Dead Lettering on Message Expiration: this checkbox specifies a Boolean value for the EnableDeadLetteringOnMessageExpiration property that provides the possibility to enable or disable the dead-lettering functionality on message expiration.
• Requires Duplicate Detection: this checkbox specifies a Boolean value for the RequiresDuplicateDetection property that gives the ability to enable or disable the duplicate message detection feature. Since metadata cannot be changed once a messaging entity is created, modifying the duplicate detection behavior requires deleting and recreating a queue. The same principle applies to the other entities.
• Requires Session: this this checkbox specifies a Boolean value for the RequiresSession property that allows to enable or disable sessions support on the queue being created.

If you don’t explicitly specify any value for one or more fields, when you click the Create button, the default value will be used for the corresponding properties.

Delete a Queue

To delete an existing queue, you can select the corresponding node in the TreeView and then perform one of the following actions:

• Right-click the node and choose Delete Queue from the context menu.
• Choose Delete Queue command under the Edit menu.
• Click the Delete button in the Main Panel.

Test a Queue

To test a queue in the current namespace, you can select the corresponding node in the TreeView and then perform one of the following actions:

• Right-click the node and choose Test Queue from the context menu.
• Choose Test Queue command under the Edit menu.

This operation shows a custom control (see the picture below) in the Main Panel that allows the user to specify the following options:

Message Text and Properties Section

• Message Text: you can use this field to enter a fixed TEXT or XML message.
• Message Properties: you can use the DataGridView control to define the key\value pairs that will be added to the Properties dictionary of a BrokeredMessage object.

Sender Section

• MessageId: you can use this field to specify the MessageId property of a BrokeredMessage object.
• SessionId: you can use this field to define the SessionId property of a BrokeredMessage object.
• Label: you can use this field to specify the Label property of a BrokeredMessage object.
• Task Count: this integer field can be used to define the number of publisher tasks that will be used to send messages.
• Msg Count: this integer field can be used to specify the number of messages that to write to the queue.
• Use Transaction: when this option is checked, each sender task will write messages to the queue within the context of a TransactionScope object. This allows sending a batch of messages within as a unit of work.
• Commit Transaction: when this and Use Transaction options are checked, sender tasks will commit the TransactionScope object. You can check the Use Transaction option and uncheck Commit Transaction option to simulate an unsuccessful transaction.
• Update MessageId: when this option is checked, the tool will generate a different MessageId for each outbound message. You can disable this option when testing the duplicate message detection feature of a queue.
• Enable Logging: when this option is checked, sender tasks will log the text and properties of transmitted messages.
• One Session/Task: when this option is checked, each sender task will use a different value for the SessionId property. This feature allows to test session-enabled queues with multiple sender and consumer tasks.

Receiver Section

• Use Transaction: when this option is checked, each receiver task will retrieve messages from the queue within the context of a TransactionScope object. This allows receiving a batch of messages within as a unit of work.
• Commit Transaction: when this and Use Transaction options are checked, receiver tasks will commit the TransactionScope object. You can check the Use Transaction option and uncheck Commit Transaction option to simulate an unsuccessful transaction.

• Receive Message: when this option is checked, the tool creates a set of consumer tasks to receive messages from the queue. You can disable this option if you want to use the tool just to write messages to a queue, but not to consume them.
• Enable Logging: when this option is checked, consumer tasks will log the text and properties of received messages.
• Task Count: this integer field can be used to define the number of consumer tasks that will be used to receive messages from the queue.
• Timeout: this integer field specifies the timeout in seconds for receiver tasks.