Working with Message Queues
The MessageQueue class is a wrapper around MessageQueuing, which defines functionality to access and manage a queue on an MSMQ server. This class also provides methods to create and delete queues, send and receive messages, and retrieve queues and messages.
Using the MessageQueue Properties
It's always a good idea to know what functionality is provided by a class before using the class. Table 21-1 describes the MessageQueue class properties.
| PROPERTY | DESCRIPTION |
|---|---|
| Authenticate | This property represents whether a queue will accept only authenticated messages. The queue will reject nonauthenticated messages. Both get and set. |
| BasePriority | This property represents the base priority of messages. Both get and set. |
| CanRead | This property is true if a message queue can be read; otherwise, it's false. Both get and set. |
| CanWrite | This property is true if a message queue can be written to; otherwise, it's false. Both get and set. |
| Category | This property represents the queue category. Both get and set. |
| CreateTime | This property gets the time and date the queue was created. |
| DefaultPropertyToSend | This represents the default message property when an application sends a message. Both get and set. |
| DenySharedRecieve | This property is true if the queue has exclusive access to receive messages from the MSMQ queue; otherwise, it's false. Both get and set. |
| EnableConnectionCache | When this property is true, a cache of connections will be maintained by the application; otherwise, they won't. Both get and set. |
| EncryptionRequired | If this property is true, the queue accepts only nonprivate (nonencrypted) messages. Both get and set. |
| FormatName | This property represents the unique queue name generated by MSMQ when queue was created. Read only. |
| Formatter | This property represents the formatter used to serialize and deserialize. Both get and set. |
| Id | This property represents the unique queuing identifier. Read only. |
| Label | This property represents the queue description. Both get and set. |
| LastModifyTime | This property represents the last time the properties on a queue were modified. Read only. |
| MachineName | This property represents the name of the computer where queue is located. Both read and write. |
| MaximumJournalSize | This property represents the maximum size of the journal queue. Both get and set. |
| MaximumQueueSize | This property represents the maximum size of the queue. Both get and set. |
| MessageReadPropertyFilter | This is the property filter for receiving or peeking messages. Both get and set. |
| Path | This property represents the queue path. Both get and set. |
| QueueName | This property represents the queue's user-friendly name. Both get and set. |
| ReadHandle | This property represents the native handle used to read messages from the queue. Read only. |
| SynchronizingObject | This property represents the object that marshals the event handler calls resulting from a ReceiveCompleted or PeekCompleted event. Both get and set. |
| Transactional | When this property is true, the queue accepts only transactions. |
| UseJournalQueue | If this property is true, received messages are copied to the journal queue. Both get and set. |
| WriteHandle | This property represents the native handle used to send messages to the queue. Read only. |
Managing Queues Using VS .NET
In Visual Studio .NET (VS .NET), the Server Explorer provides options to manage messaging queues in the messaging server. You can see all available queues by expanding the Servers\MachineName\Message Queues node. The Message Queues node has three children—Private Queues, Public Queues, and System Queues—that list private, public, and system queues, respectively. You can see the corresponding available queues by expanding these nodes (see Figure 21-2).
Figure 21-2: Managing message queues through the Server Explorer
The Server Explorer also allows you to create and delete queues. To create a queue, right-click the Private Queues or Public Queues node and select the Create Queue option.
| Note | You may not be able to view or create public queues if you're a member of a proper domain or working on a WORKGROUP computer. |
Now if you expand an available queue, you'll see children: Journal Messages and Queue Messages. You can also delete messages from a queue by simply right-clicking and selecting the Clear Messages menu option.
| Tip | After creating a message queue using the Server Explorer, you can easily add it to your application by simply dragging the queue from the Server Explorer to a form. This action adds an object of type MessageQueue to your project. |
Retrieving Available Queues
The MessageQueue class provides six methods, which you can use to retrieve private and public queues.
The GetPrivateQueuesByMachine method retrieves private queues available on the server (see Listing 21-1).
Listing 21-1: Retrieving Private Queues
 |
