MessageQueue.ReceiveByCorrelationId 方法

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId, TimeSpan timeout, System::Messaging::MessageQueueTransactionType transactionType);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId, TimeSpan timeout, System.Messaging.MessageQueueTransactionType transactionType);

member this.ReceiveByCorrelationId : string * TimeSpan * System.Messaging.MessageQueueTransactionType -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String, timeout As TimeSpan, transactionType As MessageQueueTransactionType) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

下列程式代碼範例示範 如何使用 ReceiveByCorrelationId(String, TimeSpan, MessageQueueTransactionType)。

// Connect to a nontransactional queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create a new message.
Message^ msg = gcnew Message("Example Message Body");

// Send the message to the nontransactional queue.
queue->Send(msg, "Example Message Label");

// Get the message's Id property value.
String^ id = msg->Id;

// Receive the message from the nontransactional queue.
msg = queue->ReceiveById(id, TimeSpan::FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue^ transQueue =
    gcnew MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message^ responseMsg = gcnew Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg->CorrelationId = id;

// Send the response message to the transactional queue.
transQueue->Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType::Single);

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue->MessageReadPropertyFilter->CorrelationId = true;

// Receive the response message from the transactional queue.
responseMsg = transQueue->ReceiveByCorrelationId(id,
    TimeSpan::FromSeconds(10.0), MessageQueueTransactionType::Single);

// Display the response message's property values.
Console::WriteLine("Message.Label: {0}", responseMsg->Label);
Console::WriteLine("Message.CorrelationId: {0}",
    responseMsg->CorrelationId);

transQueue->Close();
queue->Close();

// Connect to a nontransactional queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new message.
Message msg = new Message("Example Message Body");

// Send the message to the nontransactional queue.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Receive the message from the nontransactional queue.
msg = queue.ReceiveById(id, TimeSpan.FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue transQueue = new MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message responseMsg = new Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg.CorrelationId = id;

// Send the response message to the transactional queue.
transQueue.Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType.Single);

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue.MessageReadPropertyFilter.CorrelationId = true;

// Receive the response message from the transactional queue.
responseMsg = transQueue.ReceiveByCorrelationId(id,
    TimeSpan.FromSeconds(10.0), MessageQueueTransactionType.Single);

// Display the response message's property values.
Console.WriteLine("Message.Label: {0}", responseMsg.Label);
Console.WriteLine("Message.CorrelationId: {0}",
    responseMsg.CorrelationId);

備註

此方法會從 所參考MessageQueue的隊列中尋找符合指定CorrelationId參數的訊息correlationId。 如果使用 correlationId 參數所定義的交易內容，transactionType 參數所指定的相互關聯標識元訊息會立即傳回。 否則，方法會等待指定時間等待新訊息抵達。 若逾時期內未收到新訊息，則會拋出例外。

該 timeout 參數未指定此方法的總執行時間。 它指定等待新訊息到達隊列的時間。 每當有新訊息抵達時，此方法會檢查該訊息的參數CorrelationId是否符合。correlationId 若未完成，則重新開始逾時，等待另一則新訊息抵達。 因此，如果在逾時期內持續有新訊息抵達，這個方法有可能無限期地持續運行，無論是直到逾時期結束且沒有新訊息到達，或直到收到符合 CorrelationId 參數的 correlationId 訊息。 請指定AutomatictransactionType參數，是否已經連接到你想用來接收訊息的執行緒。 請指定 Single 你是否想將訊息作為單一內部交易接收。 你可以指定 None 是否想在交易上下文外接收來自交易隊列的訊息。

若呼叫此方法以接收交易佇列中的訊息，交易中止時，收到的訊息會被回傳至佇列。 在交易提交之前，訊息不會永久從佇列中移除。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 該 Receive 方法會回傳佇列中的第一個訊息，並 ReceiveById(String) 透過指定訊息的唯一識別碼來取得訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。 呼叫回 PeekByCorrelationId(String)傳的訊息沒有交易上下文。 由於 PeekByCorrelationId(String) 不會移除佇列中的任何訊息，如果交易被中止，就沒有什麼可以回滾的。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• MessageQueueTransactionType
• Transactional
• Receive()
• Peek()
• BeginReceive()

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId, TimeSpan timeout, System::Messaging::MessageQueueTransaction ^ transaction);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId, TimeSpan timeout, System.Messaging.MessageQueueTransaction transaction);

