SALES: 1-800-867-1380

Managing and Testing Topics, Queues and Relay Services with the Service Bus Explorer Tool

Updated: March 13, 2014

Authors: Paolo Salvatori

Introduced in the September 2011, queues and topics represent 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. .NET applications can use the new functionality offered by queues and topics by using the new messaging API (Microsoft.ServiceBus.Messaging) released with the Azure AppFabric SDK V1.5 or via WCF by using the new NetMessagingBinding. Likewise, any Microsoft or non-Microsoft applications can use a Service Bus REST API to manage and access messaging entities over HTTPS.

Queues and topics were first introduced by the Community Technology Preview (CTP) of Azure AppFabric that was released in May 2011. At that time, the Azure Management Portal didn’t provide any user interface to administer, create and delete messaging entities and the only way to accomplish this task was using the .NET or REST API. For this reason, I decided to build a tool called Service Bus Explorer that would allow developers and system administrators to connect to a Service Bus namespace and administer its messaging entities. During the last few months I continued to develop this tool and add new features with the intended goal to facilitate the development and administration of new Service Bus-enabled applications. In the meantime, the Azure Management Portal introduced the ability for a user to create queues, topics, and subscriptions and define their properties, but not to define or display rules for an existing subscription. Besides, the Service Bus Explorer enables to accomplish functionalities, such as importing, exporting and testing entities, that are not currently provided by the Azure Management Portal. For this reason, the Service Bus Explorer tool represents the perfect companion for the official Azure portal and it can also be used to explore the features (session-based correlation, configurable detection of duplicate messages, deferring messages, etc.) provided out-of-the-box by the Service Bus brokered messaging.

This post is the first of a two-part article where I will explain the functioning and implementation details of my tool whose source code is available on MSDN Code Gallery 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.

For more information on the AppFabric Service Bus, you can use the following resources:

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.

QueueArch

Queues are hosted in 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:

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.

  • 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:

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

TopicArch

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 you 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 subscription 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 ideal 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 Azure AppFabric Service Bus. For more information, see the following articles:

In order to use the Brokered and Relay messaging functionality provided by the Service Bus, the first operation to perform is to provision a new Service Bus namespace or modify an existing namespace to include the Service Bus. You can accomplish this task from the Azure Management Portal respectively by clicking the New button or the Modify button highlighted in the figure below.

QueuesTopicsSubs

Once completed this step, you can start creating and using queues, topics and subscriptions. You have many options to provision and manage messaging entities:

  • This first option is to exploit the CreateQueue, CreateTopic and CreateSubscription methods exposed by the NamespaceManager class that can be used to manage entities, such as queues, topics, subscriptions, and rules, in your service namespace. This is exactly the approach that I followed to build the provisioning functionality exposed by the Service Bus Explorer tool.

  • The second approach is to rely on the Service Bus REST API to create and delete messaging entities. By using REST, you can write applications in any language that supports HTTP requests, without the need for a client SDK. In particular, this allows applications based on non-Microsoft technologies (e.g. Java, Ruby, etc.) not only to send and receive messages from the Service Bus, but also to create or delete queues, topics and subscription in a given namespace.

Finally, you can administer messaging entities from the user interface supplied by the Azure Management Portal. In particular, the buttons in the Manage Entities command bar highlighted in red at point 1 in the figure below allow creating a new queue, topic and subscription entity. Then you can use the navigation tree-view shown at point 2 to select an existing entity and display its properties in the vertical bar highlighted at point 3. To remove the selected entity, you press the Delete button in the Manage Entities command bar.

QueuestopicsSubs2

Using Azure Management Portal is a handy and convenient manner to handle the messaging entities in a given Service Bus namespace. However, at least at the moment, the set of operations that a developer or a system administrator can perform using its user interface is quite limited. For example, the Azure Management Portalactually allows a user to create queues, topics, and subscriptions and define their properties, but not to create or display rules for an existing subscription. At the moment, you can accomplish this task only by using the .NET Messaging API. In particular, to add a new rule to an existing subscription you can use the AddRule(String, Filter) or the AddRule(RuleDescription) methods exposed by the SubscriptionClient class, while to enumerate the rules of an existing subscription, you can use the GetRules method of the NamespaceManager class. Besides, the Azure Management Portal actually does not provide the ability to perform the following operations:

  • Properly visualize entities in a hierarchical manner. Actually, the Azure Management Portaldisplays queues, topics and subscriptions with a flat treeview. However, you can organize messaging entities in a hierarchical structure simply by specifying their name as an absolute path composed of multiple path segments, for example crm/prod/queues/orderqueue.

  • Export the messaging entities contained in a given Service Bus namespace to an XML binding file (a-la BizTalk Server). Instead, the Service Bus Explorer tool provides the ability to select and export

    • Individual entities.

    • Entities by type (queues or topics).

    • Entities contained in a certain path (e.g. crm/prod/queues).

    • All the entities in a given namespace.

  • Individual entities.

  • Entities by type (queues or topics).

  • Entities contained in a certain path (e.g. crm/prod/queues).

  • All the entities in a given namespace.

  • Import queues, topics and subscriptions from an XML file to an existing namespace. The Service Bus Explorer supports the ability to export entities to an XML file and reimport them on the same or another Service Bus namespace. This feature comes in a handy to perform a backup and restore of a namespace or simply to transfer queues and topics from a testing to a production namespace.

That’s why in June, I created a tool called Service Bus Explorer that allows a user to create, delete and test queues, topics, subscriptions, and rules. My tool was able to manage entities in the AppFabric Labs Beta environment. However, the new version of the Service Bus API introduced some breaking changes, as you can read here, so I built a new version of the Service Bus Explorer tool that introduces a significant amount of new features.

The following picture illustrates the high-level architecture of the Service Bus Explorer tool. The application has been written in C# using Visual Studio and requires the installation of the .NET Framework 4.0 and Azure AppFabric SDK V1.5. The tool can be copied and used on any workstation that satisfies the prerequisites mentioned above to manage and test the Brokered and Relay messaging services defined in a given Service Bus namespace.

ServiceBusExplorer

In the remainder of the article I'll explain how to configure and use the Service Bus Explorer tool.

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 the user to enter the name of the Service Bus namespace that you want to connect to and the corresponding authentication credentials.

connecting2anexistingSBNamespace

The authentication and authorization to use a service exposed by the Service Bus are controlled by the Access Control Service. In particular, the Service Bus currently supports three different types of credential schemes:

  • SharedSecret, a slightly more complex but easy-to-use form of username/password authentication.

  • Saml, which can be used to interact with SAML 2.0 authentication systems.

  • SimpleWebToken, which uses the OAuth Web Resource Authorization Protocol (WRAP) and Simple Web Tokens (SWT).

The Service Bus Explorer tool currently supports only SharedSecret credentials. However, you can easily extend its code to support other credential schemes. You can retrieve the issuer-secret key for a given namespace from the Azure Management Portal by clicking the View button highlighted in red in the picture below.

connecting2anexistingSBNamespace2

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

connecting2anexistingSBNamespace3
noteNote
By convention, the name of the Default Issuer is always the 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 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>
  <serviceBusNamespaces>
    <add key="Namespace1" value="namespace=namespace1;
      servicePath=;issuerName=owner;issuerSecret=..."/>
    <add key="Namespace2" value="namespace=namespace2;servicePath=;
                     issuerName=owner;issuerSecret=..."/>
  </serviceBusNamespaces>
  <appSettings>
    <add key="debug" value="true"/>
    <add key="scheme" value="sb"/>
    <add key="message" value="Hi mate, how are you?" />
    <add key="file" value="C:\Sample.xml" />
    <add key="label" value="Service Bus Explorer" />
    <add key="retryCount" value="10" />
    <add key="retryTimeout" value="100" />
    <add key="messageDeferProvider" value="Microsoft.AppFabric.CAT.WindowsAzure.Samples.ServiceBusExplorer.InMemoryMessageDeferProvider,ServiceBusExplorer"/>
  </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 gives you the ability 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.

connect4

In the appSettings section of the configuration file you can define the following default settings:

  • debug: some components use a custom trace listener to write message in the log view. By setting this parameter to false, you can disable this behavior.

  • scheme: this parameter can be used to define the transport protocol that the tool uses to communicate with the Service Bus. At the moment, the only supported scheme is sb.

  • message: you can use this parameter to specify the default text for the test message.

  • file: this parameter can be used to define the location of the default message when testing queues, topics and relay services.

  • label: this setting defines the default value for the Label property of a brokered message.

  • retryCount: this parameter can be used the default retry count in case of exception.

  • retryTimeout: this parameter allows to control the time in milliseconds between two consecutive attemps.

  • messageDeferProvider: when testing deferred messages, the application uses a default provider to store in-process the sequence number of deferred messages. You can create an alternative provider and replace the default one. In this case, you have to use this parameter to declare its fully-qualified name.

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

  1. The Menu bar contains the main menu that allows the user to select commands and options. In particular, the commands displayed in the Actions menu vary based on the selected entity.

  2. 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.

  3. 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. In case of relay services, the Service Bus Explorer tool only supports the possibility to test the service endpoints defined in the Service Bus registry by a given relay service using the ServiceRegistrySettings endpoint behavior.

  4. 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 queues, topics and relay services to trace send and receive operations performed by individual sender and receiver tasks. The Log Panel can be hidden by deselecting the Log Window option under the View menu.

connecting2anexistingSBNamespace5

Once you connected to an existing Service Bus namespace, you can use the tool to perform the following operations.

The Menu bar contains the following menus:

  • File:

    MenuBar1
    • Connect: opens a modal dialog that allows to connect to a given Service Bus namespace.

    • Exit: closes the application.

  • Edit:

    MenuBar2
    • Clear Log: clears the log view.

    • Save Log As…: saves the content of the log to a text file.

  • Actions: contains the same commands available in the context menu of the currently selected node in the treeview.

  • View:

    MenuBar3
    • Set Default Layout: reset the layout to the default configuration

    • Log Window: enable or disable the display of the log window.

  • Options: shows a modal dialog that allows to define the layout parameters:

    MenuBar4
  • Help: contains the About Service Bus Explorer command.

By right clicking the namespace root node in the Service Bus Namespace panel, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

namespace1

The context menu provides access to the following commands:

  • Delete Entities: as shown in the picture below, prompts the user to confirm whether to delete all the entities in the current Service Bus namespace.

namespace2
  • Refresh Entities: refreshes all the entities (queues, topics, subscriptions, rules, relay services) in the current Service Bus namespace.

  • Export Entities: exports all the entities in the current Service Bus namespace to an XML file.

  • Import Entities: import entities from an XML file. The file in question can contain the definition of one or multiple queues and topics.

  • Expand Subtree: expands the subtree below the namespace root node.

  • Collapse Subtree: collapse the subtree below the namespace root node.

By right clicking the Queues node in the Service Bus Namespace panel, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

Queuescmds1

The context menu provides access to the following commands:

