Now
that you know how to work with queues, let’s look at how you can work
with messages. As we mentioned above, a queue is a FIFO structure,
similar to a line at the movie theater. The first action we usually take
with a queue it to put a message in it, or enqueue a message.
1. Putting a message on the queue
When
you put a message on the queue, the new message is placed onto the
bottom or end of the queue. When you get a message from the queue, it’s
from the top or front of the queue. Here we have a few lines of code
that show how to add a message to a queue:
CloudQueue q = Qsvc.GetQueueReference("newordersqueue");
CloudQueueMessage theNewMessage = new CloudQueueMessage("cart:31415");
q.AddMessage(theNewMessage);
To add a message to the
queue, you need to get a reference to the queue, as we did in the
preceding code. Once you have the queue reference, you can call the AddMessage method and pass in a CloudQueueMessage
object. Creating the message is a simple affair; in this case we’re
simply passing in text that will be the content of the message. You can
also pass in a byte array if you’re passing some serialized binary data.
Remember that the content of each message is limited to 8 KB in size.
When you put a message on a queue, a REST message is generated and sent
to the queue. The following listing shows you a sample of what that
might look like. This sample is for entertainment purposes only.
Listing 1. An example of putting a message onto a queue with REST
POST /my-special-queue/messages?timeout=30 HTTP/1.1
x-ms-date: Fri, 07 Aug 2009 01:49:25 GMT
Authorization: SharedKey hsslog:3oJPdtrUK47gMSpHfwrmasdnT5nJpGpszg=
Host: hsslog.queue.core.windows.net
Content-Length: 80
Expect: 100-continue
<QueueMessage><MessageText>cart:31415</MessageText></QueueMessage>
|
In this example, we’re
adding a message with an order number that can be found in the related
Azure table. The consumer will pick up the message, unwrap the content,
and process the cart numbered 31415. Their shopping cart is probably
filled with pie and pie related accessories.
Before we show you how to get a message, we want to talk about peeking.
2. Peeking at messages
Peeking is a way to get the
content of a message in the queue without taking the message off of the
queue. This leaves the message still on the queue, so someone else can
grab it. Many people peek at messages to determine if they want to
process the message or not, or to determine how they should process the
message. You can see how to peek in this snippet of code:
CloudQueueMessage m = q.PeekMessage();
private IEnumerable<CloudQueueMessage> mList;
mList = q.PeekMessages(10);
Peeking at messages is easy. Calling the PeekMessage method returns a single message—the one at the front of the queue. You can peek at more than one message by calling PeekMessages and providing the number of messages you want returned. In the preceding example, we asked for 10 messages.
Now that you’ve peeked at the messages, you’re ready to get them.
3. Getting messages
You don’t have to peek at a
message before getting it, and many times you won’t use peek at all.
Getting a message off of the queue is simple, as shown here:
private CloudQueueMessage currentMsg;
currentMsg = q.GetMessage();
If you already have a reference to your queue, getting a message is as simple as calling GetMessage. There’s one override that lets you determine the visibility timeout of the get.
Getting the contents of the
message, so that you can work with it, is quite simple, especially if it
was string data and not binary data:
string s = currentMsg.AsString;
Once you have a message, you can use the AsString or AsBytes
properties to access the contents of the message. This is the meat of
the message, and the part you’re most likely interested in.
Once you’ve processed a message, you’ll want to delete it. This takes it off of the queue.
4. Deleting messages
Deleting a message is as easy as getting it:
q.DeleteMessage(currentMsg);
To delete a message, you need to pass the message back into the DeleteMessage method of the queue object. You can also do it easily with REST. You can only delete one message at a time. The DELETE command in REST would look like the following example. Notice that all of the pertinent data needed is in the query string.
DELETE http://hsslog.queue.core.windows.net/my-special-queue/messages/f5104ff3-260c-48c8-9c35-cd8ffe3d5ace?popreceipt=AgAAAAEAAAAAAAAA1vkQXwEXygE%3d&timeout=30
Regardless of how you delete the message, through REST or the API, be prepared to handle any exceptions that might be thrown.
One aspect of messages that we
haven’t looked at yet is their lifecycle. What happens when a message is
retrieved? How does the queue keep the same message from being picked
up by several consumers at the same time? Is a message self-aware? These
are important questions for a queue service. Never losing a message
(known as durability) is critical to a queue.