member this.ReceiveByCorrelationId : string * TimeSpan * System.Messaging.MessageQueueTransaction -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String, timeout As TimeSpan, transaction As MessageQueueTransaction) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

下列程式代碼範例示範 如何使用 ReceiveByCorrelationId(String, TimeSpan, MessageQueueTransaction)。

// Connect to a nontransactional queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create a new message.
Message^ msg = gcnew Message("Example Message Body");

// Send the message to the nontransactional queue.
queue->Send(msg, "Example Message Label");

// Get the message's Id property value.
String^ id = msg->Id;

// Receive the message from the nontransactional queue.
msg = queue->ReceiveById(id, TimeSpan::FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue^ transQueue =
    gcnew MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message^ responseMsg = gcnew Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg->CorrelationId = id;

// Send the response message to the transactional queue.
transQueue->Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType::Single);

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue->MessageReadPropertyFilter->CorrelationId = true;

// Create a message queuing transaction.
MessageQueueTransaction^ transaction = gcnew MessageQueueTransaction();

try
{
    // Begin a transaction.
    transaction->Begin();

    // Receive the response message from the transactional queue.
    responseMsg = transQueue->ReceiveByCorrelationId(id,
        TimeSpan::FromSeconds(10.0), transaction);

    // Commit the transaction.
    transaction->Commit();
}
catch (Exception^ ex)
{
    // Cancel the transaction.
    transaction->Abort();

    // Propagate the exception.
    throw ex;
}
finally
{
    // Dispose of the transaction object.
    delete transaction;
    transQueue->Close();
    queue->Close();
}

// Display the response message's property values.
Console::WriteLine("Message.Label: {0}", responseMsg->Label);
Console::WriteLine("Message.CorrelationId: {0}",
    responseMsg->CorrelationId);

// Connect to a nontransactional queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new message.
Message msg = new Message("Example Message Body");

// Send the message to the nontransactional queue.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Receive the message from the nontransactional queue.
msg = queue.ReceiveById(id, TimeSpan.FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue transQueue = new MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message responseMsg = new Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg.CorrelationId = id;

// Send the response message to the transactional queue.
transQueue.Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType.Single);

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue.MessageReadPropertyFilter.CorrelationId = true;

// Create a message queuing transaction.
MessageQueueTransaction transaction = new MessageQueueTransaction();

try
{
    // Begin a transaction.
    transaction.Begin();

    // Receive the response message from the transactional queue.
    responseMsg = transQueue.ReceiveByCorrelationId(id,
        TimeSpan.FromSeconds(10.0), transaction);

    // Commit the transaction.
    transaction.Commit();
}
catch (System.Exception e)
{
    // Cancel the transaction.
    transaction.Abort();

    // Propagate the exception.
    throw e;
}
finally
{
    // Dispose of the transaction object.
    transaction.Dispose();
}

// Display the response message's property values.
Console.WriteLine("Message.Label: {0}", responseMsg.Label);
Console.WriteLine("Message.CorrelationId: {0}",
    responseMsg.CorrelationId);

備註

這個方法會在 MessageQueue 所參考的交易佇列中尋找 CorrelationId 符合指定之 correlationId 參數的訊息。 如果使用 correlationId 參數所定義的內部交易內容，transaction 參數所指定的相互關聯標識符訊息會立即傳回。 否則，方法會等待指定時間等待新訊息抵達。 若逾時期內未收到新訊息，則會拋出例外。

該 timeout 參數未指定此方法的總執行時間。 它指定等待新訊息到達隊列的時間。 每當有新訊息抵達時，此方法會檢查該訊息的參數CorrelationId是否符合。correlationId 若未完成，則重新開始逾時，等待另一則新訊息抵達。 因此，如果在逾時期內持續有新訊息抵達，這個方法有可能無限期地持續運行，無論是直到逾時期結束且沒有新訊息到達，或直到收到符合 CorrelationId 參數的 correlationId 訊息。

由於此方法是在交易佇列中呼叫，若交易中止，收到的訊息會被回傳至佇列。 在交易提交之前，訊息不會永久從佇列中移除。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 該 Receive 方法會回傳佇列中的第一個訊息，並 ReceiveById(String) 透過指定訊息的唯一識別碼來取得訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。 呼叫回 PeekByCorrelationId(String)傳的訊息沒有交易上下文。 由於 PeekByCorrelationId(String) 不會移除佇列中的任何訊息，如果交易被中止，就沒有什麼可以回滾的。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• MessageQueueTransaction
• Transactional
• InfiniteTimeout
• Receive()
• Peek()
• BeginReceive()

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId, TimeSpan timeout);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId, TimeSpan timeout);

