How to Use Service Bus Queues
This guide describes how to use Service Bus queues. The samples are written in C# and use the .NET API. The scenarios covered include creating queues and sending and receiving messages. For more information about queues, see the Next Steps section.
What are Service Bus Queues?
Service Bus queues support a brokered messaging communication model. When using queues, components of a distributed application do not communicate directly with each other; instead they exchange messages via a queue, which acts as an intermediary (broker). A message producer (sender) hands off a message to the queue and then continues its processing. Asynchronously, a message consumer (receiver) pulls the message from the queue and processes it. The producer does not have to wait for a reply from the consumer in order to continue to process and send further messages. Queues offer First In, First Out (FIFO) message delivery to one or more competing consumers. That is, messages are typically received and processed by the receivers in the order in which they were added to the queue, and each message is received and processed by only one message consumer.
Service Bus queues are a general-purpose technology that can be used for a wide variety of scenarios:
- Communication between web and worker roles in a multi-tier Azure application.
- Communication between on-premises apps and Azure hosted apps in a hybrid solution.
- Communication between components of a distributed application running on-premises in different organizations or departments of an organization.
Using queues enables you to scale out your applications more easily, and enable more resiliency to your architecture.
Create a service namespace
To begin using Service Bus queues in Azure, you must first create a service namespace. A namespace provides a scoping container for addressing Service Bus resources within your application.
To create a service namespace:
Log on to the Azure Management Portal.
In the left navigation pane of the Management Portal, click Service Bus.
In the lower pane of the Management Portal, click Create.
In the Add a new namespace dialog, enter a namespace name. The system immediately checks to see if the name is available.
After making sure the namespace name is available, choose the country or region in which your namespace should be hosted (make sure you use the same country/region in which you are deploying your compute resources).
IMPORTANT: Pick the same region that you intend to choose for deploying your application. This will give you the best performance.
Leave the other fields in the dialog with their default values (Messaging and Standard Tier), then click the check mark. The system now creates your namespace and enables it. You might have to wait several minutes as the system provisions resources for your account.
The namespace you created takes a moment to activate, and will then appear in the management portal. Wait until the namespace status is Active before continuing.
Obtain the default management credentials for the namespace
In order to perform management operations, such as creating a queue on the new namespace, you must obtain the management credentials for the namespace. You can obtain these credentials from either the Azure management portal, or from the Visual Studio Server Explorer.
To obtain management credentials from the portal
In the left navigation pane, click the Service Bus node, to display the list of available namespaces:
Select the namespace you just created from the list shown:
Click Connection Information.
In the Access connection information pane, find the connection string that contains the SAS key and key name.
Make a note of the key, or copy it to the clipboard.
To obtain management credentials from Server Explorer
To obtain connection information using Visual Studio instead of the management portal, follow the procedure described here, in the section titled To connect to Azure from Visual Studio. When you sign in to Azure, the Service Bus node under the Azure tree in Server Explorer is automatically populated with any namespaces you've already created. Right-click any namespace, and then click Properties to see the connection string and other metadata associated with this namespace displayed in the Visual Studio Properties pane.
Make a note of the SharedAccessKey value, or copy it to the clipboard:
Configure the application to use Service Bus
When you create an application that uses Service Bus, you must add a reference to the Service Bus assembly and include the corresponding namespaces.
Add the Service Bus NuGet package
The Service Bus NuGet package is the easiest way to get the Service Bus API and to configure your application with all of the Service Bus dependencies. The NuGet Visual Studio extension makes it easy to install and update libraries and tools in Visual Studio and Visual Studio Express. The Service Bus NuGet package is the easiest way to get the Service Bus API and to configure your application with all of the Service Bus dependencies.
To install the NuGet package in your application, do the following:
- In Solution Explorer, right-click References, then click Manage NuGet Packages.
Search for "Service Bus" and select the Microsoft Azure Service Bus item. Click Install to complete the installation, then close this dialog.
You are now ready to write code for Service Bus.
How to set up a Service Bus connection string
Service Bus uses a connection string to store endpoints and credentials. You can put your connection string in a configuration file, rather than hard-coding it:
- When using Azure Cloud Services, it is recommended that you store your connection string using the Azure service configuration system (.csdef and **.cscfg** files).
- When using Azure Websites or Azure Virtual Machines, it is recommended that you store your connection string using the .NET configuration system (for example, the Web.config file).
In both cases, you can retrieve your connection string using the
CloudConfigurationManager.GetSetting method, as shown later in this guide.
Configuring your connection string when using Cloud Services
The service configuration mechanism is unique to Azure Cloud Services projects and enables you to dynamically change configuration settings from the Azure management portal without redeploying your application. For example, add a
Setting label to your service definition (*.csdef) file, as shown here:
<WebRole name="MyRole" vmsize="Small">
<Setting name="Microsoft.ServiceBus.ConnectionString" />
You then specify values in the service configuration (*.cscfg) file:
Use the Shared Access Signature (SAS) key name and key values retrieved from the management portal as described in the previous section.
Configuring your connection string when using Websites or Virtual Machines
When using Websites or Virtual Machines, it is recommended that you use the .NET configuration system (for example, Web.config). You store the connection string using the
Use the SAS name and key values that you retrieved from the management portal, as described in the previous section.
How to create a queue
You can perform management operations for Service Bus queues using the
NamespaceManager class. This class provides methods to create, enumerate, and delete queues.
This example constructs a
NamespaceManager object using the Azure
CloudConfigurationManager class with a connection string consisting of the base address of a Service Bus service namespace and the appropriate SAS credentials with permissions to manage it. This connection string is of the form
For example, given the configuration settings in the previous section:
// Create the queue if it does not exist already
string connectionString =
var namespaceManager =
There are overloads of the
CreateQueue method that enable you to tune properties of the queue (for example, to set the default "time-to-live" value to be applied to messages sent to the queue). These settings are applied by using the
QueueDescription class. The following example shows how to create a queue named "TestQueue" with a maximum size of 5 GB and a default message time-to-live of 1 minute:
// Configure queue settings
QueueDescription qd = new QueueDescription("TestQueue");
qd.MaxSizeInMegabytes = 5120;
qd.DefaultMessageTimeToLive = new TimeSpan(0, 1, 0);
// Create a new queue with custom settings
string connectionString =
var namespaceManager =
You can use the
QueueExists method on
NamespaceManager objects to check if a queue with a specified name already exists within a service namespace.
How to send messages to a queue
To send a message to a Service Bus queue, your application creates a
QueueClient object using the connection string.
The code below demonstrates how to create a
QueueClient object for the "TestQueue" queue you just created using the
CreateFromConnectionString API call:
string connectionString =
QueueClient Client =
Messages sent to (and received from) Service Bus queues are instances of the
BrokeredMessage objects have a set of standard properties (such as
TimeToLive), a dictionary that is used to hold custom application specific properties, and a body of arbitrary application data. An application can set the body of the message by passing any serializable object into the constructor of the
BrokeredMessage object, and the appropriate DataContractSerializer will then be used to serialize the object. Alternatively, a System.IO.Stream can be provided.
The following example demonstrates how to send five test messages to the "TestQueue"
QueueClient object obtained in the previous code snippet:
for (int i=0; i<5; i++)
// Create message, passing a string message for the body
BrokeredMessage message = new BrokeredMessage("Test message " + i);
// Set some addtional custom app-specific properties
message.Properties["TestProperty"] = "TestValue";
message.Properties["Message number"] = i;
// Send message to the queue
Service Bus queues support a maximum message size of 256 Kb (the header, which includes the standard and custom application properties, can have a maximum size of 64 Kb). There is no limit on the number of messages held in a queue but there is a cap on the total size of the messages held by a queue. This queue size is defined at creation time, with an upper limit of 5 GB. If partitioning is enabled, the upper limit is higher. For more information, see Partitioning Messaging Entities.
How to receive messages from a queue
The recommended way to receive messages from a queue is to use a
QueueClient objects can work in two different modes:
When using the ReceiveAndDelete mode, the receive is a single-shot operation - that is, when Service Bus receives a read request for a message in a queue, it marks the message as consumed, and returns it to the application. ReceiveAndDelete is the simplest model and works best for scenarios in which an application can tolerate not processing a message in the event of a failure. To understand this, consider a scenario in which the consumer issues the receive request and then crashes before processing it. Because Service Bus will have marked the message as consumed, when the application restarts and begins consuming messages again, it will have missed the message that was consumed prior to the crash.
In PeekLock mode (which is the default mode), the receive becomes a two-stage operation, which makes it possible to support applications that cannot tolerate missing messages. When Service Bus receives a request, it finds the next message to be consumed, locks it to prevent other consumers receiving it, and then returns it to the application. After the application finishes processing the message (or stores it reliably for future processing), it completes the second stage of the receive process by calling
Complete on the received message. When Service Bus sees the
Complete call, it marks the message as consumed, and removes it from the queue.
The following example demonstrates how messages can be received and processed using the default PeekLock mode. To specify a different
ReceiveMode value, you can use another overload of
CreateFromConnectionString. This example uses the
OnMessage callback to process messages as they arrive into the "TestQueue".
string connectionString =
QueueClient Client =
// Configure the callback options
OnMessageOptions options = new OnMessageOptions();
options.AutoComplete = false;
options.AutoRenewTimeout = TimeSpan.FromMinutes(1);
// Callback to handle received messages
// Process message from queue
Console.WriteLine("Body: " + message.GetBody<string>());
Console.WriteLine("MessageID: " + message.MessageId);
Console.WriteLine("Test Property: " +
// Remove message from queue
// Indicates a problem, unlock message in queue
This example configures the
OnMessage callback using an
AutoComplete is set to false to enable manual control over when to call
Complete on the received message.
AutoRenewTimeout is set to 1 minute, which causes the client to wait for up to one minute for a message before the call times out and the client makes a new call to check for messages. This property value reduces the number of times the client makes chargeable calls that do not retrieve messages.
How to handle application crashes and unreadable messages
Service Bus provides functionality to help you gracefully recover from errors in your application or with difficulties processing a message. If a receiver application is unable to process the message for some reason, then it can call the
Abandon method on the received message (instead of the
Complete method). This causes Service Bus to unlock the message within the queue and make it available to be received again, either by the same consuming application or by another consuming application.
There is also a timeout associated with a message locked within the queue, and if the application fails to process the message before the lock timeout expires (for example, if the application crashes), then Service Bus unlocks the message automatically and makes it available to be received again.
In the event that the application crashes after processing the message but before the
Complete request is issued, the message will be redelivered to the application when it restarts. This is often called At Least Once Processing; that is, each message is processed at least once but in certain situations the same message may be redelivered. If the scenario cannot tolerate duplicate processing, then application developers should add additional logic to their application to handle duplicate message delivery. This is often achieved using the
MessageId property of the message, which remains constant across delivery attempts.
Now that you've learned the basics of Service Bus queues, follow these links to learn more.