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.Receive ()

Receives 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 Receive() As Message
[C#]
public virtual Message Receive();
[C++]
public: virtual Message* Receive();
[JScript]
public function Receive() : Message;

Return Value

A Message that references the first message available in the queue.

Exceptions

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

Remarks

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

The Receive method allows for the synchronous reading of a message, removing it from the queue. Subsequent calls to Receive will return the messages that follow in the queue,k or a new, higher priority message.

To read the first message in a queue without removing it from the queue, use the Peek method. The Peek method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue.

Use a call to Receive 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 Receive 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.Receive Overload List | Peek | BeginReceive | BeginPeek