member this.ReceiveByCorrelationId : string * TimeSpan -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String, timeout As TimeSpan) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

下列程式代碼範例示範 如何使用 ReceiveByCorrelationId(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");

// Designate a queue to receive the acknowledgement message for this
// message.
msg->AdministrationQueue =
    gcnew MessageQueue(".\\exampleAdminQueue");

// Set the message to generate an acknowledgement message upon its
// arrival.
msg->AcknowledgeType = AcknowledgeTypes::PositiveArrival;

// Send the message.
queue->Send(msg, "Example Message Label");

// Get the message's Id property value.
String^ id = msg->Id;

// Receive the message from the queue.
msg = queue->ReceiveById(id, TimeSpan::FromSeconds(10.0));

// Connect to the admin queue.
MessageQueue^ adminQueue =
    gcnew MessageQueue(".\\exampleAdminQueue");

// Set the admin queue's MessageReadPropertyFilter property to ensure
// that the acknowledgement message includes the desired properties.
adminQueue->MessageReadPropertyFilter->Acknowledgment = true;
adminQueue->MessageReadPropertyFilter->CorrelationId = true;

// Receive the acknowledgement message from the admin queue.
Message^ ackMsg = adminQueue->ReceiveByCorrelationId(id,
    TimeSpan::FromSeconds(10.0));

// Display the acknowledgement message's property values.
Console::WriteLine("Message.Label: {0}", ackMsg->Label);
Console::WriteLine("Message.Acknowledgment: {0}",
    ackMsg->Acknowledgment);
Console::WriteLine("Message.CorrelationId: {0}", ackMsg->CorrelationId);

adminQueue->Close();
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");

// Designate a queue to receive the acknowledgement message for this
// message.
msg.AdministrationQueue = new MessageQueue(".\\exampleAdminQueue");

// Set the message to generate an acknowledgement message upon its
// arrival.
msg.AcknowledgeType = AcknowledgeTypes.PositiveArrival;

// Send the message.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Receive the message from the queue.
msg = queue.ReceiveById(id, TimeSpan.FromSeconds(10.0));

// Connect to the admin queue.
MessageQueue adminQueue = new MessageQueue(".\\exampleAdminQueue");

// Set the admin queue's MessageReadPropertyFilter property to ensure
// that the acknowledgement message includes the desired properties.
adminQueue.MessageReadPropertyFilter.Acknowledgment = true;
adminQueue.MessageReadPropertyFilter.CorrelationId = true;

// Receive the acknowledgement message from the admin queue.
Message ackMsg = adminQueue.ReceiveByCorrelationId(id,
    TimeSpan.FromSeconds(10.0));

// Display the acknowledgement message's property values.
Console.WriteLine("Message.Label: {0}", ackMsg.Label);
Console.WriteLine("Message.Acknowledgment: {0}", ackMsg.Acknowledgment);
Console.WriteLine("Message.CorrelationId: {0}", ackMsg.CorrelationId);

備註

此方法會在 MessageQueue 所參考的非交易式佇列中，尋找 CorrelationId 符合指定之 correlationId 參數的訊息。 如果具有 correlationId 參數所指定相互關聯標識符的訊息在佇列中，這個方法會立即傳回。 否則，方法會等待指定時間等待新訊息抵達。 若逾時期內未收到新訊息，則會拋出例外。

該 timeout 參數未指定此方法的總執行時間。 它指定等待新訊息到達隊列的時間。 每當有新訊息抵達時，此方法會檢查該訊息的參數CorrelationId是否符合。correlationId 若未完成，則重新開始逾時，等待另一則新訊息抵達。 因此，如果在逾時期內持續有新訊息抵達，這個方法有可能無限期地持續運行，無論是直到逾時期結束且沒有新訊息到達，或直到收到符合 CorrelationId 參數的 correlationId 訊息。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 該 Receive 方法會回傳佇列中的第一個訊息，並 ReceiveById(String) 透過指定訊息的唯一識別碼來取得訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• InfiniteTimeout
• Receive()
• Peek()
• BeginReceive()

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId, System::Messaging::MessageQueueTransactionType transactionType);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId, System.Messaging.MessageQueueTransactionType transactionType);

member this.ReceiveByCorrelationId : string * System.Messaging.MessageQueueTransactionType -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String, transactionType As MessageQueueTransactionType) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

