Using MessageQueue in the .NET Framework 2.0

Introduction

Thread Safety

Only the following methods are safe for multithreaded operations: BeginPeek, BeginReceive, EndPeek, EndReceive, GetAllMessages, Peek, and Receive. I will try to explain these methods in my articles.

Remarks

Message Queuing technology allows applications running at different times to communicate across heterogeneous networks and systems which might be temporarily offline. Applications send, receive, or peek (read without removing) messages from queues. Message Queuing is an optional component of Windows 2000 and Windows NT, and must be installed separately.

The MessageQueue class is a wrapper around Message Queuing. There are multiple versions of Message Queuing, and using the MessageQueue class can result in slightly different behavior, depending on the Operating System you are using. For information about specific features of each version of Message Queuing, see the topic "What's New in Message Queuing" in the Platform SDK in MSDN.

The MessageQueue class provides a reference to a Message Queuing queue. You can specify a path in the MessageQueue constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call Send, Peek, or Receive, you must associate the new instance of the MessageQueue class with an existing queue. At that point, you can manipulate the queue properties such as Category and Label.

The MessageQueue class supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, Peek and Receive, cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, BeginPeek and BeginReceive, allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads.

When you create a new instance of the MessageQueue class, you are not creating a new Message Queuing queue. Instead, you can use the Create, Delete, and Purge methods to manage queues on the server.

Note: Unlike Purge, Create and Delete are static (Shared in Visual Basic) members, so you can call them without creating a new instance of the MessageQueue class.

You can set the MessageQueue object's Path property with one of three names: the friendly name, the FormatName, or the Label. The friendly name, which is defined by the queue's MachineName and QueueName properties, is MachineName\ QueueName for a public queue, and MachineName\ Private$\ QueueName for a private queue. The FormatName property allows offline access to message queues. Lastly, you can use the queue's Label property to set the queue's Path.

For a list of initial property values for an instance of MessageQueue, see the MessageQueue constructor.

Using the Message Queue

Create an instance of the class MessageQueue. Before you can create it, you need to import a reference of the class:

Imports System.Messaging 
 
'' Creating Instance of Message Queue
'' I have passed in the path Of the Queue
'' the path declared is a private queue path
Private WithEvents myQueue As New MessageQueue(".\private$\myQueue")

 
'' You can define the path later on also
Private WithEvents myQueue As New MessageQueue()
  

'' then in the form load or any other event define the path
'' the path declared is a private queue path
myQueue.Path = "".\private$\myQueue"

I have declared the message queue with an event because I am going to use some of the events available with the class.

Now, let's see how to send a message to the queue

To send a message to the message queue, you can either create a message using the Message class or by directly sending a string:

'' sending by creating a message variable 
Dim msg As New Message 
'' it is the lable of the message
msg.Label = "Example" 
'' it is the body of the message
msg.Body = "This message is send as an example" 
myQueue.Send(msg)
 
'' Send msg with creating a message vairable
myQueue.Send("Example","This message is send as an example")

There are some other ways to send messages to the queue. I found these methods over the MSDN. I found some of them very useful.

' References public queues.
Public Sub SendPublic()
        '' the path is of public queue
        Dim myQueue As New MessageQueue(".\myQueue")
         myQueue.Send("Public queue by path name.")
         Return
End Sub 'SendPublic

' References private queues.
Public Sub SendPrivate()
    Dim myQueue As New MessageQueue(".\Private$\myQueue")
         myQueue.Send("Private queue by path name.")
         Return
End Sub 'SendPrivate

' References queues by label.
    Public Sub SendByLabel()
    Dim myQueue As New MessageQueue("Label:TheLabel")
         myQueue.Send("Queue by label.")
    Return
End Sub 'SendByLabel

' References queues by format name.
Public Sub SendByFormatName()
    Dim myQueue As New _
         MessageQueue("FormatName:Public=5A5F7535-AE9A-41d4-935C-845C2AFF7112")
    myQueue.Send("Queue by format name.")
    Return
End Sub 'SendByFormatName

Now, let's see how to receive message from the queue

By using the method Receive, we can receive the first message in the queue, removing it from the queue:

'' using the recieve method
myQueue.Receive()

But there is a catch: we have to store the message we received in a Message variable.

''saving message from the queue in our temp message variable
Dim tempMsg as New Message
tempMsg = myQueue.Receive()

If you wish to check the message before removing it, you can use the Peek method:

'' using the peek method
Dim tempMSg as New Message
tempMsg = MyQueue.Peek()
'' Check if the message is ours
If tempMsg.Label = "Example" Then
    '' we got the message
    '' so we remove it from the Queue
    myQueue.Receive()
End If

Points of Interest

The MessageQueue is useful when there are a couple of applications that share data between them.

Bibliography

I have gone through some examples over the net and MSDN to write this article.