Skip Navigation LinksAzure Developers Guide > Azure Service Bus > Brokered Messaging > Managing Messaging Artifacts > NamespaceManager Class > Managing Queues

Training Courses

All course material is in English, and courses are delivered in English. Feel free to contact me for further information. cloudcasts.net@gmail.com

Managing Queues

Queues, topics and subscriptions are managed programmatically by calling methods on the NamespaceManager class. As the techniques for managing queues are very similar to that of topics and subscriptions queue management will be covered in detail, then additional coverage for topics and subscriptions provided where appropriate.

Creating Queues

The CreateQueue method of the NamespaceManager is overloaded and provides two options for creating queues.

 

public QueueDescription CreateQueue(string path)

 

public QueueDescription CreateQueue(QueueDescription description)

 

 

The first method will create a queue with the address of the NamespaceManager and path specified. The queue created will have the default property values. If the default property values are to be overridden, a QueueDescription can be created and the appropriate values set. This can then be used to create the queue using the second method.

Attempting to create queue with a path that already exists in the service bus namespace will result in a MessagingEntityAlreadyExistsException exception being thrown.

QueueDescription Class

The QueueDescription class is a data contract class that provides properties which can be set when creating a queue. Setting any of these properties will override their default values in the new queue.

Useful QueueDescription Properties

DefaultMessageTimeToLive

The DefaultMessageTimeToLive is a TimeSpan property that sets the default expiration timeout for messages that are added to the queue. The default value is TimeSpan.MaxValue, which is almost 30,000 years, meaning that messages will never expire during the expected lifetime of the application. If this value is set for a queue, any messages placed on that queue that have not been assigned a TimeToLive value will default to the value set for the queue. If the sending application has set the TimeToLive value for the message the value will not be changed.

DuplicateDetectionHistoryTimeWindow

If duplicate detection is enabled for a queue the DuplicateDetectionHistoryTimeWindow value will specify how long the MessageId values for the received messages will be retained in order to check for duplicate messages. The property is a TimeSpan with a default value of 10 minutes and a maximum allowed value of 7 days.

EnableDeadLetteringOnMessageExpiration

By default any messages that have been on the queue for longer than the assigned time to live will expire and be removed from the queue. Setting EnableDeadLetteringOnMessageExpiration will cause expired messages to be moved to the dead-letter queue instead of being removed from the queue. This will allow the messages to be processed at a later point in time.

Be aware that expired messages on the dead letter queue will increase the size of the queue, which could result in the queue failing to receive new messages if expired messages are not de-queued from the dead letter queue.

IsReadOnly

When an instance of the QueueDescription class is created using the default constructor the properties can be modified. When a QueueDescription for a queue that is present in a service bus namespace is returned the properties can’t be modified. The IsReadOnly property indicates weather the queue description properties can be modified.

LockDuration

LockDuration is a TimeSpan property that determines the maximum time a message will remain in the locked state when received using the peek-lock receive mode. The default value is 30 seconds; the maximum allowed value is 5 minutes. If the receiver fails to complete, abandon, defer or dead-letter the message within this time the message will become visible on the queue for other receivers to receive.

If it is expected that the receiving application may take longer than 30 seconds to determine if a message can be successfully processed or not the LockDuration of the queue should be set to an appropriate value. Be aware that it is no possible for the receiving application to specify the lock duration when dequeuing a message, and once a queue is created the lock duration cannot be changed. In production systems care should be taken to ensure a suitable lock duration has been set.

MaxDeliveryCount

The MaxDeliveryCount property specifies the maximum number of times a message can be received by a receiving application before the message is automatically place on the dead letter queue. This is used to prevent the repeated processing of “poison messages” causing bottle necks in a message channel.

The default setting is 10, the minimum allowed value is 1 and the maximum allowed value is int.MaxValue, (2,147,483,647). Setting the maximum value effectively turns off the dead lettering of poison messages.

MaxSizeInMegabytes

The MaxSizeInMegabytes property defines the maximum size a queue can reach before new messages are rejected from the queue. The default setting is 1,024, which is 1 GB, and the current maximum allowable value is 5120, which is 5 GB. The maximum size of a queue in GB is used as a multiplier when calculating the billing for entity hours in the service bus, a queue with a maximum size of 4 GB will be billed at 4 times the price of one with a maximum size of 1 GB.

MessageCount

The MessageCount property returns a count of the number of messages on the queue.

RequiresDuplicateDetection

When set to true, the RequiresDuplicateDetection property will ensure that all enqueued messages with a duplicate value of the MessageId property within the DuplicateDetectionHistoryTimeWindow will be ignored.

RequiresSession

The RequiresSession property specifies that messages sent to the queue most have a value set for their SessionId property. Sessions are used for correlating related messages into transactions.

SizeInBytes

The SizeInBytes returns the current size of the queue.

Examples

The following code shows how to create two queues using the two overloaded methods.

 

// Create a token provider with the relevant credentials.

TokenProvider credentials =

    TokenProvider.CreateSharedSecretTokenProvider

    (AccountDetails.Name, AccountDetails.Key);

 

// Create a URI for the serivce bus.

Uri serviceBusUri = ServiceBusEnvironment.CreateServiceUri

    ("sb", AccountDetails.Namespace, string.Empty);

 

// Create a ServiceBusNamespaceClient for the specified namespace

// using the specified credentials.

NamespaceManager namespaceManager = new NamespaceManager(serviceBusUri, credentials);

 

// Create a queue with the default properties.

QueueDescription defaultQueueDescription = namespaceManager.CreateQueue("defaultproperties");

WriteQueueDescription(defaultQueueDescription);

 

// Create a custom queue description.

QueueDescription customDescription = new QueueDescription("customproperties")

{

    DefaultMessageTimeToLive = TimeSpan.FromHours(1),

    EnableDeadLetteringOnMessageExpiration = true,

    RequiresDuplicateDetection = true,

    DuplicateDetectionHistoryTimeWindow = TimeSpan.FromMinutes(5),

    LockDuration = TimeSpan.FromMinutes(2),

    RequiresSession = true

};

 

// Create a queue using the queue description.

QueueDescription customQueueDescription = namespaceManager.CreateQueue(customDescription);

WriteQueueDescription(customQueueDescription);

 

 

The WriteQueueDescription method is implemented as follows.

 

static void WriteQueueDescription(QueueDescription queueDescription)

{

    Console.WriteLine("Queue Path:                                   {0}",

        queueDescription.Path);

    Console.WriteLine("Queue MessageCount:                           {0}",

        queueDescription.MessageCount);

    Console.WriteLine("Queue SizeInBytes:                            {0}",

        queueDescription.SizeInBytes);

    Console.WriteLine("Queue RequiresSession:                        {0}",

        queueDescription.RequiresSession);

    Console.WriteLine("Queue RequiresDuplicateDetection:             {0}",

        queueDescription.RequiresDuplicateDetection);

    Console.WriteLine("Queue DuplicateDetectionHistoryTimeWindow:    {0}",

        queueDescription.DuplicateDetectionHistoryTimeWindow);

    Console.WriteLine("Queue LockDuration:                           {0}",

        queueDescription.LockDuration);

    Console.WriteLine("Queue DefaultMessageTimeToLive:               {0}",

        queueDescription.DefaultMessageTimeToLive);

    Console.WriteLine("Queue EnableDeadLetteringOnMessageExpiration: {0}",

        queueDescription.EnableDeadLetteringOnMessageExpiration);

    Console.WriteLine("Queue EnableBatchedOperations:                {0}",

        queueDescription.EnableBatchedOperations);

    Console.WriteLine("Queue MaxSizeInMegabytes:                     {0}",

        queueDescription.MaxSizeInMegabytes);

    Console.WriteLine("Queue MaxDeliveryCount:                       {0}",

        queueDescription.MaxDeliveryCount);

    Console.WriteLine("Queue IsReadOnly:                             {0}",

        queueDescription.IsReadOnly);

    Console.WriteLine();

}

 

 

When the code is run the following output is displayed.

 

Listing Queues

The following code will retrieve a list of queues from a service bus namespace and output the queue details.

 

IEnumerable<QueueDescription> queueDescriptions = namespaceManager.GetQueues();

 

foreach (QueueDescription queueDescription in queueDescriptions)

{

    WriteQueueDescription(queueDescription);

}

 

 

Deleting Queues

Queues can be deleted using the DeleteQueue method of NamespaceManager, specifying the path of the queue. Attempting to delete a queue that does not exist will result in a MessagingEntityNotFoundException being thrown.

The following code shows how to delete all the queues in a service bus namespace.

 

IEnumerable<QueueDescription> queueDescriptions = namespaceManager.GetQueues();

 

foreach (QueueDescription queueDescription in queueDescriptions)

{

    Console.Write("Deleting {0}...", queueDescription.Path);

    namespaceManager.DeleteQueue(queueDescription.Path);

    Console.WriteLine("Done!");

}

 

 

As messaging entities are billed on an hourly basis it would be wise for developers to have a quick an easy way or removing a number of queues and topics form a namespace when a development or testing session is complete.

Speaking Engagements