下列程式代碼範例示範 如何使用 ReceiveByCorrelationId(String, MessageQueueTransactionType)。

// Connect to a nontransactional queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create a new message.
Message^ msg = gcnew Message("Example Message Body");

// Send the message to the nontransactional queue.
queue->Send(msg, "Example Message Label");

// Get the message's Id property value.
String^ id = msg->Id;

// Receive the message from the nontransactional queue.
msg = queue->ReceiveById(id, TimeSpan::FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue^ transQueue =
    gcnew MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message^ responseMsg = gcnew Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg->CorrelationId = id;

// Send the response message to the transactional queue.
transQueue->Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType::Single);

// Simulate doing other work so the message has time to arrive.
System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue->MessageReadPropertyFilter->CorrelationId = true;

// Receive the response message from the transactional queue.
responseMsg = transQueue->ReceiveByCorrelationId(id,
    MessageQueueTransactionType::Single);

// Display the response message's property values.
Console::WriteLine("Message.Label: {0}", responseMsg->Label);
Console::WriteLine("Message.CorrelationId: {0}",
    responseMsg->CorrelationId);

transQueue->Close();
queue->Close();

// Connect to a nontransactional queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new message.
Message msg = new Message("Example Message Body");

// Send the message to the nontransactional queue.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Receive the message from the nontransactional queue.
msg = queue.ReceiveById(id, TimeSpan.FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue transQueue = new MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message responseMsg = new Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg.CorrelationId = id;

// Send the response message to the transactional queue.
transQueue.Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType.Single);

// Simulate doing other work so the message has time to arrive.
System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue.MessageReadPropertyFilter.CorrelationId = true;

// Receive the response message from the transactional queue.
responseMsg = transQueue.ReceiveByCorrelationId(id,
    MessageQueueTransactionType.Single);

// Display the response message's property values.
Console.WriteLine("Message.Label: {0}", responseMsg.Label);
Console.WriteLine("Message.CorrelationId: {0}",
    responseMsg.CorrelationId);

備註

此方法會從 所參考MessageQueue的隊列中尋找符合指定CorrelationId參數的訊息correlationId。 若未找到符合參數的 correlationID 訊息，則會拋出例外。 否則，訊息會從佇列中移除，並透過參數定義 transactionType 的交易上下文返回給應用程式。

請指定AutomatictransactionType參數，是否已經連接到你想用來接收訊息的執行緒。 請指定 Single 你是否想將訊息作為單一內部交易接收。 你可以指定 None 是否想在交易上下文外接收來自交易隊列的訊息。

若呼叫此方法以接收交易佇列中的訊息，交易中止時，收到的訊息會被回傳至佇列。 在交易提交之前，訊息不會永久從佇列中移除。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 該 Receive 方法會回傳佇列中的第一個訊息，並 ReceiveById(String) 透過指定訊息的唯一識別碼來取得訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。 呼叫回 PeekByCorrelationId(String)傳的訊息沒有交易上下文。 由於 PeekByCorrelationId(String) 不會移除佇列中的任何訊息，如果交易被中止，就沒有什麼可以回滾的。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• MessageQueueTransactionType
• Transactional
• Receive()
• Peek()
• BeginReceive()

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId, System::Messaging::MessageQueueTransaction ^ transaction);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId, System.Messaging.MessageQueueTransaction transaction);

member this.ReceiveByCorrelationId : string * System.Messaging.MessageQueueTransaction -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String, transaction As MessageQueueTransaction) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

下列程式代碼範例示範 如何使用 ReceiveByCorrelationId(String, MessageQueueTransaction)。

// Connect to a nontransactional queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create a new message.
Message^ msg = gcnew Message("Example Message Body");

// Send the message to the nontransactional queue.
queue->Send(msg, "Example Message Label");

// Get the message's Id property value.
String^ id = msg->Id;

// Receive the message from the nontransactional queue.
msg = queue->ReceiveById(id, TimeSpan::FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue^ transQueue =
    gcnew MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message^ responseMsg = gcnew Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg->CorrelationId = id;

// Send the response message to the transactional queue.
transQueue->Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType::Single);

// Simulate doing other work so the message has time to arrive.
System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue->MessageReadPropertyFilter->CorrelationId = true;

// Create a message queuing transaction.
MessageQueueTransaction^ transaction = gcnew MessageQueueTransaction();