Create Queue: displays a custom control in the Main Panel that allows to specify the properties of a new queue. For more information on how to create a new queue, see later in this article.

Delete Queues: prompts the user to confirm whether to delete all the queues in the current Service Bus namespace.

Queuescmds2
  • Refresh Queues: refreshes all the queues in the current Service Bus namespace.

  • Export Queues: exports all the queues in the current Service Bus namespace to an XML file.

  • Expand Subtree: expands the subtree below the Queues node.

  • Collapse Subtree: collapse the subtree below the Queues node.

By right clicking a Path Segment node in the Queues subtree, as shown in the picture below, you can open a context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

QueuePath1

The context menu provides access to the following commands:

  • Create Queue: displays a custom control in the Main Panel that allows to specify the properties of a new queue. In particular, it initializes the value of the queue Name field with the absolute path of the selected node (e.g. crm/prod in the sample above). For more information on how to create a new queue, see later in this article.

  • Delete Queues: as shown in the picture below, prompts the user to confirm whether to delete all the queues in the current path.

QueuePath2
  • Export Queues: exports all the queues in the current path to an XML file.

  • Expand Subtree: expands the subtree below the selected path segment node.

  • Collapse Subtree: collapse the subtree below the selected path segment node.

If you click an existing Queue node in the Service Bus Namespace panel, its information will be displayed in the Main panel, as shown in the picture below.

queuecmd1

By right clicking a Queue node in the Queues subtree, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

queuecmd2

The context menu provides access to the following commands:

  • Delete Queue: as shown in the picture below , prompts the user to confirm whether to delete the selected queue in the current Service Bus namespace.

queuecmd3
  • Test Queue: displays a custom control in the Main Panel that allows to test the selected queue by sending and receiving messages. The tool allows the user to select a wide range of testing options. In addition, the Service Bus Explorer enables to monitor the progress and performance of an ongoing test run by using the information traced in the log view. Finally, the tool allows to display real-time performance data, such as latency and throughput for sender and receiver tasks, simply by enabling statistics and chart features. For more information on how to test a queue, see later in this article

  • Refresh Queue: refreshes the current information for the selected queue. This feature can be used to refresh the value of the MessageCount and SizeInBytes properties for the current queue.

  • Export Queue: exports the current queue definition to an XML file.

  • Copy Queue Url: as shown in the picture below, this command copies the url of the current queue to the clipboard.

queuecmd4
  • Copy Deadletter Queue Url: as shown in the picture below, this command copies the url of the deadletter queue for the current queue to the clipboard.

queuecmd5
  • Expand Subtree: expands the subtree below the Queues node.

  • Collapse Subtree: collapse the subtree below the Queues node.

By right clicking the Topics node in the Service Bus Namespace panel, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

Topics1

The context menu provides access to the following commands:

  • Create Topic: displays a custom control in the Main Panel that allows to specify the properties of a new topic. For more information on how to create a new topic, see later in this article.

  • Delete Topics: as shown in the picture below, prompts the user to confirm whether to delete all the topics in the current Service Bus namespace.

topics2
  • Refresh Topics: refreshes all the topics in the current Service Bus namespace.

  • Export Topics: exports all the topics in the current Service Bus namespace to an XML file.

  • Expand Subtree: expands the subtree below the Topics node.

  • Collapse Subtree: collapse the subtree below the Topics node.

By right clicking a Path Segment node in the Topics subtree, as shown in the picture below, you can open a context menu. The commands provided by the context menu are also available under the Actions menu in the main Menu bar.

TopicPathSeg1

The context menu provides access to the following commands:

  • Create Topic: displays a custom control in the Main Panel that allows to specify the properties of a new topic. In particular, it initializes the value of the topic Name field with the absolute path of the selected node (e.g. erp/test in the sample above). For more information on how to create a new topic, see later in this article.

  • Delete Topics: as shown in the picture below, prompts the user to confirm whether to delete all the topics in the current path.

TopicPathSeg2

Export Topics: exports all the topics in the current path to an XML file.

Expand Subtree: expands the subtree below the selected path segment node.

Collapse Subtree: collapse the subtree below the selected path segment node.

If you click an existing Topic node in the Service Bus Namespace panel, its information will be displayed in the Main panel, as shown in the picture below.

TopicCmd1

By right clicking a Topic node in the Topics subtree, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

TC2

The context menu provides access to the following commands:

  • Delete Topic: as shown in the picture below, prompts the user to confirm whether to delete the selected topic in the current Service Bus namespace.

TC3
  • Test Topic: displays a custom control in the Main Panel that allows to test the selected topic by sending and receiving messages. The tool allows the user to select a wide range of testing options. In addition, the Service Bus Explorer enables to monitor the progress and performance of an ongoing test run by using the information traced in the log view. Finally, the tool allows to display real-time performance data, such as latency and throughput for sender and receiver tasks, simply by enabling statistics and chart features. For more information on how to test a queue, see later in this article.

  • Refresh Topic: refreshes the current information for the selected topic. This feature can be used to refresh the value of the SizeInBytes property for the current topic.

  • Export Topic: exports the current topic definition to an XML file along with its subscriptions.

  • Create Subscription: displays a custom control in the Main Panel that allows to specify the properties of a new subscription for the selected topic. For more information on how to create a new subscription, see later in this article.

Delete Subscriptions: as shown in the picture below, prompts the user to confirm whether to delete all the subscriptions for the selected topic.

TC4
  • Copy Topic Url: as shown in the picture below, this command copies the url of the current topic to the clipboard.

  • Expand Subtree: expands the subtree below the Topics node.

  • Collapse Subtree: collapse the subtree below the Topics node.

