How to: Retrieve Queues

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

You can use either static or dynamic retrieval mechanisms to retrieve a list of queues. When you retrieve a static list of queues, the system returns a MessageQueue object with the results of your query. When you retrieve a dynamic list of queues, the system returns a MessageQueueEnumerator object with the results of the query.

Unlike the MessageEnumerator, which returns messages according to their order in a queue, the MessageQueueEnumerator does not return queues in any order. This is because queues on a network are not defined in order — they are not ordered, that is, by computer, label, or other user-accessible criteria. You can move the cursor to the first queue of the enumeration by calling the MoveNext method. After the enumerator has been initialized, you can use MoveNext to step forward through the remaining queues.

It is not possible to step backward with a MessageQueueEnumerator. A cursor only allows forward movement through the queue enumeration. However, you can call the Reset method to reset the enumeration and put the cursor at the beginning of the list again. Because the enumerator is dynamic, it can access a queue that is appended beyond the cursor's current position. A queue that is inserted before the cursor's current position cannot be accessed without first calling Reset.

Because the GetPublicQueues, GetPrivateQueuesByMachine, and GetMessageQueueEnumerator methods are static, you do not need to create an instance of the MessageQueue class before calling the method.

To retrieve a static list of public or private queues

1. Create an array of type MessageQueue to hold the results of your query.

2. Call the appropriate method on the MessageQueue class:

   • To retrieve all public queues without criteria, call the GetPublicQueues method.

   • To retrieve public queues with criteria, set the Criteria parameter to the appropriate value and call the GetPrivateQueuesByMachine method.

   • To retrieve only those public queues that share a category GUID, call the GetPublicQueuesByCategory method and specify the category GUID as the parameter.

   • To retrieve only those public queues that share a label, call the GetPublicQueuesByLabel method and specify the label as a parameter.

   • To retrieve only those public queues on a specific machine, call the GetPublicQueuesByMachine method and specify the machine name as a parameter.

3. Assign the results to the array.

   For example, the following code shows how you might use a list box to display the label of all retrieved public queues on the local machine:

   Private Sub button1_Click(ByVal sender As System.Object,
      ByVal e As System.EventArgs) Handles button1.Click
       Dim mqlist() As System.Messaging.MessageQueue
       Dim i As Integer
       ' Retrieve queues on the local machine.
       mqlist = System.Messaging.MessageQueue.GetPublicQueuesByMachine(".")
       ' Clear the current contents of the list.
       Me.ListBox1.Items.Clear()
       ' Display the results.
       For i = 0 To mqlist.Length - 1
           Me.ListBox1.Items.Add(mqlist(i).Path)
       Next
   End Sub
   

       private void button1_Click(System.Object sender, System.EventArgs e)
       {
           System.Messaging.MessageQueue[] mqlist;
           // Retrieve public queues.
           mqlist = System.Messaging.MessageQueue.GetPublicQueuesByMachine(
              ".");
           // Clear the current contents of the list.
           this.listBox1.Items.Clear();
           // Display the results.
           for (int i = 0; i < mqlist.Length; i++)
           {
               this.listBox1.Items.Add(mqlist[i].Path);
           }
       }
   

To retrieve a dynamic list of queues

1. Create a MessageQueueEnumerator object to hold the results of your query.

2. Call the GetMessageQueueEnumerator method on the MessageQueue class.

3. To retrieve a subset of the queues on the network, set the MessageQueueCriteria parameter to the appropriate value.

4. Set the results to the MessageQueueEnumerator object you created. Your code might look like this:

   Dim mqEnum As System.Messaging.MessageQueueEnumerator
   mqEnum = System.Messaging.MessageQueue.GetMessageQueueEnumerator()
   

           System.Messaging.MessageQueueEnumerator mqEnum;
           mqEnum = System.Messaging.MessageQueue.GetMessageQueueEnumerator();
   

See Also

Tasks

How to: Retrieve Messages

Concepts

Queue and Message Collections