try
{
    // Begin a transaction.
    transaction->Begin();

    // Receive the response message from the transactional queue.
    responseMsg = transQueue->ReceiveByCorrelationId(id, transaction);

    // Commit the transaction.
    transaction->Commit();
}
catch (Exception^ ex)
{
    // Cancel the transaction.
    transaction->Abort();

    // Propagate the exception.
    throw ex;
}
finally
{
    // Dispose of the transaction object.
    delete transaction;
    transQueue->Close();
    queue->Close();
}

// Display the response message's property values.
Console::WriteLine("Message.Label: {0}", responseMsg->Label);
Console::WriteLine("Message.CorrelationId: {0}",
    responseMsg->CorrelationId);

// Connect to a nontransactional queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new message.
Message msg = new Message("Example Message Body");

// Send the message to the nontransactional queue.
queue.Send(msg, "Example Message Label");

// Get the message's Id property value.
string id = msg.Id;

// Receive the message from the nontransactional queue.
msg = queue.ReceiveById(id, TimeSpan.FromSeconds(10.0));

// Connect to a transactional queue on the local computer.
MessageQueue transQueue = new MessageQueue(".\\exampleTransQueue");

// Create a new message in response to the original message.
Message responseMsg = new Message("Example Response Message Body");

// Set the response message's CorrelationId property value to the Id
// property value of the original message.
responseMsg.CorrelationId = id;

// Send the response message to the transactional queue.
transQueue.Send(responseMsg, "Example Response Message Label",
    MessageQueueTransactionType.Single);

// Simulate doing other work so the message has time to arrive.
System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

// Set the transactional queue's MessageReadPropertyFilter property to
// ensure that the response message includes the desired properties.
transQueue.MessageReadPropertyFilter.CorrelationId = true;

// Create a message queuing transaction.
MessageQueueTransaction transaction = new MessageQueueTransaction();

try
{
    // Begin a transaction.
    transaction.Begin();

    // Receive the response message from the transactional queue.
    responseMsg = transQueue.ReceiveByCorrelationId(id, transaction);

    // Commit the transaction.
    transaction.Commit();
}
catch (System.Exception e)
{
    // Cancel the transaction.
    transaction.Abort();

    // Propagate the exception.
    throw e;
}
finally
{
    // Dispose of the transaction object.
    transaction.Dispose();
}

// Display the response message's property values.
Console.WriteLine("Message.Label: {0}", responseMsg.Label);
Console.WriteLine("Message.CorrelationId: {0}",
    responseMsg.CorrelationId);

備註

這個方法會在 MessageQueue 所參考的交易佇列中尋找 CorrelationId 符合指定之 correlationId 參數的訊息。 若未找到符合參數的 correlationID 訊息，則會拋出例外。 否則，訊息會從佇列中移除，並使用 transaction 參數所定義的內部交易內容傳回給應用程式。

由於此方法是在交易佇列中呼叫，若交易中止，收到的訊息會被回傳至佇列。 在交易提交之前，訊息不會永久從佇列中移除。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 該 Receive 方法會回傳佇列中的第一個訊息，並 ReceiveById(String) 透過指定訊息的唯一識別碼來取得訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。 呼叫回 PeekByCorrelationId(String)傳的訊息沒有交易上下文。 由於 PeekByCorrelationId(String) 不會移除佇列中的任何訊息，如果交易被中止，就沒有什麼可以回滾的。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• MessageQueueTransaction
• Transactional
• Receive()
• Peek()
• BeginReceive()

public:
 System::Messaging::Message ^ ReceiveByCorrelationId(System::String ^ correlationId);

public System.Messaging.Message ReceiveByCorrelationId(string correlationId);

member this.ReceiveByCorrelationId : string -> System.Messaging.Message

Public Function ReceiveByCorrelationId (correlationId As String) As Message

參數

傳回

Whose Message 與CorrelationId通過的參數相符correlationId。

例外狀況

範例

以下程式碼範例發送與接收包含與隊列指令的訊息。 當原始訊息到達或從佇列中取得時，會特別請求正面確認。

#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;
ref class MyNewQueue
{
public:
   static void CreateQueue( String^ queuePath )
   {
      try
      {
         if (  !MessageQueue::Exists( queuePath ) )
         {
            MessageQueue::Create( queuePath );
         }
         else
         {
            Console::WriteLine(  "{0} already exists.", queuePath );
         }
      }
      catch ( MessageQueueException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

   }

   void SendMessage()
   {
      // Connect to a queue on the local computer.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );

      // Create a new message.
      Message^ myMessage = gcnew Message( "Original Message" );
      myMessage->AdministrationQueue = gcnew MessageQueue( ".\\myAdministrationQueue" );
      myMessage->AcknowledgeType = (AcknowledgeTypes)(AcknowledgeTypes::PositiveReceive | AcknowledgeTypes::PositiveArrival);

      // Send the Order to the queue.
      myQueue->Send( myMessage );
      return;
   }

   String^ ReceiveMessage()
   {
      // Connect to the a queue on the local computer.
      MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
      myQueue->MessageReadPropertyFilter->CorrelationId = true;
      array<Type^>^p = gcnew array<Type^>(1);
      p[ 0 ] = String::typeid;
      myQueue->Formatter = gcnew XmlMessageFormatter( p );
      String^ returnString = nullptr;
      try
      {
         // Receive and format the message. 
         Message^ myMessage = myQueue->Receive();

         // Display message information.
         Console::WriteLine( "____________________________________________" );
         Console::WriteLine( "Original message information--" );
         Console::WriteLine( "Body: {0}", myMessage->Body );
         Console::WriteLine( "Id: {0}", myMessage->Id );
         Console::WriteLine( "____________________________________________" );
         returnString = myMessage->Id;
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle Message Queuing exceptions.
      }
      // Handle invalid serialization format.
      catch ( InvalidOperationException^ e ) 
      {
         Console::WriteLine( e->Message );
      }

      // Catch other exceptions as necessary.
      return returnString;
   }

   void ReceiveAcknowledgment( String^ messageId, String^ queuePath )
   {
      bool found = false;
      MessageQueue^ queue = gcnew MessageQueue( queuePath );
      queue->MessageReadPropertyFilter->CorrelationId = true;
      queue->MessageReadPropertyFilter->Acknowledgment = true;
      try
      {
         while ( queue->PeekByCorrelationId( messageId ) != nullptr )
         {
            Message^ myAcknowledgmentMessage = queue->ReceiveByCorrelationId( messageId );

            // Output acknowledgment message information. The correlation Id is identical
            // to the id of the original message.
            Console::WriteLine( "Acknowledgment Message Information--" );
            Console::WriteLine( "Correlation Id: {0}", myAcknowledgmentMessage->CorrelationId );
            Console::WriteLine( "Id: {0}", myAcknowledgmentMessage->Id );
            Console::WriteLine( "Acknowledgment Type: {0}", myAcknowledgmentMessage->Acknowledgment );
            Console::WriteLine( "____________________________________________" );
            found = true;
         }
      }
      catch ( InvalidOperationException^ e ) 
      {
         // This exception would be thrown if there is no (further) acknowledgment message
         // with the specified correlation Id. Only output a message if there are no messages;
         // not if the loop has found at least one.
         if ( !found )
         {
            Console::WriteLine( e->Message );
         }

         // Handle other causes of invalid operation exception.
      }

   }

};

int main()
{
   // Create a new instance of the class.
   MyNewQueue^ myNewQueue = gcnew MyNewQueue;

   // Create new queues.
   MyNewQueue::CreateQueue( ".\\myQueue" );
   MyNewQueue::CreateQueue( ".\\myAdministrationQueue" );

   // Send messages to a queue.
   myNewQueue->SendMessage();

   // Receive messages from a queue.
   String^ messageId = myNewQueue->ReceiveMessage();

   // Receive acknowledgment message.
   if ( messageId != nullptr )
   {
      myNewQueue->ReceiveAcknowledgment( messageId, ".\\myAdministrationQueue" );
   }

   return 0;
}

using System;
using System.Messaging;

namespace MyProject
{

    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example sends and receives a message from
        // a queue.
        //**************************************************

        public static void Main()
        {
            // Create a new instance of the class.
            MyNewQueue myNewQueue = new MyNewQueue();

            // Create new queues.
            CreateQueue(".\\myQueue");
            CreateQueue(".\\myAdministrationQueue");

            // Send messages to a queue.
            myNewQueue.SendMessage();

            // Receive messages from a queue.
            string messageId = myNewQueue.ReceiveMessage();

            // Receive acknowledgment message.
            if(messageId != null)
            {
                myNewQueue.ReceiveAcknowledgment(messageId, ".\\myAdministrationQueue");
            }

            return;
        }

        //**************************************************
        // Creates a new queue.
        //**************************************************

        public static void CreateQueue(string queuePath)
        {
            try	
            {
                if(!MessageQueue.Exists(queuePath))
                {
                    MessageQueue.Create(queuePath);
                }
                else
                {
                    Console.WriteLine(queuePath + " already exists.");
                }
            }
            catch (MessageQueueException e)
            {
                Console.WriteLine(e.Message);
            }
        }

        //**************************************************
        // Sends a string message to a queue.
        //**************************************************
        
        public void SendMessage()
        {

            // Connect to a queue on the local computer.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");

            // Create a new message.
            Message myMessage = new Message("Original Message");

            myMessage.AdministrationQueue = new MessageQueue(".\\myAdministrationQueue");
            myMessage.AcknowledgeType = AcknowledgeTypes.PositiveReceive | AcknowledgeTypes.PositiveArrival;

            // Send the Order to the queue.
            myQueue.Send(myMessage);

            return;
        }

        //**************************************************
        // Receives a message containing an Order.
        //**************************************************
        
        public  string ReceiveMessage()
        {
            // Connect to the a queue on the local computer.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");

            myQueue.MessageReadPropertyFilter.CorrelationId = true;

            // Set the formatter to indicate body contains an Order.
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(string)});

            string returnString = null;
            
            try
            {
                // Receive and format the message.
                Message myMessage =	myQueue.Receive();

                // Display message information.
                Console.WriteLine("____________________________________________");
                Console.WriteLine("Original message information--");
                Console.WriteLine("Body: " +myMessage.Body.ToString());
                Console.WriteLine("Id: " + myMessage.Id.ToString());
                Console.WriteLine("____________________________________________");

                returnString =  myMessage.Id;
            }
            
            catch (MessageQueueException)
            {
                // Handle Message Queuing exceptions.
            }

            // Handle invalid serialization format.
            catch (InvalidOperationException e)
            {
                Console.WriteLine(e.Message);
            }
            
            // Catch other exceptions as necessary.

            return returnString;
        }

        //**************************************************
        // Receives a message containing an Order.
        //**************************************************
        
        public void ReceiveAcknowledgment(string messageId, string queuePath)
        {
            bool found = false;
            MessageQueue queue = new MessageQueue(queuePath);
            queue.MessageReadPropertyFilter.CorrelationId = true;
            queue.MessageReadPropertyFilter.Acknowledgment = true;

            try
            {
                while(queue.PeekByCorrelationId(messageId) != null)
                {
                    Message myAcknowledgmentMessage = queue.ReceiveByCorrelationId(messageId);
            
                    // Output acknowledgment message information. The correlation Id is identical
                    // to the id of the original message.
                    Console.WriteLine("Acknowledgment Message Information--");
                    Console.WriteLine("Correlation Id: " + myAcknowledgmentMessage.CorrelationId.ToString());
                    Console.WriteLine("Id: " + myAcknowledgmentMessage.Id.ToString());
                    Console.WriteLine("Acknowledgment Type: " + myAcknowledgmentMessage.Acknowledgment.ToString());
                    Console.WriteLine("____________________________________________");

                    found = true;
                }
            }
            catch (InvalidOperationException e)
            {
                // This exception would be thrown if there is no (further) acknowledgment message
                // with the specified correlation Id. Only output a message if there are no messages;
                // not if the loop has found at least one.
                if (!found)
                {	
                    Console.WriteLine(e.Message);
                }

                // Handle other causes of invalid operation exception.
            }
        }
    }
}

Imports System.Messaging


' Provides a container class for the example.

Public Class MyNewQueue
   
   

   ' Provides an entry point into the application.       
   ' This example sends and receives a message from
   ' a queue.
      
   Public Shared Sub Main()
         ' Create a new instance of the class.
         Dim myNewQueue As New MyNewQueue()
         
         ' Create new queues.
         CreateQueue(".\myQueue")
         CreateQueue(".\myAdministrationQueue")
         
         ' Send messages to a queue.
         myNewQueue.SendMessage()
         
         ' Receive messages from a queue.
         Dim messageId As String = myNewQueue.ReceiveMessage()
         
         ' Receive acknowledgment message.
         If Not (messageId Is Nothing) Then
            myNewQueue.ReceiveAcknowledgment(messageId, ".\myAdministrationQueue")
         End If
         
         Return
   End Sub
      
      
      ' Creates a new queue.

   Public Shared Sub CreateQueue(queuePath As String)
         Try
            If Not MessageQueue.Exists(queuePath) Then
               MessageQueue.Create(queuePath)
            Else
               Console.WriteLine((queuePath + " already exists."))
            End If
         Catch e As MessageQueueException
            Console.WriteLine(e.Message)
         End Try
   End Sub
       
      
      
 
      ' Sends a string message to a queue.
 
   Public Sub SendMessage()
         
         ' Connect to a queue on the local computer.
         Dim myQueue As New MessageQueue(".\myQueue")
         
         ' Create a new message.
         Dim myMessage As New Message("Original Message")
         
         myMessage.AdministrationQueue = New MessageQueue(".\myAdministrationQueue")
         myMessage.AcknowledgeType = AcknowledgeTypes.PositiveReceive Or AcknowledgeTypes.PositiveArrival
         
         ' Send the Order to the queue.
         myQueue.Send(myMessage)
         
         Return
   End Sub
      
      
      
 
      ' Receives a message containing an Order.
 
   Public Function ReceiveMessage() As String
         ' Connect to the a queue on the local computer.
         Dim myQueue As New MessageQueue(".\myQueue")
         
         myQueue.MessageReadPropertyFilter.CorrelationId = True
         
         
         ' Set the formatter to indicate body contains an Order.
         myQueue.Formatter = New XmlMessageFormatter(New Type() {GetType(String)})
         
         Dim returnString As String = Nothing
         
         Try
            ' Receive and format the message. 
            Dim myMessage As Message = myQueue.Receive()
            
            
            ' Display message information.
            Console.WriteLine("____________________________________________")
            Console.WriteLine("Original message information--")
            Console.WriteLine(("Body: " + myMessage.Body.ToString()))
            Console.WriteLine(("Id: " + myMessage.Id.ToString()))
            Console.WriteLine("____________________________________________")
            
            returnString = myMessage.Id
         
         
                  
         ' Handle invalid serialization format.
         Catch e As InvalidOperationException
            Console.WriteLine(e.Message)
         End Try
         
         ' Catch other exceptions as necessary.
         Return returnString
   End Function 'ReceiveMessage
      
      
 
      ' Receives a message containing an Order.
 
   Public Sub ReceiveAcknowledgment(messageId As String, queuePath As String)
         Dim found As Boolean = False
         Dim queue As New MessageQueue(queuePath)
         queue.MessageReadPropertyFilter.CorrelationId = True
         queue.MessageReadPropertyFilter.Acknowledgment = True
         
         Try
            While Not (queue.PeekByCorrelationId(messageId) Is Nothing)
               Dim myAcknowledgmentMessage As Message = queue.ReceiveByCorrelationId(messageId)
               
               ' Output acknowledgment message information. The correlation Id is identical
               ' to the id of the original message.
               Console.WriteLine("Acknowledgment Message Information--")
               Console.WriteLine(("Correlation Id: " + myAcknowledgmentMessage.CorrelationId.ToString()))
               Console.WriteLine(("Id: " + myAcknowledgmentMessage.Id.ToString()))
               Console.WriteLine(("Acknowledgment Type: " + myAcknowledgmentMessage.Acknowledgment.ToString()))
               Console.WriteLine("____________________________________________")
               
               found = True
            End While
         Catch e As InvalidOperationException
            ' This exception would be thrown if there is no (further) acknowledgment message
            ' with the specified correlation Id. Only output a message if there are no messages;
            ' not if the loop has found at least one.
            If found = False Then
               Console.WriteLine(e.Message)
            End If
         End Try 
   End Sub
 End Class

備註

此方法會在 MessageQueue 所參考的非交易式佇列中，尋找 CorrelationId 符合指定之 correlationId 參數的訊息。 若未找到符合參數的 correlationID 訊息，則會拋出例外。 否則，訊息會從佇列中移除，並傳回至應用程式。

此 CorrelationId 屬性用於將發送到佇列的訊息與相關的回應、報告或確認訊息綁定。

另外兩種方法可以讓你從佇列中接收訊息。 Receive 方法會傳回佇列中的第一個訊息，而 ReceiveById(String) 方法會藉由指定其唯一標識符來擷取訊息。

若要讀取具有指定相互關聯標識碼的訊息，而不需從佇列中移除它，請使用 PeekByCorrelationId(String) 方法。 該 PeekByCorrelationId(String) 方法總是回傳佇列中的第一個訊息，因此後續呼叫該方法也會回傳相同的訊息，除非佇列中有更高優先權的訊息。

下表顯示此方法是否可在多種工作群組模式中使用。

另請參閱

• Receive()
• Peek()
• BeginReceive()