By right clicking a Subscriptions node as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

SubCmds2
  • The context menu provides access to the following commands:

  • Create Subscription: displays a custom control in the Main Panel that allows to specify the properties of a new subscription for the current topic. For more information on how to create a new subscription, see later in this article.

  • Delete Subscriptions: as shown in the picture below, prompts the user to confirm whether to delete all the subscriptions for the current topic.

SC1
  • Refresh Subscriptions: refreshes the current information for the subscriptions of the current topic.

  • Expand Subtree: expands the subtree below the Subscriptions node.

  • Collapse Subtree: collapse the subtree below the Subscriptions node.

By right clicking a Subscription node as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

TC5

The context menu provides access to the following commands:

  • Delete Subscription: as shown in the picture below, prompts the user to confirm whether to delete the selected subscription.

DelSub
  • Test Subscription: displays a custom control in the Main Panel that allows to test the selected subscription by receiving messages from it. The tool allows the user to select a wide range of testing options. In addition, the Service Bus Explorer enables to monitor the progress and performance of an ongoing test run by using the information traced in the log view. Finally, the tool allows to display real-time performance data, such as latency and throughput for receiver tasks, simply by enabling statistics and chart features. For more information on how to test a queue, see later in this article.

  • Refresh Subscription: refreshes the current information for the selected subscription. This feature can be used to refresh the value of the MessageCount property for the current subscription.

  • Add Rule: displays a custom control in the Main Panel that allows to specify the properties of a new rule for the currently selected subscription. For more information on how to create a new topic, see later in this article.

  • Copy Queue Url: as shown in the picture below, this command copies the url of the current queue to the clipboard.

CopyDeadLetterQ

Copy Deadletter Queue Url: as shown in the picture below, this command copies the url of the deadletter queue for the current queue to the clipboard.

copyDeadLetterQURL
  • Expand Subtree: expands the subtree below the Subscription node.

  • Collapse Subtree: collapse the subtree below the Subscription node

By right clicking a Rules node as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

RC0

The context menu provides access to the following commands:

  • Add Rule: displays a custom control in the Main Panel that allows to specify the properties of a new rule for the currently selected subscription. For more information on how to create a new topic, see later in this article.

  • Delete Rules: as shown in the picture below, prompts the user to confirm whether to delete all the rules for the current subscription.

RC1
  • Refresh Rules: refreshes the current information for the rules of the current topic.

By right clicking a Rule node as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

RC11

The context menu provides access to the following commands:

Remove Rule: as shown in the picture below, prompts the user to confirm whether to remove the selected rule.

RC12

By right clicking the Relay Services node in the Service Bus Namespace panel, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

RelayServiceCmds

The context menu provides access to the following commands:

Refresh Relay Services: refreshes all the relay services in the current Service Bus namespace. In order to appear in the treeview, a relay service needs to use the ServiceRegistrySettings endpoint behavior to define its public endpoints in the Service Bus registry.

Expand Subtree: expands the subtree below the Relay Services node.

Collapse Subtree: collapse the subtree below the Relay Services node.

By right clicking a Path Segment node in the Relay Service subtree, as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

Relay Service Path Segment Commands

The context menu provides access to the following commands:

Expand Subtree: expands the subtree below the selected path segment node.

Collapse Subtree: collapse the subtree below the selected path segment node.

By right clicking a Relay Service node as shown in the picture below, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

Relay Service Commands

The context menu provides access to the following commands:

  • Expand Subtree: expands the subtree below the selected path segment node.

  • Collapse Subtree: collapse the subtree below the selected path segment node.

If you click an Endpoint node of a relay service in the Service Bus Namespace panel, the following custom control appears in the Main panel. This control allows to configure a client endpoint and send messages to the selected endpoint. For more information on how to test a relay service, see later in this article

Relay Service Endpoint Commands2

By right clicking an Endpoint node of a relay service, you can open the following context menu. The commands provided by the context menu are also available under the Actions menu in the Menu bar.

Relay Service Endpoint Commands1

The context menu provides access to the following commands:

  • Copy Relay Service Url: as shown in the picture below, this command copies the url of the current service endpoint to the clipboard.

Relay Service Endpoint Commands

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

ViewQ

The current version of the Service Bus does not allow to change the properties of an existing queue once created. The same principle applies to the other entities (topics, subscriptions, rules).

To create a new queue in the current namespace, you can select the Queues node or a path segment node under the Queues subtree and then perform one of the following actions:

  1. Right-click the node and choose Create Queue from the context menu.

  2. Choose Create Queue command under the Actions menu.

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

CreateQ
  • Path: this field defines the path for the queue within the namespace. The value can be an absolute path like erp/prod/queues/orderqueue.

  • 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.

  • 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.

  • 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 or called the Abandon method to release the lock.

  • Max Delivery Count: the MaxDeliveryCount property defines the maximum delivery count. A message is automatically deadlettered after this number of deliveries.

  • Max Size In Megabytes: the MaxSizeInMegabytes property defines the maximum size in megabytes, which is the size of memory allocated for the queue.

  • Enable Batched Operations: the EnableBatchedOperations property accepts a Boolean value that indicates whether server-side batched operations are enabled.

  • Enable Dead Lettering on Message Expiration: this checkbox specifies a Boolean value for the EnableDeadLetteringOnMessageExpiration property that enables or disables the dead-lettering functionality on message expiration.

  • Requires Duplicate Detection: this checkbox specifies a Boolean value for the RequiresDuplicateDetection property that enables or disables the duplicate message detection feature.

  • Requires Session: this checkbox specifies a Boolean value for the RequiresSession property that enables or disables sessions support on the queue being created.

