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()