MessageQueue.PeekById 方法

定義

傳回具有指定訊息識別項的訊息複本,但不從佇列中移除訊息。Returns a copy of the message that has the specified message identifier without removing the message from the queue.

多載

PeekById(String)

窺視訊息識別項符合 id 參數的訊息。Peeks the message whose message identifier matches the id parameter.

PeekById(String, TimeSpan)

窺視訊息識別項符合 id 參數的訊息。Peeks the message whose message identifier matches the id parameter. 等待直到訊息出現在佇列中,或等到發生逾時。Waits until the message appears in the queue or a time-out occurs.

PeekById(String)

窺視訊息識別項符合 id 參數的訊息。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

參數

id
String

要窺視訊息的 IdThe Id of the message to peek.

傳回

Message

Message 屬性符合 id 參數的 IdThe Message whose Id property matches the id parameter.

例外狀況

id 參數為 nullThe id parameter is null.

具有指定 id 的訊息不存在。No message with the specified id exists.

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

範例

下列程式碼範例示範 PeekById(String) 的用法。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);

備註

使用 PeekById(String) 讀取,而不從佇列中移除,也就是具有已知訊息識別碼的訊息。Use PeekById(String) to read, without removing from the queue, a message that has a known message identifier. 訊息的識別碼在訊息佇列企業中是唯一的,因此佇列中最多隻會有一個訊息符合指定的 id 參數。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.

另外兩個方法可讓您查看佇列中的訊息: PeekPeekByCorrelationId(String)Two additional methods allow you to peek messages in a queue: Peek and PeekByCorrelationId(String). Peek方法會傳回佇列中的第一則訊息; 傳回 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

另請參閱

適用於

PeekById(String, TimeSpan)

窺視訊息識別項符合 id 參數的訊息。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

參數

id
String

要窺視訊息的 IdThe Id of the message to peek.

timeout
TimeSpan

TimeSpan,指出等待新訊息可以進行檢查的時間。A TimeSpan that indicates the time to wait until a new message is available for inspection.

傳回

Message

Message 屬性符合 id 參數的 IdThe Message whose Id property matches the id parameter.

例外狀況

id 參數為 nullThe id parameter is null.

timeout 參數指定的值無效,可能是 timeout 小於 Zero 或大於 InfiniteTimeoutThe value specified for the timeout parameter is not valid, possibly timeout is less than Zero or greater than InfiniteTimeout.

佇列中沒有具有指定 id 的訊息,且該訊息未在 timeout 參數指定的逾時到期前到達。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.

範例

下列程式碼範例示範 PeekById(String, TimeSpan) 的用法。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));

備註

使用 PeekById(String) 讀取,而不從佇列中移除,也就是具有已知訊息識別碼的訊息。Use PeekById(String) to read, without removing from the queue, a message that has a known message identifier. 訊息的識別碼在訊息佇列企業中是唯一的,因此佇列中最多隻會有一個訊息符合指定的 id 參數。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.

timeout此參數不會指定此方法的總執行時間。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. 每次新訊息抵達時,此方法會檢查 Id 新訊息的,以查看它是否符合 id 參數。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. 因此,如果新的訊息在超時期間內仍持續到達,則此方法可能會無限期地繼續執行,直到過期期間過期,而不會到達任何新訊息,或直到到達符合參數的訊息到達為止 Id idTherefore, 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.

另外兩個方法可讓您查看佇列中的訊息: PeekPeekByCorrelationId(String)Two additional methods allow you to peek messages in a queue: Peek and PeekByCorrelationId(String). Peek方法會傳回佇列中的第一則訊息; 傳回 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

另請參閱

適用於