Export (0) Print
Expand All

MessageQueue.ReceiveByLookupId Method (MessageLookupAction, Int64, MessageQueueTransaction)

Introduced in MSMQ 3.0. Receives a specific message from a transactional queue. The message can be specified by a lookup identifier or by its position at the front or end of the queue.

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

public Message ReceiveByLookupId(
	MessageLookupAction action,
	long lookupId,
	MessageQueueTransaction transaction


Type: System.Messaging.MessageLookupAction

One of the MessageLookupAction values, specifying how the message is read in the queue. Specify one of the following:

MessageLookupAction.Current: Receives the message specified by lookupId and removes it from the queue.

MessageLookupAction.Next: Receives the message following the message specified by lookupId and removes it from the queue.

MessageLookupAction.Previous: Receives the message preceding the message specified by lookupId and removes it from the queue.

MessageLookupAction.First: Receives the first message in the queue and removes it from the queue. The lookupId parameter must be set to 0.

MessageLookupAction.Last: Receives the last message in the queue and removes it from the queue. The lookupId parameter must be set to 0.

Type: System.Int64

The LookupId of the message to receive, or 0. 0 is used when accessing the first or last message in the queue.

Type: System.Messaging.MessageQueueTransaction

The MessageQueueTransaction object.

Return Value

Type: System.Messaging.Message
The Message specified by the lookupId and action parameters passed in.


MSMQ 3.0 is not installed.


The message with the specified lookupId could not be found.


An error occurred when accessing a Message Queuing method.


The queue is non-transactional.


The action parameter is not one of the MessageLookupAction members.

Use this method to read a message with a known lookup identifier and remove it from the queue, using a transaction context defined by the transaction parameter. This method throws an exception immediately if the message is not in the queue.

The LookupId property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given lookupId parameter.

Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed.

To read a message with a specified identifier without removing it from the queue, use the PeekByLookupId method. There is no transaction context associated with a message returned by a call to PeekByLookupId. Because PeekByLookupId does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted.

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


.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

© 2014 Microsoft