A Windows Azure storage account encompasses the Blob, Queue, and Table services. The URI scheme for accessing the Queue service via your storage account is

<http|https>://<account name>.queue.core.windows.net

where <account name> is the unique name you created for your storage account. The <account name> must be globally unique.

For example, the Queue service for the storage account that I created in the previous chapter can be referenced as

<http|https>://proazurestorage.queue.core.windows.net

A queue is a logical destination for sending messages. There can be any number of queues in an account in the Queue service. A queue stores messages and makes them available to applications via the REST API. Queues can have metadata in the form of name-value pairs up to 8KB in size per queue. The Queue service support only private access; that means you need to have account privileges in order to access queues in a Queue service.

You can access a queue using the URI

<http|https>://<account name>.queue.core.windows.net/<queue name>

where <queue name> is the name of the queue you want to access.

For example, if you create a queue named logsqueue in the proazurestorage account, you can reference it using the following URI:

<http|https>://proazurestorage.queue.core.windows.net/logsqueue

The naming constraints for a queue are as follows:^[7]

If a queue name or the URI violates the naming convention, an HTTP status code 400 (Bad Request) is returned by the server.

Messages are stored in queues. There is no limit to the number of messages that can be stored in a queue, but the size of each individual message can't exceed 8KB. To communicate large object messages, you can put the large object in a blob and then send the URI of that object as a message to a queue.

When you send a message, it can be in either text or binary format; but when you receive a message from the queue, it's always in Base64-encoded format. A GUID MessageID assigned by the Queue service uniquely identifies a message in the queue.

A message has the following attributes:

You can access messages in a queue using the following URI

<http|https>://<account name>.queue.core.windows.net/<queue name>/messages

where <queue name> is the unique name of the queue within the scope of the account specified in the URI, and messages is a constant string representing all the messages in the specified queue. For example, if you create a queue named logsqueue, you can get messages from it by calling the following URI:

<http|https>://proazurestorage.queue.core.windows.net/logsqueue/messages

The Queue service REST API's HTTP request components are described in the following sections.

PUT http://proazurestorage.queue.core.windows.net/logsqueue

GET http://proazurestorage.queue.core.windows.net/?comp=list

Authorization="[SharedKey|SharedKeyLite] <Account Name>:<Signature>"

PUT /myfirstazurequeue?comp=metadata&timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 04:33:45 GMT
x-ms-meta-createdBy: tejaswi
x-ms-meta-creationDate: 6/16/2009
Authorization: SharedKey proazurestorage:
     spPPnadPYnH6AJguuYT9wP1GLXmCjn0I1S6W2+hzyMc=
     Host: proazurestorage.queue.core.windows.net
Content-Length: 0

The HTTP response of the Queue service API typically includes the following components.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: ccf3c21c-7cca-4386-a636-7f0087002970
Date: Tue, 16 Jun 2009 04:47:54 GMT

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults AccountName="http://proazurestorage.queue.core.windows.net/">
<MaxResults>50</MaxResults>
<Queues>
<Queue>
<QueueName>testq</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq</Url>
</Queue>
<Queue>
<QueueName>testq1</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq1</Url>
</Queue>
<Queue>
<QueueName>testq2</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq2</Url>
</Queue>
<Queue>
<QueueName>testq3</QueueName>
<Url>http://proazurestorage.queue.core.windows.net/testq3</Url>
</Queue>
</Queues>
<NextMarker />
</EnumerationResults>

Even though the REST API and the operations in the REST API are easily readable, the API doesn't automatically create client stubs like the ones created by WDSL-based web services. You have to create your own client API and stubs for REST API operations. This makes the client programming more complex and increases the barrier to entry for developers. To reduce this barrier to entry, the Windows Azure SDK team has created two client helper libraries: Microsoft.WindowsAzure.StorageClient from Windows Azure SDK, and the Storage Client code sample. Both libraries are used to invoke REST APIs of the Windows Azure Storage service. The Microsoft.WindowsAzure.StorageClient library abstracts this by providing a closed-source interface and therefore is less interesting to developers who want to see the inner workings of the method calls.

In the Windows Azure CTP version, a code sample named Storage Client became the choice of developers for calling storage services because the Microsoft.WindowsAzure.StorageClient wasn't available and also because it was open source. It provided good insight into building your own storage client library. The Storage Client made it easier to see the end-to-end method calls to the Storage service. This chapter uses the Storage Client code sample in sample applications and covers the class structure and calling mechanisms in the Microsoft.WindowsAzure.StorageClient namespace.

The following sections cover the queue storage APIs from Microsoft.WindowsAzure.StorageClient and the Storage Client code sample.

Windows Azure Storage Client Queue API

The Microsoft.WindowsAzure.StorageClient namespace consists of classes representing the entire queue hierarchy. Figure 5-3 illustrates the core classes for programming Queue service applications.

Figure 5.3. Queue class hierarchy

As shown in Figure 5-3, four core classes are required for queue operations. Table 5-1 lists these classes and a short description of each of them.

Tip

The Windows Azure Storage Client API is the recommended method for programming Storage service applications. The API provides synchronous as well as asynchronous methods for interacting with the Storage service REST API.

Table 5.1. Classes for the Queue Service

Class Name	Description
CloudStorageAccount	A helper class for retrieving account information from the configuration file or creating an instance of the storage account object from account parameters.
CloudQueueClient	A wrapper class for getting references to the core queue objects. The class consists of methods like GetQueueReference() and ListQueues().
CloudQueue	Consists of queue operations like Create(), Delete(), AddMessage(), and GetMessage().
CloudQueueMessage	Represents a queue message with properties like InsertionTime, ExpirationTime, NextVisibleTime, Id, and PopReceipt.

In addition to these core classes, classes like QueueAttributes and QueueErrorCodeStrings represent more details about the queue.

The steps for programming simple queue applications with the queue classes listed in Table 5-1 are as follows:

1. Add the following using statement to your C# class:

   using Microsoft.WindowsAzure.StorageClient;

2. Instantiate the CloudStorageAccount class from the configuration file:

   CloudStorageAccount  storageAccountInfo =
   CloudStorageAccount.FromConfigurationSetting(configurationSettingName);

   Or, instantiate the CloudStorageAccount class using account information:

   CloudStorageAccount  storageAccountInfo = new CloudStorageAccount(new
   StorageCredentialsAccountAndKey(accountName, accountKey), new Uri
   (blobEndpointURI), new
   Uri(queueEndpointURI), new Uri(tableEndpointURI));

3. Create an instance of CloudQueueClient:

   CloudQueueClient queueStorageType = storageAccountInfo. CreateCloudQueueClient ();

When you have an instance of the CloudQueueClient class, you can execute operations on the queue storage service as follows:

• List queues:

  IEnumerable<CloudQueue> queues = queueStorageType.ListQueues();
  Create Queue
  queueStorageType.GetQueueReference(queueName).Create();
  Delete Queue
  queueStorageType.GetQueueReference(queueName).Delete();

• Add a message:

  public void AddMessage(string queueName, CloudQueueMessage queueMessage)
  {
  queueStorageType.GetQueueReference(queueName).AddMessage(queueMessage);
  }

• Get messages:

  queueStorageType.GetQueueReference(queueName).GetMessages
  (numberofMessages, TimeSpan.FromSeconds(visibilityTimeoutInSecs));

• Peek messages:

  queueStorageType.GetQueueReference(queueName).PeekMessages(numberofMessages);

• Delete a message:

  public void DeleteMessage(string queueName, CloudQueueMessage queueMessage)
  {
  queueStorageType.GetQueueReference(queueName).DeleteMessage(queueMessage);
  }

• Set queue metadata:

  public void SetQueueMetadata(string queueName, NameValueCollection queueProps)
  {
  
  CloudQueue queue = queueStorageType.GetQueueReference(queueName);
  queue.Attributes.Metadata = queueProps;
  queue.SetMetadata();
  }

  The call to SetMetadata() method calls the method on the queue service API in the cloud.

Storage Client Code Sample Queue API

The Storage Client project consists of five important classes in the context of the Queue service. Table 5-2 lists these classes and a short description of each of them.

Table 5.2. Storage Client classes for the Queue Service

Class Name	Description
StorageAccountInfo	A helper class for retrieving account information from the configuration file.
QueueStorage	An abstract class that has properties and methods at the account level of the Queue service hierarchy. It has an AccountName property and the method ListQueues().
QueueStorageRest	A class that extends the QueueStorage class and implements the abstract methods. This class also has a nested class ListQueueResult, representing the results returned by the Queue service.
MessageQueue	An abstract class with signatures for the queue and message operations. Some example method calls are CreateQueue(), PutMessage(), and GetMessages().
QueueRest	A class that extends the MessageQueue class and implements the abstract methods.

Figure 5-4 illustrates the five classes listed in Table 5-2 and the relationships between them.

Figure 5.4. StorageClient classes for the Queue service

Following are some of the typical steps required to interact with the Queue service using Storage Client classes.

1. Add your account information in the <appSettings> section of your application configuration file (app.config or web.config):

   <add key = "AccountName" value="[Your Account Name]"/>
   <add key = "AccountSharedKey"
   value="[Your Account Shared Key from the Developer Portal]"/>

   To work with local storage, add "devstoreaccount1" as the AccountName and "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==" as the shared key.

2. Add the Queue service endpoint URI in the appSettings section of your application configuration file:

   <add key="QueueStorageEndpoint" value="http://blob.core.windows.net"/>

   To work with local storage, add the URI of the local Queue service resource, http://127.0.0.1:10001.

3. Create an instance of the StorageAccountInfo class from the configuration information you entered in the configuration file:

   StorageAccountInfo account =
   StorageAccountInfo.GetDefaultQueueStorageAccountFromConfiguration();

4. Create an instance of the QueueStorage class based on the account object:

   QueueStorage queueStorage = QueueStorage.Create(account);

5. Call the ListQueues() method on the queueStorage object to get a list of all the queues in the account:

   queueStorage.ListQueues();

6. To access a particular queue, call

   MessageQueue messageQueue = queueStorage.GetQueue(queueName);

   When you have a reference to the message queue object, then you can call not only queue methods like CreateQueue(), DeleteQueue(), and ListQueues(), but also message functions like PutMessage(), GetMessages(), and DeleteMessage().

In the next few sections, you learn how to call some of these functions at every level of the Queue service hierarchy.

The Create Queue operation creates a queue in a storage account. The URI for the Create Queue operation is of the format account name>.queue.core.windows.net/<queue name>. You can think of Queue as a message queuing system in the cloud. For example, if you want to send and receive messages across diverse applications in different domains, Windows Azure Queue may fit your requirement. Because of its standard REST interface and Internet scale, you can send and receive queue messages anywhere, anytime, and in any programming language that supports Internet programming. The Create Queue REST request looks like Listing 5-8.

PUT /myfirstazurequeue?timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 03:16:12 GMT
Authorization: SharedKey proazurestorage:a0EQSlfMdXfFrP/wwdfCUVqMYiv4PjXesF0Jp4d71DA=
Host: proazurestorage.queue.core.windows.net
Content-Length: 0

Listing 5-8 shows the request for creating a queue named myfirstazurequeue. The PUT HTTP verb instructs the Queue service to create a queue. There is no metadata information for the queue, so the queue is created without any metadata. You can add x-ms-meta-[name]:[value] to the header to create metadata values. For the Create Queue operation, the Queue service responds with a status code of HTTP/1.1 201 Created, or HTTP/1.1 409 Conflict if a queue with the same name already exists. The Create Queue response is shown in Listing 5-9.

HTTP/1.1 201 Created
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 8b4d45c8-2b5d-46b8-8e14-90b0d902db80
Date: Wed, 17 Jun 2009 03:17:57 GMT
Content-Length: 0

In Listing 5-9, the first line represents the status code of the operation. The x-ms-request-id represents a unique request identifier that can be used for debugging or tracing.

Figure 5-8 shows the working of the Create Queue operation in the Windows Azure Storage Operations application.

Figure 5.8. Create Queue from Windows Azure Storage Operations.exe

As shown in Figure 5-8, to create a queue, you need to do the following:

To help you understand the programming model of the Create Queue operation, open the Visual Studio Solution Chapter4.sln from the Chapter 4 source directory. The WindowsAzureStorageHelper class in the ProAzureCommonLib contains a helper function called CreateQueue, as shown in Listing 5-10.

public bool CreateQueue(string queueName, out bool alreadyExists)
{
alreadyExists = false;
MessageQueue q = QueueStorageType.GetQueue(queueName);

return q.CreateQueue(out alreadyExists);
}

As shown in Listing 5-10, the CreateQueue() method calls the GetQueue() method to get a reference to the MessageQueue object. The MessageQueue object is a local instance of the Queue object. This instance doesn't create a queue when you instantiate it. To create a queue, you have to call the CreateQueue() method on the MessageQueue object. The MessageQueue object is used by the StorageClient to create accurate URI and metadata headers and send them to the Queue service. Figure 5-9 illustrates the sequence of method calls across different objects and assemblies for the Create Queue operation.

Figure 5.9. Create Queue sequence diagram

As shown in Figure 5-9, the Windows Azure Storage Operations application calls the CreateQueue() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the CreateQueue() method on the MessageQueue object. The CreateQueue() method creates the REST message and sends it synchronously to the Windows Azure Queue service to create the queue. It uses the System.Net.HttpWebRequest to send the REST message over HTTP. Upon success or failure of the operation, the Windows Azure Queue service returns an HTTP status code: HTTP/1.1 201 for success or HTTP/1.1 409 for conflict or failure. The CreateQueue() method translates the HTTP status code into true for success and false for failure or conflict. The Boolean value is passed all the way to the Windows Azure Storage Operations application as a return parameter of the CreateQueue() method.

Queues can contain name-value pairs of metadata values. You can store values like the time of creation, creator, last modified by user, and so on in the metadata fields of a container. The size of the metadata can be 8KB per queue. The Set Queue Metadata operation sets the metadata of a queue independently. The URI for the Set Queue Metadata operation is of the format account name>.queue.core.windows.net/<queue name>?comp=metadata. The Set Queue Metadata REST request looks like Listing 5-11.

PUT /myfirstazurequeue?comp=metadata&timeout=30 HTTP/1.1
x-ms-date: Wed, 17 Jun 2009 04:33:45 GMT
x-ms-meta-createdBy: tejaswi
x-ms-meta-creationDate: 6/16/2009
Authorization: SharedKey proazurestorage:spPPnadPYnH6AJguuYT9wP1GLXmCjn0I1S6W2+hzyMc=
Host: proazurestorage.queue.core.windows.net
Content-Length: 0

In Listing 5-11, the HTTP verb used is PUT, and the URI parameter is ?comp=metadata. This parameter instructs the Queue service to set the queue metadata instead of creating the queue. The Create Queue operation doesn't have this parameter. The x-ms-meta.[name]:[value] entries represent the metadata name-value pairs you want to set on the queue.

Figure 5-10 illustrates how to execute the Set Queue Metadata operation in Windows Azure Storage Operations application.

Figure 5.10. Set Queue Metadata in the Windows Azure Storage Operations application

As shown in Figure 5-10, to execute the Set Queue Metadata operation, you do the following:

To help you understand the programming model of the Set Queue Metadata operation, open the Visual Studio Solution Chapter4.sln from the Chapter 4 source directory. The WindowsAzureStorageHelper class in the ProAzureCommonLib contains a helper function called SetQueueProperties(), as shown in Listing 5-12.

public bool SetQueueProperties(string queueName, QueueProperties queueProps)
{
MessageQueue q = QueueStorageType.GetQueue(queueName);

return q.SetProperties(queueProps);
}

In Listing 5-12, the SetQueueProperties() method accepts the name of the queue and a QueueProperties object populated with metadata name-value pairs. The QueueProperties class has a property Metadata of type System.Collections.Specialized.NameValueCollection, which represents the metadata name-value pairs. The queue name is used to create a local instance of the MessageQueue object. The code then calls the SetProperties() method on the MessageQueue object to set the metadata values for the queue. If the metadata is set successfully, a Boolean value of true is returned back to the caller; otherwise, a false value is returned. Figure 5-11 illustrates the sequence of method calls across different objects and assemblies for the Set Queue Metadata operation.

Figure 5.11. Set Queue Metadata sequence diagram

As shown in Figure 5-11, the Windows Azure Storage Operations application calls the SetQueueProperties() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the SetProperties() method on the MessageQueue object. The SetProperties() method creates the REST message and sends it synchronously to the Windows Azure Queue service to set the queue metadata values. It uses the System.Net.HttpWebRequest to send the REST message over HTTP. Upon success or failure of the operation, the Windows Azure Queue service returns an HTTP status code: HTTP/1.1 200 for success or HTTP/1.1 204 (No content). The SetProperties() method translates the HTTP status code into true for success and false for failure. The Boolean value is passed all the way to the Windows Azure Storage Operations application as a return parameter of the SetQueueProperties() method.

The Put Message operation en-queues (puts) a message at the end of the queue. The URI of a Put Message operation is of the format account name>.queue.core.windows.net/<queue name>/messages. You can send a message with size up to 8KB. To send larger files, you can save the message as a blob and send the URI of the blob to the queue. The body of the message while sending can be text or binary, but it should support inclusion in an XML body with UTF-8 encoding. This is because a message received from the queue is always returned in Base64-encoded format within an XML response body. You see this in the Get Messages operation. The URI for the Put Message operation supports an additional optional parameter, listed in Table 5-10.

The Put Message REST request looks like Listing 5-13.

POST /myfirstazurequeue/messages?messagettl=120&timeout=30 HTTP/1.1
x-ms-date: Thu, 18 Jun 2009 05:52:00 GMT
Authorization: SharedKey proazurestorage:Ahv5yhR9xOrHiMTnq3fBcaBKL8KeUFQ3r
Host: proazurestorage.queue.core.windows.net
Content-Length: 84
Expect: 100-continue

<QueueMessage>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>

In Listing 5-13, a string message "myfirstazuremessage" is sent to the queue named myfirstazurequeue. The time-to-live seconds for the message is 120, which means if the message isn't received or deleted by an application within 120 seconds in the queue, the message will be marked for deletion and won't be visible to any applications. The request body consists of the message content wrapped in the <QueueMessage> element. Note that the content of the message within the <MessageText /> element is in Base64-encoded format. Listing 5-14 shows the response from the Queue service.

HTTP/1.1 201 Created
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: e724cc82-3d21-4253-9317-3b3964374be7
Date: Thu, 18 Jun 2009 05:53:32 GMT
Content-Length: 0

As shown in Listing 5-14, the Queue service responds with an HTTP/1.1 201 Created status code for a successful Put Message operation. Figure 5-12 shows the working of the Put Message operation in the Windows Azure Storage Operations application.

Figure 5.12. Put Message in Windows Azure Storage Operations.exe

As illustrated in Figure 5-12, you can send a text message using the Windows Azure Storage Operations application. The steps for sending a message to a queue are as follows:

To help you understand the programming model of the Put Message operation, open the Visual Studio Solution Chapter4.sln from the Chapter 4 source directory. The WindowsAzureStorage.cs file in the Windows Azure Storage Operations project consists of a PutMessage() method, as shown in Listing 5-15.

private void PutMessage()
        {
            string messageBody = string.Empty;
            if (txtMessageBody.Text.Length > 0)
            {
                messageBody = txtMessageBody.Text;

            }
            else
            {
                messageBody = String.Format
("Message from Windows Azure Storage Operations",
System.Guid.NewGuid().ToString("N"));
            }
            int ttlsecs = 300;
            if(txtTimeTolive.Text.Length > 0)
            {
                ttlsecs = int.Parse(txtTimeTolive.Text);
            }
            if (StorageHelper.PutMessage(txtQueueName.Text, new
 Microsoft.Samples.ServiceHosting.StorageClient.Message(messageBody), ttlsecs))
            {
                statusLabel.Text = String.Format
("Message {0} sent successfully to queue {1}", messageBody, txtQueueName.Text);

            }
        }

As shown in Listing 5-15, the PutMessage() method calls the PutMessage() operation on the WindowsAzureStorageHelper (StorageHelper object). The message body and the time-to-live values are parsed appropriately from the server controls and passed as parameters to the method. If you don't enter a message in the Message Body text box, the application automatically creates a default message for you. Figure 5-13 shows the sequence of Put Message operation from the application to the Queue service as it passes through various assemblies and objects.

Figure 5.13. Put Message sequence diagram

As shown in Figure 5-13, the Windows Azure Storage Operations application calls the PutMessage() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the PutMessage() method on the MessageQueue object. The PutMessage() method of the MessageQueue object creates the REST message request and sends it synchronously to the Queue service. It uses the System.Net.HttpWebRequest to send the REST message over HTTP. Upon the success of the operation, the Queue service returns an HTTP status code: HTTP/1.1 201 Created. The PutMessage() method translates the HTTP code into true for success and false for failure. The Boolean value is passed all the way to the Windows Azure Storage Operations application as a return parameter of the PutMessage() method.

In the previous section, you learned to send messages to queues in the Queue service. In this section, you learn to retrieve these messages using the Get Messages operation. The URI for the Get Messages operation is of the format account name>.queue.core.windows.net/<queue name>/messages. The URI for the Get Messages operation supports additional optional parameters, as listed in Table 5-11.

Listing 5-16 shows the REST API request for the Get Messages operation.

GET /myfirstazurequeue/messages?numofmessages=10&visibilitytimeout=60&timeout=30_
 HTTP/1.1
x-ms-date: Thu, 18 Jun 2009 05:34:13 GMT
Authorization: SharedKey proazurestorage:qB9P717GTC6nd6rX4Ed16r6QkxO2QwJxLcr
Host: proazurestorage.queue.core.windows.net

In Listing 5-16, the URI points to the myfirstazurequeue queue. numofmessages=10 instructs the Queue service to retrieve only 10 messages. visibilitytimeout=60 instructs the Queue service to make the retrieved messages invisible to other applications for 60 seconds, unless the receiving application deletes them. Listing 5-17 shows the REST API response from the Queue service for the Get Messages operation.

HTTP/1.1 200 OK
Content-Type: application/xml
Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: c10542ae-fa9e-45fd-b036-3f0b77ed611e
Date: Thu, 18 Jun 2009 05:35:43 GMT
Content-Length: 3900

<?xml version="1.0" encoding="utf-8"?>
<QueueMessagesList>

<QueueMessage>
<MessageId>ba16723c-8b4c-48dd-9d80-d5d2731bcbd8</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
<QueueMessage>
<MessageId>c0d92c72-2f9f-4c15-a177-7cf988c2532d</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
<QueueMessage>
<MessageId>f3ae9ccd-b97c-4bae-bc22-744cadd2c9c0</MessageId>
<InsertionTime>Thu, 18 Jun 2009 05:36:43 GMT</InsertionTime>
<ExpirationTime>Thu, 18 Jun 2009 05:37:28 GMT</ExpirationTime>
<PopReceipt>AgAAAAEAAAAAAAAAIBeHw9bvyQE=</PopReceipt>
<TimeNextVisible>Thu, 18 Jun 2009 05:36:43 GMT</TimeNextVisible>
<MessageText>bXlmaXJzdGF6dXJlbWVzc2FnZQ==</MessageText>
</QueueMessage>
</QueueMessagesList>

Listing 5-17 shows the HTTP header and body of the Get Messages operation response. For the sake of brevity, only three messages are shown. The HTTP response body consists of a list of messages in XML format. Every <QueueMessage /> element represents a message. When you retrieve a message, the MessageId and the PopReceipt properties of the message are important for deletion purposes. The recommended pattern is to receive the message, process it, and then delete it before it becomes visible to other applications when the visibilitytimeout period expires. The TimeNextVisible value specifies the expiration time of the visibilitytimeout period. The ExpirationTime specifies the time when the message will be marked for deletion if not retrieved and/or deleted by a receiving application. This value was set when the message was sent to the queue. Figure 5-14 shows the working of the Get Messages operation in the Windows Azure Storage Operations.exe application.

Figure 5.14. Get Messages in the Windows Azure Storage Operations application

As illustrated in Figure 5-14, you can use the Get Messages operation for a queue using the Windows Azure Storage Operations application. The steps for retrieving messages are as follows:

The retrieved messages are populated in the DataGridView control in the Messages section. Each message is represented by a row in the DataGridView control. The control displays all the properties of the retrieved messages. To delete a message, select a row in the DataGridView and press the Delete button on your keyboard.

To help you understand the programming model of the Get Messages operation, open the Visual Studio Solution Chapter4.sln from the Chapter 4 source directory. The WindowsAzureStorage.cs file in the Windows Azure Storage Operations project consists of a GetMessages() method, as shown in Listing 5-18.

private void GetMessages()
{
dgvMessages.Rows.Clear();
IEnumerable<Microsoft.Samples.ServiceHosting.StorageClient.Message>
 msgs = StorageHelper.GetMessages(txtQueueName.Text, int.Parse(txtNumberOf
Messages.Text), int.Parse(txtVisibilityTimeoutSecs.Text));

if (msgs != null)
{
IList<Microsoft.Samples.ServiceHosting.StorageClient.Message> messages =
new List<Microsoft.Samples.ServiceHosting.StorageClient.Message>(msgs);
PopulateMessagesDataGridView(messages);

}
}

As shown in Listing 5-18, the GetMessages() method calls the GetMessages() method of WindowsAzureStorageHelper (StorageHelper object). The numofmessages and visibilitytimeout parameters are parsed appropriately into integer values and passed as parameters to the GetMessages() method. The returned messages are then packaged into a list and passed to the PopulateMessagedataGridView() method for display. Figure 5-15 illustrates the sequence diagram for the Get Messages operation.

Figure 5.15. Get Messages sequence diagram

As shown in Figure 5-15, the Windows Azure Storage Operations application calls the GetMessages() method on the WindowsStorageHelper object in the ProAzureCommonLib.dll. The WindowsStorageHelper object calls the GetQueue() method on the QueueStorage object to get an instance of the MessageQueue object. The WindowsStorageHelper object then calls the GetMessages() method on the MessageQueue object. The MessageQueue object calls a private method InternalGet() to retrieve the messages from the specified queue. The body of the HTTP response contains messages in XML format. The XML contents are parsed and packaged into an IEnumerable<Message> collection and passed as a return parameter to the GetMessages() operation. Finally, the Windows Azure Storage Operations application displays these messages in a DataGridView control, as shown earlier in this section.

Consider a scenario in which you're designing an ecommerce web application in Windows Azure with a Web Role front end and several Worker Roles for back-end processing work. The Web Role instances continuously send purchase order information to the Worker Roles for order processing. In this scenario, you can use the Windows Azure Queue service to queue purchase order messages for the Worker Roles, as shown in Figure 5-16.

Figure 5.16. Web Role/Worker Role communication using the Queue service

In Figure 5-16, Web Role instances 1 and 2 send orders to the order-processing queue. Worker Roles 1 and 2 dequeue the order messages and process the orders. Because not all orders have to be processed immediately, Worker Roles can pick up from the queue only the orders that are ready to be processed. This way, you can create an effective message communication system between Web Roles and Worker Roles, taking advantage of the scalable and highly available Queue service infrastructure. If the order message size exceeds 8KB, you can store the message body in the Blob service and pass a link to the blob as a queue message, as shown in Figure 5-16. When the Worker Role dequeues the message, it can retrieve the contents of the order from the Blob service.

Continuing Scenario 1, depending on the volume of messages, you can either adjust the number of queues or the number of instances of Worker Roles for processing orders. For example, if you identify during your testing phase that one Worker Role can process only ten orders at a time, you can configure Worker Roles to pick up only ten messages from the queue. If the number of messages in the queue keeps increasing beyond the number that Worker Roles can process, you can create more instances of Worker Roles on demand and increase the order-processing capacity. Similarly, if the queue is under-utilized, you can reduce the Worker Role instances for processing orders.

In this scenario, the Queue service plays the role of capacity indicator. You can think of the queues in the Queue service as indicators of the system's processing capacity. You can also use this pattern to process scientific calculations and perform business analysis. Figure 5-17 illustrates the Worker Role load-distribution scenario.

Figure 5.17. Worker Role load distribution

In Figure 5-17, Worker Roles 1 through 3 can process average order loads. When the number of orders backs up into the queue, you can spawn more Worker Roles (4 through n) depending on demand and the need for overall order-processing capacity.

Large enterprises use applications from different vendors, and these applications seldom interoperate with each other. An enterprise may end up buying an expensive third-party tool that acts as the interoperability bridge between these applications. Instead, the enterprise could use the Queue service to send messages across the applications that don't interoperate with each other naturally. The Queue service exposes a REST API based on open standards. Any programming language or application capable of Internet programming can send and receive messages from the Windows Azure Queue service using the REST API. Figure 5-18 illustrates the use of the Queue service to interoperate between a Java-based Sales application and a .NET-based CRM application.

Figure 5.18. Interoperable messaging

Scenario 4: Guaranteed Processing

In Scenario 1, every order needs guaranteed processing. Any loss in orders can cause financial damage to the company. So, the Worker Roles and the Queue service must make sure every order in the queue is processed. You can implement guaranteed processing using four simple principles:

• Set the visibilitytimeout parameter to a value large enough to last beyond the average processing time for the messages.

• Set the visibilitytimeout parameter to a value small enough to make the message visible if message processing fails in a consumer (Worker Role) or a consumer crashes.

• Don't delete a message until it's processed completely.

• Design the message consumers (Worker Roles) to be idempotent (that is, they should account for handling the same message multiple times without an adverse effect on the application's business logic).

Figure 5-19 illustrates guaranteed message processing in the context of the order-processing example discussed in Scenario 1.

Figure 5.19. Guaranteed processing

In Figure 5-19, two Web Roles create orders, and three Worker Roles process orders. Consider the following steps:

1. Worker Role 1 reads order O1 for processing. Worker Roles typically take 15 seconds to process an order. The visibilitytimeout for messages is set to 60 seconds.

2. Worker Role 1 starts processing order O1. At this point, O1 isn't visible to other Worker Roles for 60 seconds.

3. Worker Role 1 crashes after 10 seconds.

4. After 60 seconds, O1 becomes visible again because Worker Role 1 wasn't able to delete it.

5. Worker Role 2 reads O1 and processes it.

6. After processing is complete, Worker Role 2 deletes O1 from the queue.

The important points to note here are that Worker Role 1 didn't delete the message from the queue before processing was complete, and the visibilitytimeout was set to an appropriate time window to exceed the processing time of an order.