Queues – Azure Storage Client v1.0

Azure Queues provided a convenient and simple section to investigate in the new Azure Storage Client v1.0. The funtionality is provided in three classes:

• CloudQueue
• CloudQueueClient
• CloudQueueMessage

The CloudQueue class represents a Windows Azure queue. The CloudQueueClient class provides access to the Azure Queue service – and I’m not really convinced yet that the class is well named. The CloudQueueMessage class represents a queue message.

CloudQueueClient

The CloudQueueClient class is declared:

public class CloudQueueClient {
    // Constructors
    public CloudQueueClient(Uri baseAddressUri, StorageCredentials credentials);
    public CloudQueueClient(String baseAddress, StorageCredentials credentials);

    // Events
    public event EventHandler<ResponseReceivedEventArgs> ResponseReceived;

    // Properties
    public TimeSpan ApproximateMessageCountCacheLength { get; set; }
    public StorageCredentials Credentials { get; }
    public RetryPolicy RetryPolicy { get; set; }
    public TimeSpan Timeout { get; set; }
    public Boolean UsePathStyleUris { get; }

    // Methods
    public IAsyncResult BeginListQueuesSegmented(String prefix, AsyncCallback callback, Object state);
    public IAsyncResult BeginListQueuesSegmented(String prefix, QueueListingDetails detailsIncluded, AsyncCallback callback, Object state);
    public ResultSegment<CloudQueue> EndListQueuesSegmented(IAsyncResult asyncResult);
    public CloudQueue GetQueueReference(String queueAddress);
    public IEnumerable<CloudQueue> ListQueues(String prefix, QueueListingDetails detailsIncluded);
    public IEnumerable<CloudQueue> ListQueues();
    public IEnumerable<CloudQueue> ListQueues(String prefix);
}

Although the class has a couple of constructors, a CloudQueueClient object is more easily created using the CreateCloudQueueClient() extension method from the CloudStorageAccountStorageClientExtensions class:

public static class CloudStorageAccountStorageClientExtensions {
    // Methods
    public static CloudBlobClient CreateCloudBlobClient(CloudStorageAccount account);
    public static CloudQueueClient CreateCloudQueueClient(CloudStorageAccount account);
    public static CloudTableClient CreateCloudTableClient(CloudStorageAccount account);
}

For example:

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.FromConfigurationSetting(“DataConnectionString”);
CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();

If the Configurations Settings Publisher has been set correctly, as mentioned in a previous post, the account information and Azure Storage Service endpoint will be taken from the Azure Service configuration file.

An important CloudStorageClient method is GetQueueReference() which returns a CloudQueue object with the specified queue name. This CloudQueue object can then be used for any operations on the queue.

CloudQueue

The CloudQueue class has many members allowing operations including: create queue, delete queue, add message, get message, delete message, peek message, etc. These all come in both synchronous and asynchronous form. The following methods support adding messages to a queue:

public void AddMessage(CloudQueueMessage message, TimeSpan timeToLive);
public void AddMessage(CloudQueueMessage message);
public IAsyncResult BeginAddMessage(CloudQueueMessage message, TimeSpan timeToLive, AsyncCallback callback, Object state);
public IAsyncResult BeginAddMessage(CloudQueueMessage message, AsyncCallback callback, Object state);
public void EndAddMessage(IAsyncResult asyncResult);

The following methods support the retrieval of one or more messages from the queue:

public IAsyncResult BeginGetMessage(AsyncCallback callback, Object state);
public IAsyncResult BeginGetMessage(TimeSpan visibilityTimeout, AsyncCallback callback, Object state);
public IAsyncResult BeginGetMessages(Int32 messageCount, AsyncCallback callback, Object state);
public IAsyncResult BeginGetMessages(Int32 messageCount, TimeSpan visibilityTimeout, AsyncCallback

public CloudQueueMessage EndGetMessage(IAsyncResult asyncResult);
public IEnumerable<CloudQueueMessage> EndGetMessages(IAsyncResult asyncResult);

public CloudQueueMessage GetMessage();
public CloudQueueMessage GetMessage(TimeSpan visibilityTimeout);
public IEnumerable<CloudQueueMessage> GetMessages(Int32 messageCount);
public IEnumerable<CloudQueueMessage> GetMessages(Int32 messageCount, TimeSpan visibilityTimeout);

A call to GetMessage() or GetMessages() is not a blocking call – that is it returns immediately either with a message if there is one on the queue or null if there is not.

 

CloudQueueMessage

The CloudQueueMessage class has the following members supporting the creation of and access to messages.

public class CloudQueueMessage {
    // Fields
    public static readonly Int64 MaxMessageSize;
    public static readonly Int32 MaxNumberOfMessagesToPeek;
    public static readonly TimeSpan MaxTimeToLive;

    // Constructors
    public CloudQueueMessage(String content);
    public CloudQueueMessage(Byte[] content);

    // Properties
    public Byte[] AsBytes { get; }
    public String AsString { get; }
    public Nullable<DateTime> ExpirationTime { get; }
    public String Id { get; }
    public Nullable<DateTime> InsertionTime { get; }
    public Nullable<DateTime> NextVisibleTime { get; }
    public String PopReceipt { get; }
}

A CloudQueueMessage instance can be created with a message content that is either a String or a Byte array. In both cases, the message content will be Base64 encoded before the message is sent to the Queue Service.

Note that PopReceipt is null for a CloudQueueMessage object created in response to CloudQueue.PeekMessage() or one of its variations. This is the correct behavior. However, an attempt to delete this message from the queue using CloudQueue.DeleteMessage() leads to a PopReceipt is null error rather than a more direct expression of the problem.

Example: Create Queue

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.FromConfigurationSetting(“DataConnectionString”);
CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();
CloudQueue cloudQueue = cloudQueueClient.GetQueueReference(queueName);
cloudQueue.CreateIfNotExist();

CreateIfNotExist() uses functionality from the Create Queue operation in the Azure Queue REST API whereby the Queue Service verifies whether the queue name already exists with identical metadata to the current request. If so it does not create the queue and returns a 204 (No content) rather than a 409 (Conflict) error. This means that it is not necessary to check non-existence of the queue before the queue is created.

Example: Add Message

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.FromConfigurationSetting(“DataConnectionString”);
CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();
CloudQueue cloudQueue = cloudQueueClient.GetQueueReference(queueName);
CloudQueueMessage cloudQueueMessage = new CloudQueueMessage(messageText);
cloudQueue.AddMessage(cloudQueueMessage);

This led to the following HTTP request

POST /testqueue/messages?timeout=90 HTTP/1.1
x-ms-version: 2009-09-19
x-ms-date: Sun, 15 Nov 2009 07:20:33 GMT
Authorization: SharedKey myaccount:6BONgnjiEp4UQfGOtEqJryJMVhAf1U+Y95aNNBFiNVA=
Host: myaccount.queue.core.windows.net
Content-Length: 125
Connection: Keep-Alive

<?xml version=”1.0″ encoding=”utf-8″?><QueueMessage><MessageText>QmF0dGxlc3RhciBHYWxsYWN0aWNh</MessageText></QueueMessage>

where testqueue was the name of the queue. The actual message content was Battlestar Gallactica which was automatically Base64 encoded to QmF0dGxlc3RhciBHYWxsYWN0aWNh.

The HTTP response was:

HTTP/1.1 201 Created
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: e45d68d7-a3a6-4ace-ad48-feed30859b54
x-ms-version: 2009-09-19
Date: Sun, 15 Nov 2009 07:20:19 GMT
Content-Length: 0

Example: Get Message

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.FromConfigurationSetting(“DataConnectionString”);
CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();
CloudQueue cloudQueue = cloudQueueClient.GetQueueReference(queueName);

CloudQueueMessage cloudQueueMessage = cloudQueue.GetMessage();
String messageText = cloudQueueMessage.AsString;

cloudQueue.DeleteMessage(cloudQueueMessage);

This also deletes the message from the queue once it has been read.

Example: Using Account Name and Key Directly

This example shows the account name and key being used directly rather than retrieved from the configuration file:

StorageCredentialsAccountAndKey storageCredentialsAccountAndKey = new StorageCredentialsAccountAndKey(“ACCOUNT_NAME”, “ACCOUNT_KEY”);

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.DevelopmentStorageAccount;
CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();
CloudQueue cloudQueue = cloudQueueClient.GetQueueReference(queueName);
cloudQueue.CreateIfNotExist();

The example creates a queue.

Example: Using Development Storage Directly

This example shows development storage being used directly rather than using the account name and key retrieved from the configuration file:

CloudStorageAccount cloudStorageAccount = CloudStorageAccount.DevelopmentStorageAccount;

CloudQueueClient cloudQueueClient = cloudStorageAccount.CreateCloudQueueClient();
CloudQueue cloudQueue = cloudQueueClient.GetQueueReference(queueName);
cloudQueue.CreateIfNotExist();

The example creates a queue.

UPDATE 11/24/2009

Added material on GetMessage() to the CloudQueue section.