Visual Basic Code Example: Navigating Using Lookup Identifiers

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

This example provides a private Sub procedure that synchronously peeks at each message in the queue, navigating through the queue using the lookup identifier of each message it finds. Locating messages by their lookup identifier is introduced in MSMQ 3.0.

When navigating with lookup identifiers, keep the following in mind.

• Receiving applications can start at the front of the queue, at the end of the queue, or at a specific message if the lookup identifier for that message is known.

• Receiving applications can read the next message or a previous message by using the appropriate peek or receive method. This example starts at the front and navigates to the end of the queue.

• There is no time-out parameter when reading messages synchronously.

For more information on lookup identifiers, see Navigating with Lookup Identifiers.

To navigate a queue using lookup identifiers

1. Declare the objects needed to read the messages in the queue.

1. Obtain an MSMQQueueInfo object. The following example initializes the MSMQQueueInfo object by setting the MSMQQueueInfo.PathName property using the computer name and queue name provided by the caller.

   Because this procedure sets the MSMQQueueInfo.PathName property of the MSMQQueueInfo object, Message Queuing must obtain the format name of the queue before opening the queue. The format name of a public queue must be retrieved from the directory service, and the format name of a local private queue can be obtained from information stored on the local computer. However, a remote private queue cannot be opened unless the MSMQQueueInfo.FormatName property is set with a direct format name. This procedure can be modified to receive the format name from the caller or to generate a direct format name. The applicable format name can then be used to set the FormatName property. For more information, see Format Names.

2. Call MSMQQueueInfo.Open to open the queue with receive access. When opening a queue with receive access the application can peek at or retrieve the messages in the queue.

3. Call MSMQQueue.PeekFirstByLookupId to read the first message in the queue.

4. Using a loop, call MSMQQueue.PeekNextByLookupId to read the remaining messages in the queue.

5. When there are no messages left, call MSMQQueue.Closee to release resources used to open queue and exit the Sub procedure.

Code Example

The following code example requires MSMQ 3.0.

Private Sub NavigateWithLookupId( _  
                                 strComputerName As String, _  
                                 strQueueName As String _  
                                 )  
  ' Declare Message Queuing objects.  
  Dim qinfo As New MSMQQueueInfo  
  Dim q As MSMQQueue  
  Dim msg As MSMQMessage  
  
  ' Set the path name in the MSMQQueueInfo object.  
  qinfo.PathName = strComputerName & "\" & strQueueName  
  On Error GoTo ErrorHandler  
  
  ' Open the public queue with receive access.  
  Set q = qinfo.Open(Access:=MQ_RECEIVE_ACCESS, ShareMode:=MQ_DENY_NONE)  
  
  ' Peek at the first message in the queue.  
  Set msg = q.PeekFirstByLookupId  
  
  ' Peek at remaining messages.  
  Do While Not msg Is Nothing  
    MsgBox "A message was found in the queue."  
    Set msg = q.PeekNextByLookupId(LookupId:=msg.LookupId)  
  Loop  
  
  ' Close the queue.  
  q.Close  
  Exit Sub  
  
ErrorHandler:  
  MsgBox "Error " + Hex(Err.Number) + " was returned. " + Chr(13) + _  
         "Description: " + Err.Description  
  If Not q Is Nothing And q.IsOpen2 Then  
    q.Close  
  EndIf  
End Sub