Dim queList As MessageQueue() = _ MessageQueue.GetPrivateQueuesByMachine(".") Dim que As MessageQueue For Each que In queList Console.WriteLine(que.Path) Next que |
The GetPublicQueues method returns public queues on the server (see Listing 21-2).
Listing 21-2: Retrieving Public Queues
|
Sub GetPublicQueuesMethod() Try Dim queList As MessageQueue() = _ MessageQueue.GetPublicQueues() Dim que As MessageQueue For Each que In queList Console.WriteLine(que.Path) Next que Catch exp As Exception Console.WriteLine(exp.Message) End Try End Sub
|
The GetPublicQueuesByCategory method returns public queues that belong to the specified category. This method takes the ID of the queue as an argument, which can be retrieved by using the Id property of MessageQueue.
The GetPublicQueuesByMachine method returns public queues that belong to the specified machine. This method takes the machine name as an argument.
The GetPublicQueuesByLabel method returns public queues that have the specified label.
| Note | All GetPublicXXX and GetPrivateQueuesByMachine methods are static methods. Hence, they can't be used through the MesssageQueue class instances. |
Listing 21-3 retrieves public queues based on the specified category, machine, and label.
Listing 21-3: Filtering Queues Based on Category, Machine Name, and Label
|
Sub GetQueuesByCategoryMethod() Try Dim queList As MessageQueue() = _ MessageQueue.GetPublicQueuesByCategory(New _ Guid("{00000000-0000-0000-0000-000000000001}")) Dim que As MessageQueue For Each que In queList Console.WriteLine(que.Path) Next que Catch exp As Exception Console.WriteLine(exp.Message) End Try End Sub Public Sub GetQueuesByLabelMethod() Try Dim queList As MessageQueue() = _ MessageQueue.GetPublicQueuesByLabel("LabelName") Dim que As MessageQueue For Each que In queList Console.WriteLine(que.Path) Next que Catch exp As Exception Console.WriteLine(exp.Message) End Try End Sub Public Sub GetQueuesByMachineMethod() Try Dim queList As MessageQueue() = _ MessageQueue.GetPublicQueuesByMachine("MCB") Dim que As MessageQueue For Each que In queList Console.WriteLine(que.Path) Next que Catch exp As Exception Console.WriteLine(exp.Message) End Try End Sub |
Filtering Queues Using MessageQueueCriteria
You can even filter public queues by using GetPublicQueues. This method takes an argument of type MessageQueueCriteria. The MessageQueueCriteria class provides properties you can use to filter queue types (see Table 21-2).
| PROPERTY | DESCRIPTION |
|---|---|
| Category | Filters queues based on this category (both get and set) |
| CreatedAfter | Filters queues created after this time (both get and set) |
| CreatedBefore | Filters queues created before this time (both get and set) |
| Label | Filters queues based on this label (both get and set) |
| MachineName | Filters queues based on this machine name (both get and set) |
| ModifiedAfter | Filters queues based on the queues modified after this time (both get and set) |
| ModifiedBefore | Filters queues based on the queues modified before this time (both get and set) |
Using MessageQueueCriteria, you can simply filter the queues. The following code filters queues based on a machine name and label:
Dim filter As New MessageQueueCriteria() Filter.MachineName = "MCB" filter.Label = "LabelName " Dim queList As MessageQueue() = _ MessageQueue.GetPublicQueues(filter)
| Tip | To remove all filters set by the MessageQueueCriteria class, call the RemoveAll method. |
Creating and Deleting Message Queues Programmatically
The Create method of MessageQueue creates a queue on the server. This method has two overloaded forms. The first form takes only one argument of the path of the queue, and the second form takes a path with a Boolean argument, which represents whether the queue will be created as a transactional queue. The following shows both forms of the Create method:
Overloads Public Shared Function Create(String) As MessageQueue Overloads Public Shared Function Create(String, Boolean) As MessageQueue
The Create method returns an object of type MessageQueue. You can create a public queue or a private queue using the Create method. The type of queue created depends on the path of the queue. For a public queue, the path syntax is MachineName\QueueName; for a private queue, the path syntax is MachineName\Private$\QueueName.
The following code creates one public and one private queue:
MessageQueue.Create(".\MyPubQ") MessageQueue.Create(@".\Private$\MyPrivatQ") The Delete method of MessageQueue deletes a queue on the server. Similar to the Create method, the deletion of the public or private queue depends on the path of the queue. The following code deletes a public and a private queue from the server:
MessageQueue.Delete(".\MyPubQ") MessageQueue. Delete (@".\Private$\MyPrivatQ") The Exists method checks whether a queue path is available.
| Note | The Create, Delete, and Exists methods are static methods and hence can't be used through the MessageQueue class instances. |
EAN: 2147483647
Pages: 214