MessageQueue.PeekById Method (String)

 
System_CAPS_noteNote

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Peeks the message whose message identifier matches the id parameter.

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

public Message PeekById(
	string id
)

Parameters

id
Type: System.String

The Id of the message to peek.

Return Value

Type: System.Messaging.Message

The Message whose Id property matches the id parameter.

Exception Condition
ArgumentNullException

The id parameter is null.

InvalidOperationException

No message with the specified id exists.

MessageQueueException

An error occurred when accessing a Message Queuing method.

Use PeekById(String) to read, without removing from the queue, a message that has a known message identifier. The identifier 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. This overload throws an exception if the queue does not currently contain the message.

Two additional methods allow you to peek messages in a queue: Peek and PeekByCorrelationId(String). The Peek method returns the first message in the queue; PeekByCorrelationId(String) returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue.

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

The following code example demonstrates the use of PeekById(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.
System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

// Peek at the message.
msg = queue.PeekById(id);

.NET Framework
Available since 1.1
Return to top
Show: