Edit

Share via


MessageQueue.ReceiveByLookupId Method

Definition

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

Overloads

ReceiveByLookupId(Int64)

Introduced in MSMQ 3.0. Receives the message that matches the given lookup identifier from a non-transactional queue.

ReceiveByLookupId(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.

ReceiveByLookupId(MessageLookupAction, Int64, MessageQueueTransactionType)

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

ReceiveByLookupId(Int64)

Introduced in MSMQ 3.0. Receives the message that matches the given lookup identifier from a non-transactional queue.

public:
 System::Messaging::Message ^ ReceiveByLookupId(long lookupId);
public System.Messaging.Message ReceiveByLookupId (long lookupId);
member this.ReceiveByLookupId : int64 -> System.Messaging.Message
Public Function ReceiveByLookupId (lookupId As Long) As Message

Parameters

lookupId
Int64

The LookupId of the message to receive.

Returns

The Message whose LookupId property matches the lookupId parameter passed in.

Exceptions

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.

Remarks

Use this method to read a message with a known lookup identifier and remove it from the queue. 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.

To read a message with a specified lookup identifier without removing it from the queue, use the PeekByLookupId method.

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

Workgroup mode Available
Local computer Yes
Local computer and direct format name Yes
Remote computer No
Remote computer and direct format name Yes

See also

Applies to

ReceiveByLookupId(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.

public:
 System::Messaging::Message ^ ReceiveByLookupId(System::Messaging::MessageLookupAction action, long lookupId, System::Messaging::MessageQueueTransaction ^ transaction);
public System.Messaging.Message ReceiveByLookupId (System.Messaging.MessageLookupAction action, long lookupId, System.Messaging.MessageQueueTransaction transaction);
member this.ReceiveByLookupId : System.Messaging.MessageLookupAction * int64 * System.Messaging.MessageQueueTransaction -> System.Messaging.Message
Public Function ReceiveByLookupId (action As MessageLookupAction, lookupId As Long, transaction As MessageQueueTransaction) As Message

Parameters

action
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.

lookupId
Int64

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

Returns

The Message specified by the lookupId and action parameters passed in.

Exceptions

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.

-or-

The queue is non-transactional.

The action parameter is not one of the MessageLookupAction members.

Remarks

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 Available
Local computer Yes
Local computer and direct format name Yes
Remote computer No
Remote computer and direct format name Yes

See also

Applies to

ReceiveByLookupId(MessageLookupAction, Int64, MessageQueueTransactionType)

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

public:
 System::Messaging::Message ^ ReceiveByLookupId(System::Messaging::MessageLookupAction action, long lookupId, System::Messaging::MessageQueueTransactionType transactionType);
public System.Messaging.Message ReceiveByLookupId (System.Messaging.MessageLookupAction action, long lookupId, System.Messaging.MessageQueueTransactionType transactionType);
member this.ReceiveByLookupId : System.Messaging.MessageLookupAction * int64 * System.Messaging.MessageQueueTransactionType -> System.Messaging.Message
Public Function ReceiveByLookupId (action As MessageLookupAction, lookupId As Long, transactionType As MessageQueueTransactionType) As Message

Parameters

action
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.

lookupId
Int64

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

transactionType
MessageQueueTransactionType

One of the MessageQueueTransactionType values, describing the type of transaction context to associate with the message.

Returns

The Message specified by the action and lookupId parameters passed in.

Exceptions

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 action parameter is not one of the MessageLookupAction members.

-or-

The transactionType parameter is not one of the MessageQueueTransactionType members.

Remarks

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 transactionType 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.

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.

Specify Automatic for the transactionType parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify Single if you want to receive the message as a single internal transaction. You can specify None if you want to receive a message from a transactional queue outside of a transaction context.

If this method is called to receive a message from 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.

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

Workgroup mode Available
Local computer Yes
Local computer and direct format name Yes
Remote computer No
Remote computer and direct format name Yes

See also

Applies to