NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

MessageQueue.Peek ()

Returns without removing (peeks) the first message available in the queue referenced by the MessageQueue. This call is synchronous. It blocks the current thread of execution until a message is available.

[Visual Basic]
Overloads Overridable Public Function Peek() As Message
[C#]
public virtual Message Peek();
[C++]
public: virtual Message* Peek();
[JScript]
public function Peek() : Message;

Return Value

The Message that represents the first message available in the queue.

Exceptions

Exception Type Condition
MessageQueueException The attempt to unlock the queue in order to peek generated an exception specified by the given status message.

Remarks

Use this overload to peek a queue, or wait until there are messages in the queue.

The Peek method allows for the synchronous reading of a message without removing it from the queue. Repeated calls to Peek return the same message unless a higher priority message arrives in the queue. To read a message and remove it from the queue, use the Receive method. Subsequent calls to Receive will return the following messages in the queue or a new, higher priority message.

Use a call to Peek when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the Peek method specifies an System.Messaging.MessageQueue.Infinite timeout, the application may wait indefinitely. If the application processing should continue without waiting for a message, consider using the asynchronous method, BeginPeek.

Example [Visual Basic]

The following example uses the Peek and Receive methods on a queue. A Message object is instantiated to refer to the first message in the queue. If the first message is an application-defined marker, the queue is purged. Otherwise, the first message is read and removed.

This procedure assumes that the queue "myQueue" exists on the computer "myComputer". It also assumes that the message body "Purge the queue" is used to indicate that the queue should be purged.

[Visual Basic]

Private Sub PeekQueue()
    'Define a Message.
    Dim msg As System.Messaging.Message
    'Define a string to hold the contents of the message body
    Dim msgBody As String
    'Define a new MessageQueue.
    Dim messageQueue1 As MessageQueue
    'Associate the MessageQueue with the given queue.
    messageQueue1 = New MessageQueue("myComputer\myQueue")

    'Read without removing (peek) the first message in the queue.
    msg = messageQueue1.Peek

    'If the message body indicates a specific marker, purge the queue.
    If msg.BodyStream.ToString = "Purge the queue." Then
        messageQueue1.Purge()
    Else
        'Otherwise, remove the top message from the queue (receive it).
        msg = MessageQueue1.Receive
    End If
End Sub

See Also

MessageQueue Class | MessageQueue Members | System.Messaging Namespace | MessageQueue.Peek Overload List | Receive | BeginPeek | BeginReceive