{"id":6739,"date":"2011-05-25T00:00:00","date_gmt":"2011-05-25T00:00:00","guid":{"rendered":"https:\/\/azure.microsoft.com\/blog\/an-introduction-to-service-bus-topics"},"modified":"2025-09-10T13:15:12","modified_gmt":"2025-09-10T20:15:12","slug":"an-introduction-to-service-bus-topics","status":"publish","type":"post","link":"https:\/\/azure.microsoft.com\/en-us\/blog\/an-introduction-to-service-bus-topics\/","title":{"rendered":"An Introduction to Service Bus Topics"},"content":{"rendered":"\n

[This article was contributed by the AppFabric team.]<\/p>\n\n\n\n

In the May CTP of Service Bus, we\u2019ve added a brand-new set of cloud-based, message-oriented-middleware technologies including reliable message queuing and durable publish\/subscribe messaging. Last week I posted the Introduction to Service Bus Queues<\/a> blog entry. This post follows on from that and provides an introduction to the publish\/subscribe capabilities offered by Service Bus Topics. Again, I\u2019m not going to cover all the features in this article, I just want to give you enough information to get started with the new feature. We\u2019ll have follow-up posts that drill into some of the details.<\/p>\n\n\n\n


I\u2019m going to continue with the retail scenario that I started in the queues blog post<\/a>. Recall that sales data from individual Point of Sale (POS) terminals needs to be routed to an inventory management system which uses that data to determine when stock needs to be replenished. Each POS terminal reports its sales data by sending messages to the DataCollectionQueue where they sit until they are received by the inventory management system as shown below:<\/p>\n\n\n\n

\"diagram<\/figure>\n\n\n\n

<\/p>\n\n\n\n

Now let\u2019s evolve this scenario. A new requirement has been added to the system: the store owner wants to be able to monitor how the store is performing in real-time.<\/p>\n\n\n\n

To address this requirement we need to take a \u201ctap\u201d off the sales data stream. We still want each message sent by the POS terminals to be sent to the Inventory Management System as before but we want another copy of each message that we can use to present the dashboard view to the store owner.<\/p>\n\n\n\n

In any situation like this, where you need each message to be consumed by multiple parties, you need the Service Bus Topic feature. Topics provide the publish\/subscribe pattern in which each published message is made available to each subscription registered with the Topic. Contrast this with the queue where each message is consumed by a single consumer. That\u2019s the key difference between the two models.<\/p>\n\n\n\n

Messages are sent to a topic in exactly the same way as they are sent to a queue but messages aren\u2019t received from the topic directly, instead they are received from subscriptions. You can think of a topic subscription like a virtual queue that gets copies of the messages that are sent to the topic. Messages are received from a subscription in exactly the same way as they are received from a queue.<\/p>\n\n\n\n

So, going back to the scenario, the first thing to do is to switch out the queue for a topic and add a subscription that will be used by the Inventory Management System. So, the system would now look like this:<\/p>\n\n\n\n

\"diagram<\/figure>\n\n\n\n

<\/p>\n\n\n\n

The above configuration would perform identically to the previous queue-based design. That is, messages sent to the topic would be routed to the Inventory subscription from where the Inventory Management System would consume them.<\/p>\n\n\n\n

Now, in order to support the management dashboard, we need to create a second subscription on the topic as shown below:<\/p>\n\n\n\n

\"another<\/figure>\n\n\n\n

<\/p>\n\n\n\n

Now, with the above configuration, each message from the POS terminals will be made available to both the Dashboard and Inventory subscriptions.<\/p>\n\n\n\n

Show Me the Code<\/h2>\n\n\n\n

I described how to sign-up for a Service Bus account and create a namespace in the queues blog post<\/a> so I won\u2019t cover that again here. Recall that to use the Service Bus namespace, an application needs to reference the AppFabric Service Bus DLLs, namely Microsoft.ServiceBus.dll and Microsoft.ServiceBus.Messaging.dll. You can find these as part of the SDK download.<\/p>\n\n\n\n

Creating the Topic and Subscriptions<\/h3>\n\n\n\n

Management operations for Service Bus messaging entities (queues and topics) are performed via the ServiceBusNamespaceClient which is constructed with the base address of the Service Bus namespace and the user credentials. The ServiceBusNamespaceClient provides methods to create, enumerate and delete messaging entities. The snippet below shows how the ServiceBusNamespaceClient is used to create the DataCollectionTopic.<\/p>\n\n\n\n

    Uri ServiceBusEnvironment.CreateServiceUri(“sb”, “ingham-blog”, string.Empty);<\/p>\n\n\n\n

    string name = “owner”;<\/p>\n\n\n\n

    string key = “abcdefghijklmopqrstuvwxyz”;<\/p>\n\n\n\n

    ServiceBusNamespaceClient namespaceClient = new ServiceBusNamespaceClient(<\/p>\n\n\n\n

        baseAddress, TransportClientCredentialBase.CreateSharedSecretCredential(name, key) );<\/p>\n\n\n

\n Topic dataCollectionTopic = namespaceClient.CreateTopic(\"DataCollectionTopic\");\n<\/pre><\/div>\n\n\n
Note that there are overloads of the CreateTopic method that allow properties of the topic to be tuned, for example, to set the default time-to-live to be applied to messages sent to the topic. Next, let\u2019s add the Inventory and Dashboard subscriptions.<\/p>\n\n\n
\n    dataCollectionTopic.AddSubscription(\"Inventory\");\n<\/pre><\/div>\n\n
\n    dataCollectionTopic.AddSubscription(\"Dashboard\");\n<\/pre><\/div>\n\n\n
Sending Messages to the Topic<\/h3>\n\n\n\n
As I mentioned earlier, applications send messages to a topic in the same way that they send to a queue so the code below will look very familiar if you read the queues blog post<\/a>. The difference is the application creates a TopicClient instead of a QueueClient.<\/p>\n\n\n\n
For runtime operations on Service Bus entities, i.e., sending and receiving messages, an application first needs to create a MessagingFactory. The base address of the ServiceBus namespace and the user credentials are required.<\/p>\n\n\n\n
    Uri ServiceBusEnvironment.CreateServiceUri(“sb”, “ingham-blog”, string.Empty);<\/p>\n\n\n\n
    string name = “owner”;<\/p>\n\n\n\n
    string key = “abcdefghijklmopqrstuvwxyz”;<\/p>\n\n\n\n
    MessagingFactory factory = MessagingFactory.Create(<\/p>\n\n\n\n
        baseAddress, TransportClientCredentialBase.CreateSharedSecretCredential(name, key) );<\/p>\n\n\n\n
From the factory, a TopicClient is created for the particular topic of interest, in our case, the DataCollectionTopic.<\/p>\n\n\n\n
    TopicClient topicClient = factory.CreateTopicClient(“DataCollectionTopic”);<\/p>\n\n\n\n
A MessageSender is created from the TopicClient to perform the send operations.<\/p>\n\n\n\n
    MessageSender ms = topicClient.CreateSender();<\/p>\n\n\n\n
Messages sent to, and received from, Service Bus topics (and queues) are instances of the BrokeredMessage class which consists of a set of standard properties (such as Label and TimeToLive), a dictionary that is used to hold application properties, and a body of arbitrary application data. An application can set the body by passing in any serializable object into CreateMessage (the example below passes in a SalesData object representing the sales data from the POS terminal) which will use the DataContractSerializer to serialize the object. Alternatively, a System.IO.Stream can be provided.<\/p>\n\n\n\n
    BrokeredMessage bm = BrokeredMessage.CreateMessage(salesData);<\/p>\n\n\n\n
    bm.Label = “SalesReport”;<\/p>\n\n\n\n
    bm.Properties[“StoreName”] = “Redmond”;<\/p>\n\n\n\n
    bm.Properties[“MachineID”] = “POS_1”;<\/p>\n\n\n\n
    ms.Send(bm);<\/p>\n\n\n\n
Receiving Messages from a Subscription<\/h3>\n\n\n\n
Just like when using queues, messages are received from a subscription using a MessageReceiver. The difference is that the MessageReceiver is created from a SubscriptionClient rather than a QueueClient. Everything else remains the same including support for the two different receive modes (ReceiveAndDelete and PeekLock) that I discussed in the queues blog post<\/a>.<\/p>\n\n\n\n
So, first we create the SubscriptionClient, passing the name of the topic and the name of the subscription as parameters. Here I\u2019m using the Inventory subscription.<\/p>\n\n\n
\n    SubscriptionClient subClient = factory.CreateSubscriptionClient(\"DataCollectionTopic\", \"Inventory\");\n<\/pre><\/div>\n\n\n
Next we create the MessageReceiver and receive a message.<\/p>\n\n\n\n
    MessageReceiver mr = subClient.CreateReceiver();<\/p>\n\n\n\n
    BrokeredMessage receivedMessage = mr.Receive();<\/p>\n\n\n\n
    try<\/p>\n\n\n\n
    {<\/p>\n\n\n\n
        ProcessMessage(receivedMessage);<\/p>\n\n\n\n
        receivedMessage.Complete();<\/p>\n\n\n\n
    }<\/p>\n\n\n\n
    catch (Exception e)<\/p>\n\n\n\n
    {<\/p>\n\n\n\n
        receivedMessage.Abandon();<\/p>\n\n\n\n
    }<\/p>\n\n\n\n
Subscription Filters<\/h2>\n\n\n\n
So far, I\u2019ve said that all messages sent to the topic are made available to all registered subscriptions. The key phrase there is \u201cmade available\u201d. While Service Bus subscriptions see all messages sent to the topic, it is possible to only copy a subset of those messages to the virtual subscription queue. This is done using subscription filters. When a subscription is created, it\u2019s possible to supply a filter expression in the form of a SQL92 style predicate that can operate over the properties of the message, both the system properties (e.g., Label) and the application properties, such as StoreName in the above example.<\/p>\n\n\n\n
Let\u2019s evolve the scenario a little to illustrate this. A second store is to be added to our retail scenario. Sales data from all of the POS terminals from both stores still need to be routed to the centralized Inventory Management System but a store manager using the Dashboard tool is only interested in the performance of her store. We can use subscription filtering to achieve this. Note that when the POS terminals publish messages, they set the StoreName application property on the message. Now we have two stores, let\u2019s say Redmond and Seattle, the POS terminals in the Redmond store stamp their sales data messages with a StoreName of Redmond while the Seattle store POS terminals use a StoreName of Seattle. The store manager of the Redmond store only wishes to see data from its POS terminals. Here\u2019s how the system would look:<\/p>\n\n\n\n
\"diagram<\/figure>\n\n\n\n
To set this routing up, we need to make a simple change to how we\u2019re creating the Dashboard subscription as follows:<\/p>\n\n\n
\n    dataCollectionTopic.AddSubscription(\"Dashboard\", new SqlFilterExpression(\"StoreName = 'Redmond'\");\n<\/pre><\/div>\n\n\n
With this subscription filter in place, only messages with the StoreName property set to Redmond will be copied to the virtual queue for the Dashboard subscription.<\/p>\n\n\n\n
There is a bigger story to tell around subscription filtering. Applications have an option to have multiple filter rules per subscription and there\u2019s also the ability to modify the properties of a message as it passes in to a subscription\u2019s virtual queue. We\u2019ll cover these advanced topics in a separate blog post.<\/p>\n\n\n\n
Wrapping up<\/h2>\n\n\n\n
Hopefully this post has shown you how to get started with the topic-based publish\/subscribe feature being introduced in the new May CTP of Service Bus.<\/p>\n\n\n\n
It\u2019s worth noting that all of the reasons for using queuing that I mentioned in the introduction to queuing blog post<\/a> also apply to topics, namely:<\/p>\n\n\n\n