MessageQueue.ReceiveById Method (String)


Receives the message that matches the given identifier from a non-transactional queue and immediately raises an exception if no message with the specified identifier currently exists in the queue.

Namespace:   System.Messaging
Assembly:  System.Messaging (in System.Messaging.dll)

public Message ReceiveById(
	string id


Type: System.String

The Id of the message to receive.

Return Value

Type: System.Messaging.Message

The Message whose Id property matches the id parameter passed in.

Exception Condition

The id parameter is null.


The message with the specified id could not be found.


An error occurred when accessing a Message Queuing method.

Use this method to read a message with a known identifier and remove it from the queue. This method throws an exception immediately if the message is not in the queue.

The Id property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given id parameter.

Two other methods allow you to receive messages from a queue. The Receive method returns the first message in the queue, and the ReceiveByCorrelationId(String) method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue.

To read a message with a specified identifier without removing it from the queue, use the PeekById(String) method. The PeekById(String) 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.

The following table shows whether this method is available in various Workgroup modes.

Workgroup mode


Local computer


Local computer and direct format name


Remote computer


Remote computer and direct format name


The following code example demonstrates the use of ReceiveById(String).

// Connect to a queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new message.
Message msg = new Message("Example Message Body");

// Send the message.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Simulate doing other work so the message has time to arrive.

// Receive the message from the queue.
msg = queue.ReceiveById(id);

.NET Framework
Available since 1.1
Return to top