The MessageCount and SizeInBytes are read-only properties and cannot be set when creating a queue. In addition, 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. 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.

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 Actions menu.

  • Click the Delete button in the Main Panel.

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 Actions menu.

This operation shows a custom control in the Main panel that is composed of four tabs:

  • Message Tab

  • Sender Tab

  • Receiver Tab

  • Graph Tab

MessageTab1

The Message tab allows the user to specify the following information:

  • Message Text: specifies the payload of a BrokeredMessage as a TEXT or XML message. The tool provides the ability to read the message from the file system by pressing the Open button and selecting a file.

  • Message Properties: you can use the datagrid to define the key\value pairs that will be added to the Properties dictionary of a BrokeredMessage object. The Properties collection allows to define application specific message properties. This is probably the most important feature of a BrokeredMessage entity as user-defined properties can be used for the following:

  • Carry the payload of a message. In this context, the body of the message could be empty.

  • Define application specific properties that can be used by a worker process to decide how to process the current message.

Specify filter and action expressions that can be used to define routing and data enrichment rules at a subscription level.

noteNote
As indicated in Azure AppFabric Service Bus Quotas, the maximum size for each property is 32K. Cumulative size of all properties cannot exceed 64K. This applies to the entire header of the BrokeredMessage, which has both user properties as well as system properties (such as SequenceNumber,Label, MessageId, and so on). The space occupied by properties counts towards the overall size of the message and its maximum size of 256K. If an application exceeds any of the limits mentioned above, a SerializationException exception is generated, so you should expect to handle this error condition..

SenderTab1

The Sender tab allows the user to specify the following information:

  • Enabled: this checkbox allows enabling or disabling sender tasks when testing a queue.

  • MessageId: this field specifies a value for the MessageId property of a BrokeredMessage object. When a queue is configured to use the duplicate detection mechanism, this property is used to individuate duplicates or already received messages.

  • SessionId: this field specifies a value for the SessionId property of a BrokeredMessage object. A SessionId is a logical and lightweight way to correlate messages to each other. For example, the sender can set SessionId = "SessionId" of several messages as an indicator that these messages are related to each other.

  • CorrelationId: the CorrelationId property can be used to implement a request-reply message exchange pattern where the client application uses the MessageId property of an outgoing request message and the CorrelationId property of an incoming response message to correlate the two messages.

  • Label: specifies a value for the Label property of a BrokeredMessage object.

  • ReplyTo: the ReplyTo property can be used to define the address of the queue to reply to. In an asynchronous request-reply scenario where a client application A sends a request message to a server application B via a Service Bus queue or topic and waits for a response message, by convention the client application A can use the ReplyTo property of the request message to indicate to the server application B the address of the queue or topic where to send the response.

  • ReplyToSessionId: by definition, the ReplyToSessionId property of a BrokeredMessage object can be used by a client application to indicate to a service the session identifier to reply to. When a client application A sends a flow of request messages to a server application B via a session-enabled queue or topic and waits for the correlated response messages on a separate session-enabled queue or a subscription, the client application A can assign the id of the receive session to the ReplyToSessionId property of outgoing messages to indicate to the application B the value to assign to the SessionId property of response messages.

  • Task Count: this field can be used to define the number of publisher tasks that will be used to send messages. Every task runs on a separate .NET thread pool thread.

  • Message Count: this integer field can be used to specify the number of messages to write to the queue.

  • Time to Live: specifies the value in seconds for the TimeToLive property of a BrokeredMessage object. This is the duration after which the message expires, starting from when the message is sent to the Service Bus. Messages older than their TimeToLive value will expire and no longer be retained in the message store. Subscribers will be unable to receive expired messages.

  • Use Transaction: when this option is checked, publisher tasks will use a TransactionScope object to send a batch of messages within a transaction context. For more information, see the code snippet in the table below.

  • Commit Transaction: when this option is checked, publisher tasks will invoke the Complete method to commit the transaction and persist messages to the queue. Please note that when a publisher sends one or multiple messages within a TransactionScope and at the end does not call the Complete method, messages are not written to the queue. The Use Transaction and Commit Transaction options can be used to test the behavior of send-side transactions. For more information, see the code snippet in the table below.

 

using (var scope = new TransactionScope())
{
    serviceBusHelper.SendMessages(...);
    ...
    if (checkBoxSenderCommitTransaction.Checked)
    {
        scope.Complete();
        ...
    }
    ...
}

  • Enable Logging: when this option is checked, sender tasks will track the operations performed in the log view.

  • Enable Verbose: when this option is checked, sender tasks will log the payload and properties of transmitted messages.

  • Enable Statistics: when this option is checked, sender tasks will update statistics in the Graph tab.

  • Enable Graph: when this option is checked, sender tasks will update the latency and throughput charts in the Graph tab.

  • 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.

  • 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.

  • Add Message Number: when this option is checked, sender tasks will add the actual message number as a user-defined property to the Properties collection of the outgoing messages.

  • Send WCF Messages: when this option is checked, outgoing messages are wrapped in a SOAP envelope. This feature can be used to send messages to one or multiple consumers that use WCF and NetMessagingBinding to receive messages from a queue. The following table shows the code used by sender tasks to create a WCF message from a BrokeredMessage object used as template. As you can see, the WCF message needs to be encoded using a message encoder that depends on the protocol scheme used by a consumer to receive and decode the message.

 

/// <summary>
/// Create a BrokeredMessage for a WCF receiver.
/// </summary>
/// <param name="messageTemplate">The message template.</param>
/// <param name="taskId">The task Id.</param>
/// <param name="updateMessageId">Indicates whether to use a unique id for each message.</param>
/// <param name="oneSessionPerTask">Indicates whether to use a different session for each sender task.</param>
/// <param name="messageText">The message text.</param>
/// <param name="to">The name of the target topic or queue.</param>
/// <returns>The cloned BrokeredMessage object.</returns>
public BrokeredMessage CreateMessageForWcfReceiver(BrokeredMessage messageTemplate,
                                                    int taskId,
                                                    bool updateMessageId,
                                                    bool oneSessionPerTask,
                                                    string messageText,
                                                    string to)
{

    if (!IsXml(messageText))
    {
        throw new ApplicationException(MessageIsNotXML);
    }

    MessageEncodingBindingElement element;
    if (scheme == DefaultScheme)
    {
        element = new BinaryMessageEncodingBindingElement();
    }
    else
    {
        element = new TextMessageEncodingBindingElement();
    }
    using (var stringReader = new StringReader(messageText))
    {
        using (var xmlReader = XmlReader.Create(stringReader))
        {
            using (var dictionaryReader = XmlDictionaryReader.CreateDictionaryReader(xmlReader))
            {
                var message = Message.CreateMessage(MessageVersion.Default, "*", dictionaryReader);
                message.Headers.To = new Uri(namespaceUri, to);
                var encoderFactory = element.CreateMessageEncoderFactory();
                var encoder = encoderFactory.Encoder;
                var outputStream = new MemoryStream();
                encoder.WriteMessage(message, outputStream);
                outputStream.Seek(0, SeekOrigin.Begin);
                var outboundMessage = new BrokeredMessage(outputStream, true)
                {
                    ContentType = encoder.ContentType
                };
                if (!string.IsNullOrEmpty(messageTemplate.Label))
                {
                    outboundMessage.Label = messageTemplate.Label;
                }
                outboundMessage.MessageId = updateMessageId ? Guid.NewGuid().ToString() : messageTemplate.MessageId;
                outboundMessage.SessionId = oneSessionPerTask ? taskId.ToString() : messageTemplate.SessionId;
                if (!string.IsNullOrEmpty(messageTemplate.CorrelationId))
                {
                    outboundMessage.CorrelationId = messageTemplate.CorrelationId;
                }
                if (!string.IsNullOrEmpty(messageTemplate.ReplyTo))
                {
                    outboundMessage.ReplyTo = messageTemplate.ReplyTo;
                }
                if (!string.IsNullOrEmpty(messageTemplate.ReplyToSessionId))
                {
                    outboundMessage.ReplyToSessionId = messageTemplate.ReplyToSessionId;
                }
                outboundMessage.TimeToLive = messageTemplate.TimeToLive;
                foreach (var property in messageTemplate.Properties)
                {
                    outboundMessage.Properties.Add(property.Key, property.Value);
                }
                return outboundMessage;
            }
        }
    }
}

ReceiverTab

The Receiver tab allows the user to specify the following information:

  • Enabled: this checkbox allows enabling or disabling receiver tasks when testing a queue. When using the Service Bus Explorer tool to send messages to a real application, make sure to uncheck this option.

  • Task Count: this field can be used to define the number of consumer tasks that will be used to receive messages from the queue.

  • Receive Timeout: specifies the time span in seconds that consumer tasks wait before a time out occurs. When this happens, consumer tasks stop receiving messages from the queue. This value corresponds to the TimeSpan parameter of the Receive method exposed by the MessageReceiver and QueueClient classes.

  • Session Timeout: specifies the time span in seconds that consumer tasks wait for a new session before a time out occurs. This value corresponds to the TimeSpan parameter of the AcceptMessageSession method exposed by the QueueClient class.

  • Filter: the filter field can be used in conjunction with the Defer Message and Move to Deadletter Queue options to determine, respectively, the messages to defer or move to deadletter queue. This field accepts the SQL92 standard syntax accepted by the SqlExpression property of an SqlFilter object. Note: as shown in the following code snippet, a consumer application can use a SqlFilter to check at runtime whether a BrokeredMessage object matches a given condition.

 

...
var sqlFilter = new SqlFilter(!string.IsNullOrEmpty(txtFilterExpression.Text)
                              ? txtFilterExpression.Text
                              : DefaultFilterExpression);
sqlFilter.Validate();
filter = sqlFilter.Preprocess();
...
if (filter.Match(inboundMessage))
{
    inboundMessage.Defer();
    ...
}

  • Prefetch Count: specifies a value for the PrefetchCount property.of the MessageReceiver objects used by receiver tasks to consume messages from the current queue. This number indicates the number of messages that the message receiver can simultaneously request.

  • Receive Mode: indicates the receive mode (PeekLock or ReceiveAndDelete) used by consumer tasks.

  • Use Transaction: when this option is checked, consumer tasks will use a TransactionScope object to receive a batch of messages within a transaction context. For more information, see the code snippet in the table below.

  • Commit Transaction: when this option is checked, the consumer tasks will invoke the Complete method to commit the transaction and delete messages from the queue. Please note that when a consumer task receives one or multiple messages within a TransactionScope and at the end doesn’t call the Complete method, messages are not delete from the queue. The Use Transaction and Commit Transaction options can be used to test the behavior of receive-side transactions. For more information, see the code snippet in the table below.

 

using (var scope = new TransactionScope())
{
    serviceBusHelper.ReceiveMessages(...);
    ...
    if (checkBoxReceiverCommitTransaction.Checked)
    {
        scope.Complete();
        ...
    }
    ...
}

  • Enable Logging: when this option is checked, receiver tasks will track the operations performed in the log view.

  • Enable Verbose: when this option is checked, receiver tasks will log the payload and properties of transmitted messages.

  • Enable Statistics: when this option is checked, receiver tasks will update statistics in the Graph tab.

  • Enable Graph: when this option is checked, receiver tasks will update the latency and throughput charts in the Graph tab.

  • Move to Deadletter queue: when this option is checked, consumer tasks will move messages matching the SQL expression contained in the Filter field to the deadletter queue.

  • Read from Deadletter queue: when this option is checked, consumer tasks will read messages from the deadletter queue. Consider disabling sender tasks when using this option.

  • Defer Message: when this option is selected, consumer tasks will defer messages matching the SQL expression defined in the Filter field. Deferred messages will be processed at the end after the messages that do not match the filter expression. In order to save the SequenceNumber of deferred messages, consumer tasks use the following helper class. You can replace this component with another class that implements the custom IMessageDeferProvider interface. In this case, you need to indicate the fully-qualified-name of the new provider class in the messageDeferProvider setting in the configuration file.

 

public interface IMessageDeferProvider
{
    int Count { get; }
    void Enqueue(long sequenceNumber);
    bool Dequeue(out long sequenceNumber);
}

public class InMemoryMessageDeferProvider : IMessageDeferProvider
{
    #region Private Fields
    private readonly Queue<long> queue = new Queue<long>();
    #endregion

    #region Public Properties
    public int Count
    {
        get
        {
            lock (this)
            {
                return queue.Count;
            }
        }
    }
    #endregion

    #region Public Methods
    public bool Dequeue(out long sequenceNumber)
    {
        sequenceNumber = -1;
        lock (this)
        {
            if (queue.Count > 0)
            {
                sequenceNumber = queue.Dequeue();
                return true;
            }
        }
        return false;
    }

    public void Enqueue(long sequenceNumber)
    {
        lock (this)
        {
            queue.Enqueue(sequenceNumber);
        }
    }
    #endregion
}
  • Read WCF Message: when this option is checked, incoming messages are extracted from a SOAP envelope. This feature can be used to receive messages from an application that used WCF and NetMessagingBinding to send messages to a queue. The following table shows the code used by consumer tasks to extract a BrokeredMessage object from a WCF message. As you can see, the WCF message needs to be decoded using a message encoder that depends on the protocol scheme used by a WCF publisher to encode and send the message.

 

MessageEncodingBindingElement element;
if (scheme == DefaultScheme)
{
    element = new BinaryMessageEncodingBindingElement();
}
else
{
    element = new TextMessageEncodingBindingElement();
}
var encoderFactory = element.CreateMessageEncoderFactory();
encoder = encoderFactory.Encoder;
...
var stream = inboundMessage.GetBody<Stream>();
if (stream != null)
{
    var stringBuilder = new StringBuilder();
    var message = encoder.ReadMessage(stream, MaxBufferSize);
    using (var reader = message.GetReaderAtBodyContents())
    {
        // The XmlWriter is used just to indent the XML message
        var settings = new XmlWriterSettings { Indent = true };
        using (var writer = XmlWriter.Create(stringBuilder, settings))
        {
            writer.WriteNode(reader, true);
        }
    }
    messageText = stringBuilder.ToString();
}

  • Complete Receive: when this option is checked and the selected receive mode is equal to PeekLock, consumer tasks will call the Complete method on received messages to complete the receive operation and delete the message from the queue. Conversely, when this option is unchecked, consumer tasks will call the Abandon method on received messages to and relinquish the lock. This option can be used to test and examine the behavior of the Complete and Abandon methods of the BrokeredMessage class.

When the Enable Statistics and Enable Graph options are enabled, this tab displays performance statistics for sender and receiver tasks and four distinct chart series:

  • Sender Latency

  • Receiver Latency

  • Sender Throughput

  • Receiver Throughput

GraphTab1

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

ViewaTopic

The current version of the Service Bus does not allow to change the properties of an existing topic once created. The same principle applies to the other entities (queues, subscriptions, rules).

To create a new topic in the current namespace, you can select the Topics node or a path segment node under the Topics subtree and then perform one of the following actions:

  1. Right-click the node and choose Create Topic from the context menu.

  2. Choose Create Topic command under the Actions menu.

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

CreateTopic
  • Path: this field defines the path for the topic within the namespace. The value can be an absolute path like erp/prod/topics/ordertopic.

  • 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.

  • Max Size In Megabytes: the MaxSizeInMegabytes property defines the maximum size in megabytes, which is the size of memory allocated for the topic.

  • Enable Batched Operations: the EnableBatchedOperations property accepts a Boolean value that indicates whether server-side batched operations are enabled.

  • Requires Duplicate Detection: this checkbox specifies a Boolean value for the RequiresDuplicateDetection property that enables or disables the duplicate message detection feature.

The SizeInBytes is a read-only property and as such cannot be set when creating a topic. 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.

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

  1. Right-click the node and choose Delete Topic from the context menu.

  2. Choose Delete Topic command under the Actions menu.

  3. Click the Delete button in the Main Panel.

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

  1. Right-click the node and choose Test Topic from the context menu.

  2. Choose Test Topic command under the Actions menu.

This operation shows a custom control in the Main panel that is composed of four tabs:

  • Message Tab

  • Sender Tab

  • Receiver Tab

  • Graph Tab

The module that allows to test a topic is virtually identical to that we described above and that can be used to test a queue. The only addition is the ability to choose a Subscription in the Receiver tab as shown in the following picture.

