Queue and Message Collections

You can retrieve lists of the queues on your Message Queuing network and the messages they contain by using any of a variety of retrieval methods available in the MessageQueue class. You might retrieve lists of queues and messages if you want to perform administrative tasks , generate reports about queue contents, or search through the contents of a queue for messages that meet specific criteria.

You can retrieve both messages and message queues in two main ways: You can retrieve a static snapshot of the messages or queues on the network, or you can use an enumerator to iterate through messages and queues. Retrieving a static list of queues or messages is faster than retrieving an enumeration, but it does not give you as much accuracy in or control over the resulting set of information. You might use a static snapshot of retrieval if you need to perform an administrative task on all public queues in your network.

Enumerators give you finer control over how you interact with the retrieved results. Using an enumerator, you can locate a queue or message that meets certain criteria, rather than evaluate each and every item in the returned collection. For example, you might use an enumerator if you want to review the contents of a queue and work with only those messages for which a particular property has been set to True.

Message Queues Retrieval

You can retrieve information about message queues in the following ways:

• You can retrieve a static array of all the public or private queues on the network.

• You can retrieve a static subset of all the public queues on the network by specifying certain criteria such as the date and time the queue was created or modified, or by specifying a category, label, or machine by which to retrieve queues.

• You can iterate queues on the network using an enumerator, or you can iterate through a subset of all the queues on the network by specifying criteria such as machine name , date and time created, and category.

• You can also use the Exists method to determine whether a queue you are interested in exists. The Exists method searches for a specific queue by a path you define.

Message Retrieval

When you retrieve messages in an array or enumerator, you do not actually pull those messages off the queue as you do when you read or receive messages. Instead, you retrieve information about the items in the queue, while the actual messages remain available to the users who were intended to receive them.

You can retrieve messages in the following ways:

• You can retrieve a static array of all the messages in a queue.

• You can use an enumerator iterate messages in a queue.

After you create an enumeration of messages or queues, the enumerator is conceptually positioned before the first item of the enumeration. You can call the GetNext method to move to the first item in the list and to move through subsequent items. You can also use the Current method to return the item on which you are currently positioned in the enumeration.

Retrieving a Static List of Messages

The following code shows how you might use the GetAllMessages function to retrieve the messages from a queue and display the message labels in a list box. This example assumes that a MessageQueue component instance has been added to the application.

 ' Visual Basic  Private Sub button1_Click(ByVal sender As System.Object,  ByVal e As System.EventArgs) Handles button1.Click     Me.messageQueue1.Path = (".\MyQueue")     Dim msg() As System.Messaging.Message     Dim i As Integer     ' Retrieve the messages.     msg = messageQueue1.GetAllMessages()     ' Clear the current contents of the list.     Me.listBox1.Items.Clear()     ' Display the results.     For i = 0 To msg.Length - 1        Me.listBox1.Items.Add(msg(i).Label)     Next  End Sub  // C#  private void button1_Click(System.Object sender, System.EventArgs e)  {     messageQueue1.Path = (".\MyQueue");     System.Messaging.Message[] msg;     integer i;     // Retrieve the messages.     msg = messageQueue1.GetAllMessages();     // Clear the current contents of the list.     this.listBox1.Items.Clear();     // Display the results.     for (int i = 0; i < msg.Length; i++)     {        this.listBox1.Items.Add(msg[i].Label);     }  } 

Retrieving a Dynamic List of Messages

If you need to assign the results to the MessageEnumerator object, your code might look like this:

 ' Visual Basic  Dim mq as New System.Messaging.MessageQueue(".\MyQueue")  Dim msgEnum As System.Messaging.MessageEnumerator  msgEnum = CType(mq.GetEnumerator, System.Messaging.MessageEnumerator)  // C#  System.Messaging.MessageQueue mq = new System.Messaging.MessageQueue();  System.Messaging.MessageEnumerator msgEnum;  mq.Path = @".\MyQueue";  msgEnum = (MessageEnumerator)(mq.GetEnumerator());