MessageQueue.PeekById 方法

定義

命名空間:

System.Messaging

組件:

System.Messaging.dll

傳回具有指定訊息識別項的訊息複本，但不從佇列中移除訊息。

多載

PeekById(String)	窺視訊息識別項符合 id 參數的訊息。
PeekById(String, TimeSpan)	窺視訊息識別項符合 id 參數的訊息。 等待直到訊息出現在佇列中，或等到發生逾時。

PeekById(String)

窺視訊息識別項符合 id 參數的訊息。

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

要窺視訊息的 Id。

傳回

Message

Message 屬性符合 id 參數的 Id。

例外狀況

ArgumentNullException

id 參數為 null。

InvalidOperationException

具有指定 id 的訊息不存在。

MessageQueueException

存取訊息佇列方法時發生錯誤。

範例

下列程式碼範例示範 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) 讀取，而不從佇列中移除具有已知訊息標識碼的訊息。 訊息的標識碼在整個消息佇列企業中是唯一的，因此佇列中最多會有一個符合指定 id 參數的訊息。 如果佇列目前未包含訊息，此多載會擲回例外狀況。

兩個額外的方法可讓您查看佇列中的訊息： Peek 和 PeekByCorrelationId(String)。 方法 Peek 會傳回佇列中的第一個訊息; PeekByCorrelationId(String) 傳回通知、報告或應用程式產生的回應消息，這是傳送至佇列的訊息所產生。

下表顯示這個方法是否可在各種工作組模式中使用。

工作組模式	可用
本機電腦	是
本機計算機和直接格式名稱	是
遠端電腦	否
遠端電腦和直接格式名稱	是

另請參閱

• Id
• Peek()
• BeginPeek()

PeekById(String, TimeSpan)

窺視訊息識別項符合 id 參數的訊息。 等待直到訊息出現在佇列中，或等到發生逾時。

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

要窺視訊息的 Id。

timeout

TimeSpan

TimeSpan，指出等待新訊息可以進行檢查的時間。

傳回

Message

Message 屬性符合 id 參數的 Id。

例外狀況

ArgumentNullException

id 參數為 null。

ArgumentException

為 timeout 參數指定的值無效，可能是 timeout 小於 Zero 或大於 InfiniteTimeout。

InvalidOperationException

佇列中沒有具有指定 id 的訊息，且該訊息未在 timeout 參數指定的逾時到期前到達。

MessageQueueException

存取訊息佇列方法時發生錯誤。

範例

下列程式碼範例示範 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) 讀取，而不從佇列中移除具有已知訊息標識碼的訊息。 訊息的標識碼在整個消息佇列企業中是唯一的，因此佇列中最多會有一個符合指定 id 參數的訊息。 如果佇列目前未包含訊息，且新訊息在逾時發生之前未送達，此多載就會擲回例外狀況。

參數 timeout 未指定這個方法的總運行時間。 相反地，它會指定等候新訊息抵達佇列的時間。 每次新訊息送達時，這個方法都會 Id 檢查新訊息的 ，以查看它 id 是否符合 參數。 如果沒有，這個方法會開始逾時期間，並等候另一個新訊息送達。 因此，如果新訊息繼續在逾時期間內送達，則此方法可以無限期地繼續執行，直到逾時期間到期，而不會到達任何新訊息，或直到訊息到達符合 Id 參數的 id 訊息為止。

兩個額外的方法可讓您查看佇列中的訊息： Peek 和 PeekByCorrelationId(String)。 方法 Peek 會傳回佇列中的第一個訊息; PeekByCorrelationId(String) 傳回通知、報告或應用程式產生的回應消息，這是傳送至佇列的訊息所產生。

下表顯示這個方法是否可在各種工作組模式中使用。

工作組模式	可用
本機電腦	是
本機計算機和直接格式名稱	是
遠端電腦	否
遠端電腦和直接格式名稱	是

另請參閱

• InfiniteTimeout
• Id
• Peek()
• BeginPeek()