This documentation is archived and is not being maintained.

Peeking at Messages

You can use the Peek method to look at the first message on any queue without removing that message from the queue. This allows your component to get information from the queue without preventing other applications or components from retrieving messages they were intended to process.

Note   Peek allows you to see only the first message on the queue. Because that message is not removed from the queue when you peek at it, you cannot then peek at subsequent messages. If you want to see all of the messages in a queue without removing them from the queue, you can use the GetAllMessages method or the GetMessageEnumerator method. For more information, see Queue and Message Collections.

If there are no messages in the queue when you call the Peek method, the method waits until a message arrives. You can specify a time-out period if you want the method to wait only a specified period of time. The time-out period is specified as a TimeSpan object. Most commonly, the time-out period will be set to either zero, in which case it checks for a message and does not wait at all, or to the default infinite setting, which waits indefinitely. You would set this in code using the following syntax:

' Visual Basic
msg.TimeToBeReceived = System.Messaging.Message.InfiniteTimeout

// C#
msg.TimeToBeReceived = System.Messaging.Message.InfiniteTimeout;

You can also set this in the Properties window by setting the TimeToBeReceived property for DefaultMessagestoSend to Infinity.

Tip   When using dependent clients, be sure the clock on the client computer is synchronized with the clock on the server that is running Message Queuing. Otherwise, unpredictable behavior might result when sending a message whose TimeToBeReceived property is not InfiniteTimeout.

Peeking can be synchronous or asynchronous. For more information, see Receiving Messages Asynchronously.

To peek at messages synchronously

  1. Create an instance of the MessageQueue component and set its Path property to the queue to which you want to refer. For more information, see Creating MessageQueue Component Instances.
  2. Create an instance of the Message object to hold the data the Peek method copies from the queue.
  3. Call the Peek method to get data about the first message on the queue. Optionally, to specify a time-out for the Peek method, enter the length of time (as a TimeSpan object) that you want the method to wait as an argument of the method.

    For example, the following code shows how you can use the Peek method to return and display information about the first message on a queue. This example assumes that you are working on a Windows Forms application that contains a label called Label1, and that you are working with a queue called MyQueue.

    ' Visual Basic
    Public Sub LookFirstMessage()
       Dim NewQueue As New System.Messaging.MessageQueue(".\MyQueue")
       Dim FirstMessage As System.Messaging.Message
       FirstMessage = NewQueue.Peek
       Dim targetNames() As String = {"System.String,mscorlib"}
       FirstMessage.Formatter = _
          New System.Messaging.XmlMessageFormatter(targetNames)
       Dim label As String = CStr(FirstMessage.Label)
    End Sub
    // C#
    public void LookFirstMessage()
       System.Messaging.MessageQueue newQueue = 
          new System.Messaging.MessageQueue(".\\MyQueue");
       System.Messaging.Message firstMessage;
       string[] types = { "System.String,mscorlib" };
       firstMessage = newQueue.Peek();
       firstMessage.Formatter = 
          new System.Messaging.XmlMessageFormatter(types);
       string label = firstMessage.Label.ToString();

See Also

Reading and Receiving Messages | Receiving Messages Programmatically | Creating MessageQueue Component Instances