MessageQueue.PeekById Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Returns a copy of the message that has the specified message identifier without removing the message from the queue.
Overloads
PeekById(String) |
Peeks the message whose message identifier matches the |
PeekById(String, TimeSpan) |
Peeks the message whose message identifier matches the |
PeekById(String)
Peeks the message whose message identifier matches the id
parameter.
public:
System::Messaging::Message ^ PeekById(System::String ^ id);
public System.Messaging.Message PeekById (string id);
member this.PeekById : string -> System.Messaging.Message
Public Function PeekById (id As String) As Message
Parameters
Returns
The Message whose Id property matches the id
parameter.
Exceptions
The id
parameter is null
.
No message with the specified id
exists.
An error occurred when accessing a Message Queuing method.
Examples
The following code example demonstrates the use of PeekById(String).
// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");
// Create a new message.
Message^ msg = gcnew 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);
queue->Close();
// 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);
Remarks
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 |
See also
Applies to
PeekById(String, TimeSpan)
Peeks the message whose message identifier matches the id
parameter. Waits until the message appears in the queue or a time-out occurs.
public:
System::Messaging::Message ^ PeekById(System::String ^ id, TimeSpan timeout);
public System.Messaging.Message PeekById (string id, TimeSpan timeout);
member this.PeekById : string * TimeSpan -> System.Messaging.Message
Public Function PeekById (id As String, timeout As TimeSpan) As Message
Parameters
- timeout
- TimeSpan
A TimeSpan that indicates the time to wait until a new message is available for inspection.
Returns
The Message whose Id property matches the id
parameter.
Exceptions
The id
parameter is null
.
The value specified for the timeout
parameter is not valid, possibly timeout
is less than Zero or greater than InfiniteTimeout.
The message with the specified id
does not exist in the queue and did not arrive before the period specified by the timeout
parameter expired.
An error occurred when accessing a Message Queuing method.
Examples
The following code example demonstrates the use of PeekById(String, TimeSpan).
// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");
// Create a new message.
Message^ msg = gcnew Message("Example Message Body");
// Send the message.
queue->Send(msg, "Example Message Label");
// Get the message's Id property value.
String^ id = msg->Id;
// Peek at the message.
msg = queue->PeekById(id, TimeSpan::FromSeconds(10.0));
queue->Close();
// 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;
// Peek at the message.
msg = queue.PeekById(id, TimeSpan.FromSeconds(10.0));
Remarks
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 and a new message does not arrive before the time-out occurs.
The timeout
parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the Id of the new message to see if it matches the id
parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose Id matches the id
parameter.
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 |
See also
Applies to
Tilbakemeldinger
https://aka.ms/ContentUserFeedback.
Kommer snart: Gjennom 2024 faser vi ut GitHub Issues som tilbakemeldingsmekanisme for innhold, og erstatter det med et nytt system for tilbakemeldinger. Hvis du vil ha mer informasjon, kan du se:Send inn og vis tilbakemelding for