TestTopic1

To view the properties of a subscription associated to a given topic, you can expand the Subscriptions node under the topic node and select the corresponding subscription node.

ViewSub1

The current version of the Service Bus does not allow to change the properties of an existing subscription once created. The same principle applies to the other entities (queues, topics, rules).

To add a new subscription to an existing topic, you can select the topic node in the treeview and then perform one of the following actions:

  • Right-click the topic node and choose Create Subscription from the context menu.

  • Expand the topic node, right-click the Subscriptions node under the latter and choose Create Subscription from the context menu.

  • Choose Create Subscription command under the Actions menu.

This operation displays a custom control (see the picture below) in the Main panel that allows the user to specify the following properties for the new subscription:

CreateSub1
  • Name: this field defines the name for the subscription being created.

  • Max Delivery Count: the MaxDeliveryCount property defines the maximum delivery count. A message is automatically deadlettered after this number of deliveries.

  • 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.

  • 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.

  • Enable Batched Operations: the EnableBatchedOperations property accepts a Boolean value that indicates whether server-side batched operations are enabled.

  • Enable Dead Lettering on Message Expiration: this checkbox specifies a Boolean value for the EnableDeadLetteringOnMessageExpiration property that enables or disables the dead-lettering functionality on message expiration.

  • Requires Duplicate Detection: this checkbox specifies a Boolean value for the RequiresDuplicateDetection property that enables or disables the duplicate message detection feature.

  • Requires Session: this checkbox specifies a Boolean value for the RequiresSession property that enables or disables sessions support on the subscription being created.

  • Filter: this field defines the SQL filter expression for the default rule.

  • Action: this field defines the SQL filter action for the default rule. This field is optional.

To remove an existing subscription, you can select the corresponding node in the treeview and then perform one of the following actions:

  1. Right-click the node and choose Delete Subscription from the context menu.

  2. Choose Delete Subscription command under the Actions menu.

  3. Click the Delete button in the Main panel.

To test a subscription, you can select the corresponding node in the treeview and then perform one of the following actions:

  1. Right-click the node and choose Test Subscription from the context menu.

  2. Choose Test Subscription command under the Actions menu.

This operation shows a custom control in the Main panel that is composed of two tabs:

  • Receiver Tab

  • Graph Tab

Please refer to the Test a Queue section for a description of the functionality and options of the Receiver and Graph tabs.

TestSub

To view the properties of a rule associated to a given subscription, you can expand the Rules node under the subscription node and select the corresponding rule node, as illustrated in the picture below.

ViewRulw

To add a new rule to an existing subscription, you can select the subscription node in the treeview and then perform one of the following actions:

  1. Right-click the subscription node and choose Add Rule from the context menu.

  2. Expand the subscription node, right-click the Rules node under the latter and choose Add Rule from the context menu.

  3. Choose Add Rule command under the Actions menu.

This operation displays a custom control (see the picture below) in the Main panel that allows the user to specify the following properties for the new rule:

  • Name: this field defines the name for the new rule.

  • Is Default Rule: this checkbox can be used to indicate that the rule being created is the default rule for the current subscription. If the subscription in question already owns a default rule, this field is disabled.

  • Filter: this field defines the SQL filter expression for the new rule.

  • Action: this field defines the SQL filter action for the new rule.

AddRule1

To remove an existing rule from a subscription, you can select the corresponding node in the treeview and then perform one of the following actions:

  1. Right-click the node and choose Remove Rule from the context menu.

  2. Choose Remove Rule command under the Edit menu.

  3. Click the Remove button in the Main Panel.

To test one of endpoints exposed by a relay service, you can select the corresponding node in the treeview as highlighted in red in the following picture.

TestRelayEP

This operation shows a custom control in the Main panel that is composed of three tabs:

  • Message Tab

  • Sender Tab

  • Graph Tab

MessageTab

The Message tab allows the user to specify the following information:

  • Message Text: specifies the payload of a WCF message. The tool provides the ability to read the message from the file system by pressing the Open button and selecting an XML file.

  • Message Properties: you can use the datagrid to define the custom headers, as shown in the picture above.

SenderTab

The Sender tab allows the user to specify the following information:

  • Task Count: this field can be used to define the number of sender tasks that will be used to transmit messages to the relay service. Every task runs on a separate .NET thread pool thread.

  • Message Count: this integer field can be used to specify the number of messages to send.

  • Method Action: specified the value for the WS-Addressing Action header.

  • Enable Logging: when this option is checked, sender tasks will track the operations performed in the log view.

  • Enable Verbose: when this option is checked, sender tasks will log the payload and headers of request and response messages (if any).

  • Enable Statistics: when this option is checked, sender tasks will update statistics in the Graph tab.

  • Enable Graph: when this option is checked, sender tasks will update the latency and throughput charts in the Graph tab.

  • Binding: you can use this section to select and configure the binding used by the tool to communicate with the underlying relay service. In particular, make sure to properly configure the security section to match settings specified in the configuration file of the relay service.

When the Enable Statistics and Enable Graph options are enabled, this tab displays performance statistics for sender tasks and two distinct chart series:

  • Sender Latency

  • Sender Throughput

GraphTab11

The Service Bus Explorer is the perfect tool to explore the features provided by the Service Bus and a useful companion for all developers and system administrators that work with it every day. In the future I will continue to develop and extend the tool with new features as they will be made available by the Service Bus team. In the meantime, I invite you to share your ideas on how to improve the tool and I strongly encourage you to download from the MSDN Code Gallery and customize my code to accommodate your needs.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft