Manipulating Queues in .NET

.NET provides a System.Messaging namespace that provides types used for formatting, sending, and receiving messages as well as for programmatically discovering, creating, and configuring message queues. Table 8-1 lists the key types in this namespace. The MessageQueue class is the heart of this namespace because it provides instance-based members that enable you to interact with a specific queue and shared methods for retrieving information about all the queues on a computer.

Table 8-1. System.Messaging Classes 

Class	Description
BinaryMessageFormatter	Serializes or deserializes a .NET object (or an entire graph of connected objects) to or from the body of a Message Queuing message using a binary format.
Message	Encapsulates a Message Queuing message and its properties.
MessageQueue	Provides access to a queue on a Message Queuing server, enabling you to send or retrieve messages.
MessageQueueException	Represents an internal Message Queuing error.
MessageQueueInstaller	Enables you to install and configure a message queue. This class can be added to a custom setup project or used with the InstallUtil.exe utility.
XmlMessageFormatter	Serializes or deserializes a .NET object (or an entire graph of connected objects) to or from the body of a Message Queuing message using an XML format based on the XSD schema definition.

Before continuing with the following examples, be sure to add a reference to the System.Messaging.dll assembly and import this namespace:

 Imports System.Messaging 

Selecting a Queue

You can take two approaches to finding a queue. You can create the message queue by name or you can search through all the message queues available on a computer or in Active Directory.

To create a link to a known message queue, you just create a new MessageQueue object and specify the name in the constructor. A good approach is to use the Exists method first to verify that the desired queue can be found before you attempt to create it.

Queues are identified using a path-like syntax, which you might have already seen in the MSMQ configuration windows. The first portion of the path indicates a computer or domain name or uses a period (.) to indicate the current computer. The second portion indicates the public queue name. Therefore, Listing 8-3 creates a MessageQueue object for the public queue called MyQueue and displays its public GUID:

Listing 8-3 Selecting a queue

 If MessageQueue.Exists(".\MyQueue") Then     Dim Queue As New MessageQueue(".\MyQueue")     ' Display the unique ID, which is set when the queue is created.     Console.WriteLine(Queue.Id.ToString()) End If 

If you want to connect to a private queue, the second portion of the queue path should always be Private$ and the third portion should be the queue name.

For example, the following code statement creates a reference to a private queue on the current computer:

 Dim Queue As New MessageQueue(".\Private$\MyQueue") 

Occasionally, you might want to open another type of queue. Table 8-2 lists the required queue path formats.

Table 8-2. Queue Path Formats

Queue Type	Path Format
Public	[MachineName]\[QueueName]
Private	[MachineName]\Private$\[QueueName]
Journal	[MachineName]\[QueueName]\Journal$
Machine journal	[MachineName]\Journal$
Machine dead-letter	[MachineName]\DeadLetter$
Machine transactional dead-letter	[MachineName]\XactDeadLetter$

All the rules change when you're working in a disconnected environment. In this case, the queue is not available when the MessageQueue object is constructed (and when the message is sent). You need to use the format name rather than the queue name. The format name takes one of several formats, some of which use the GUID that identifies the queue or the machine. Here's an example:

 ' This works even if the queue is not currently available. Dim Queue As New MessageQueue( _   "FormatName:PUBLIC=382c74c3-721d-4f34-80e5-57657b6cbc27") 

Table 8-3 lists the supported format names. Note that to determine a queue's GUID or number, you must either look it up with the Computer Management utility or create a test application. This test application creates a MessageQueue object using the name of the queue while connected to the network and then displays the required information.

Table 8-3. Queue Path Formats

Type	Syntax
Public queue	FormatName:PUBLIC=[QueueGUID]
Private queue	FormatName:PRIVATE=[MachineGUID]\[QueueNumber]
Queue by machine	FormatName:DIRECT=OS:[MachineName]\[QueueNumber]
Queue with protocol	FormatName:DIRECT=[Protocol]:MachineName]\[QueueNumber]

Note that you can't use the "queue with protocol" option equivalently on all systems. For example, Message Queuing 3.0 supports the HTTP protocol, whereas Message Queuing 2.0 does not.

After you have a MessageQueue object, you can retrieve or set a great deal of information, including all the properties shown in the Computer Management administrative tool. The .NET class library reference describes all the queue properties that you can access.

Searching for a Queue

Another way to find a queue is to use the shared MessageQueue.GetPublicQueues method, as shown in Listing 8-4.

Listing 8-4 Browsing all public queues

 Dim Queues As MessageQueue() = MessageQueue.GetPublicQueues() Dim Queue As MessageQueue ' Add the path for every queue to a list control. For Each Queue In Queues     lstQueues.Items.Add(Queue.Path) Next 

You can also use an overloaded version of the GetPublicQueues method that accepts a MessageQueueCriteria instance. You can use this object to define filter criteria for the queues you want to retrieve, including label, category, and machine information. There are also specialized methods such as GetPublicQueuesByMachine, GetPublicQueuesByCategory, and GetPublicQueuesByLabel.

With private queues, you're constrained to a single GetPrivateQueuesByMachine method, which enables you to retrieve the queues for a single machine (as shown in Listing 8-5).

Listing 8-5 Browsing all private queues

 Dim Queues As MessageQueue() ' Get the private queues for the current machine. Queues = MessageQueue.GetPrivateQueuesByMachine(".") 

Creating a Queue

Programmatically creating a queue is just as easy after you understand the queue path syntax. For example, you can create a public queue using the shared MessageQueue.Create method, as shown in Listing 8-6.

Listing 8-6 Creating a public queue

 Dim Queue As MessageQueue Queue = MessageQueue.Create("MyDomain\TestPublicQueue") Console.Write("Created: " & Queue.Path) Console.WriteLine("at " & Queue.CreateTime.ToString()) 

Listing 8-7 generates a new private queue on the current computer.

Listing 8-7 Creating a private queue

 Dim Queue As MessageQueue Queue = MessageQueue.Create(".\Private$\TestPrivateQueue") 

The next code snippet uses the only other version of the Create method. This accepts a Boolean parameter that, if True, creates a transactional queue:

 Dim Queue As MessageQueue Queue = MessageQueue.Create(".\Private$\TestTransactionalQueue", True) 

The MessageQueue class also exposes a shared Delete method, which removes the named queue entirely, and an instance Purge method, which clears out all the messages from a queue.