Windows Azure : Messaging with the queue - Working with basic queue operations

To show you how to use the basic queue API operations, we’re going to build a queue browser. This little tool (shown in figure 1) will help you debug any system you’re building, by letting you look at the queues that are being used and see how they’re working.

Figure 1. A screenshot of the simple queue browser we’ll build in this article. It’s important to note that your authors, while charming, aren’t graphic designers or UX specialists. This tool will act as a vehicle for understanding the basics of working with queues.

We’ll be focusing on creating methods that perform each of the following operations of the browser:

• ListQueues()— Lists the queues that exist in your storage account

• Create() or CreateIfNotExist()— Creates queues in your account

• SetMetadata()— Writes metadata

• Clear()— Clears a queue of all of its pending messages

• Delete()— Deletes a queue or a message from the system

We aren’t going to focus on how WPF works, or the best application architecture for this little application. This is meant to be “me-ware”—something that works for you and doesn’t have to work for anyone else. You should use it as a harness to play with the different APIs and learn how they work.

1. Get a list of queues

There are several basic queue operations that you’ll need to be able to work with. The first one we’re going to look at is a method that will tell you what queues exist in your account. You may not always need this. Usually, you’ll know what the queue for your application is and provision it for yourself.

To get a list of the available queues, you need to first connect to the queue service and then call the method. You can see how in the following listing.

Listing 1. Connecting to the queue service and getting a list of queues

You’ll use something like line quite often. This creates a connection to the service, similar to how you create a connection object to a database. You’ll want to create this once for a block of code and hold it in memory so that you aren’t always reconnecting to the service. In this little application, we create this object in the constructor for the window itself and store it in a variable at the form level. This makes it available to every method in the form and saves you the trouble of having to continuously recreate the object.

The CloudStorageAccount serves as a factory that creates service objects that represent the Azure Queue storage service, called the CloudQueueClient. There are several ways to create the CloudQueueClient. The most common approach is to create it as in listing 16.3, by using the FromConfigurationSetting method. This looks into your configuration and sets up all of the URIs, usernames, account names, and so on. This is better than having to set four or five different parameters when you’re newing up the connection.

Once you have a handle to the Queue service, you can call ListQueues. This doesn’t just return a list of strings, as you might expect, but instead returns a collection of queue objects. Each queue object represents a queue in your account and is fully usable. The equivalent call to get a list of queues in REST would be like the following code. You can see that it’s a simple GET.

GET http://hsslog.queue.core.windows.net/?comp=list&maxresults=50&timeout=30

					  

If you don’t have any queues, you’ll get back an empty collection. In this case, your next step would be to create a queue.

2. Creating a queue

Once you’re connected to the queue service you can create a queue with the queue client. You do this by creating a reference to the queue, even if the queue doesn’t exist yet. Then you can create the queue using the reference as a control point:

CloudQueue q = Qsvc.GetQueueReference("newordersqueue");
q.CreateIfNotExist();

In the preceding code, we first create a CloudQueue object. This is an empty object, and this line doesn’t actually connect to the service. It’s merely an empty handle that doesn’t point to anything. Then the CreateIfNotExist method is called on the queue object. This will check if a queue with that name exists, and if it doesn’t, it’ll create one. This is very handy.

You can check whether a queue exists before you try to create it by using q.Does-QueueExist. This method will return a Boolean value telling you whether the queue exists or not.

Your next step is to attach some metadata to the queue.

3. Attaching metadata

You can store up to 8 KB of data in the property bag for each queue. You might want to use this to track some core data about the queue, or perhaps some core metrics on how often it should be polled. To work with the metadata, use the following code:

CloudQueue q = Qsvc.GetQueueReference("newordersqueue");
q.Metadata.Add("ProjectName", "ElectronReintroductionPhasing");
q.Metadata.Remove("BadKeyNoDoughnut");
q.SetMetadata();

The metadata for a queue is attached as a property on the CloudQueue object. You work with it like any other name value collection. In this code, we first add a new entry to the metadata called ProjectName, with a value of ElectronReintroductionPhasing. But this new entry won’t be saved back to the queue service until we call SetMetaData, which connects to the service and uploads the metadata for the queue in the cloud.

You can remove existing properties from the bag if you no longer need them. In this example, the Remove method removes BadKeyNoDoughnut from use. When you remove an item from the metadata collection, you must follow that with a SetMetaData call to persist the changes to the cloud.

In our queue example application, we’ve set some metadata properties, namely RefreshInterval and BackOffPace. You can see how we set and fetch these in figure 2.

Figure 2. Displaying the metadata set on a queue. You can attach up to 8 KB of metadata to a queue. This can help in managing the queue, such as by specifying what the backoff pace rate should be.

Now that you’ve created a queue and set its metadata, let’s look at how you can delete a queue. On occasion, you’ll want to dynamically create and destroy queues.

4. Deleting a queue

It’s good practice to clear a queue before you delete it. This removes all of the messages from the queue. The clear queue method is handy for resetting a system or clearing out poison messages that may have stopped up the flow.

Deleting a queue is as simple as this, when using the client library:

CloudQueue q = Qsvc.GetQueueReference("newordersqueue");
q.Clear();
q.Delete();

The equivalent REST call would be as follows:

DELETE http://hsslog.queue.core.windows.net/newordersqueue?timeout=30

Being able to create and destroy queues in a single line of code makes them simple objects to work with. In the past, using a queue in your system would require days, if not weeks, of installing several queue servers (for redundancy purposes). They would also require a lot of care and feeding. Queues in the cloud are much easier to work with and don’t require any grooming or maintenance. But the real power of queues is in the messages that flow through them, which we’ll delve into in the next section.