MessageQueue.ReceiveById 方法

参考

定义

命名空间:: System.Messaging

程序集:: System.Messaging.dll

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

接收匹配给定标识符的消息，并将其从队列中移除。

重载

ReceiveById(String)	从非事务性队列中接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。
ReceiveById(String, MessageQueueTransaction)	从事务性队列中接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。
ReceiveById(String, MessageQueueTransactionType)	接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。
ReceiveById(String, TimeSpan)	从非事务性队列接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。
ReceiveById(String, TimeSpan, MessageQueueTransaction)	从事务性队列接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。
ReceiveById(String, TimeSpan, MessageQueueTransactionType)	接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。

ReceiveById(String)

从非事务性队列中接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id);

public System.Messaging.Message ReceiveById (string id);

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

Public Function ReceiveById (id As String) As Message

参数

id: String

要接收的消息的 Id。

Message

Message，其 Id 属性匹配传入的 id 参数。

例外

ArgumentNullException

id 参数为 null。

InvalidOperationException

未能找到具有指定 id 的消息。

MessageQueueException

访问“消息队列”方法时出错。

示例

以下代码示例演示了 ReceiveById(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));

// Receive the message from the queue.
msg = queue->ReceiveById(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));

// Receive the message from the queue.
msg = queue.ReceiveById(id);

注解

使用此方法读取具有已知标识符的消息并将其从队列中删除。如果消息不在队列中，此方法将立即引发异常。

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。

另外两种方法可用于从队列接收消息。方法 Receive 返回队列中的第一条消息，该方法 ReceiveByCorrelationId(String) 用于检索由于发送到队列的消息而创建的确认、报告或应用程序生成的响应消息。

若要读取具有指定标识符的消息而不将其从队列中删除，请使用 PeekById(String) 方法。方法 PeekById(String) 始终返回队列中的第一条消息，因此对方法的后续调用将返回相同的消息，除非优先级较高的消息到达队列。

下表显示了此方法是否在各种工作组模式下可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

ReceiveById(String, MessageQueueTransaction)

从事务性队列中接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id, System::Messaging::MessageQueueTransaction ^ transaction);

public System.Messaging.Message ReceiveById (string id, System.Messaging.MessageQueueTransaction transaction);

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

Public Function ReceiveById (id As String, transaction As MessageQueueTransaction) As Message

参数

id: String

要接收的消息的 Id。

transaction: MessageQueueTransaction

MessageQueueTransaction 对象。

Message

Message，其 Id 属性匹配传入的 id 参数。

例外

ArgumentNullException

id 参数为 null。

- 或 -

transaction 参数为 null。

InvalidOperationException

未能找到具有指定 id 的消息。

MessageQueueException

该队列为非事务性队列。

- 或 -

访问“消息队列”方法时出错。

示例

以下代码示例演示了 ReceiveById(String, MessageQueueTransaction) 的用法。


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

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

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

// 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));

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

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

    // Receive the message from the queue.
    msg = queue->ReceiveById(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;
    queue->Close();
}


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

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

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

// 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));

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

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

    // Receive the message from the queue.
    msg = queue.ReceiveById(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();
}

注解

使用此方法读取具有已知标识符的消息，并使用参数定义的 transaction 内部事务上下文将其从队列中删除。如果消息不在队列中，此方法会立即引发异常

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。

由于此方法是在事务队列上调用的，因此如果事务中止，收到的消息将返回到队列。在提交事务之前，不会从队列中永久删除消息。

若要读取具有指定标识符的消息而不将其从队列中删除，请使用 PeekById(String) 方法。方法 PeekById(String) 始终返回队列中的第一条消息，因此对方法的后续调用将返回相同的消息，除非优先级较高的消息到达队列。没有与调用 PeekById(String)返回的消息关联的事务上下文。由于 PeekById(String) 不删除队列中的任何消息，因此如果中止事务，则不会回滚任何消息。

下表显示了此方法是否在各种工作组模式下可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

ReceiveById(String, MessageQueueTransactionType)

接收与给定的标识符匹配的消息，而且在队列中当前不存在具有指定标识符的消息时立即引发异常。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id, System::Messaging::MessageQueueTransactionType transactionType);

public System.Messaging.Message ReceiveById (string id, System.Messaging.MessageQueueTransactionType transactionType);

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

Public Function ReceiveById (id As String, transactionType As MessageQueueTransactionType) As Message

参数

id: String

要接收的消息的 Id。

transactionType: MessageQueueTransactionType

MessageQueueTransactionType 值之一，它描述与消息关联的事务上下文的类型。

Message

Message，其 Id 属性匹配传入的 id 参数。

例外

ArgumentNullException

id 参数为 null。

InvalidOperationException

未能找到具有指定 id 的消息。

InvalidEnumArgumentException

transactionType 参数不是 MessageQueueTransactionType 成员之一。

MessageQueueException

访问“消息队列”方法时出错。

示例

以下代码示例演示了 ReceiveById(String, MessageQueueTransactionType) 的用法。


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

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

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

// 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));

// Receive the message from the queue.
msg = queue->ReceiveById(id, MessageQueueTransactionType::Single);

queue->Close();


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

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

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

// 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));

// Receive the message from the queue.
msg = queue.ReceiveById(id, MessageQueueTransactionType.Single);

注解

使用此方法读取具有已知标识符的消息并将其从队列中删除。如果消息不在队列中，此方法将立即引发异常。否则，消息将从队列中删除，并使用参数定义的 transactionType 事务上下文返回到应用程序。

如果已将外部事务上下文附加到要用于接收消息的线程，请为 transactionType 参数指定 Automatic 。指定 Single 是否要以单个内部事务的形式接收消息。可以指定 None 是否要从事务上下文之外的事务队列接收消息。

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。如果具有指定标识符的消息位于与此实例关联的 MessageQueue 队列以外的队列中，则找不到该消息。

如果调用此方法以接收来自事务队列的消息，则如果中止事务，则收到的消息将返回到队列。在提交事务之前，不会从队列中永久删除消息。

下表显示了此方法是否在各种工作组模式下可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

ReceiveById(String, TimeSpan)

从非事务性队列接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id, TimeSpan timeout);

public System.Messaging.Message ReceiveById (string id, TimeSpan timeout);

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

Public Function ReceiveById (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。

MessageQueueException

在时间超时之前，带有指定 id 的消息没有到达队列。

- 或 -

访问“消息队列”方法时出错。

示例

以下代码示例演示了 ReceiveById(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;

// Receive the message from the queue.
msg = queue->ReceiveById(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;

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

注解

使用此方法可读取具有已知标识符的消息，并将其从队列中删除。如果具有参数指定的 id 标识符的消息在队列中，则此方法将立即返回。否则，方法将等待给定的时间段，以便新消息到达。如果新消息在超时到期之前未到达，则会引发异常。

参数 timeout 不指定此方法的总运行时间。而是指定等待新消息到达队列的时间。每当新消息到达时，此方法都会 Id 检查新消息的，以查看它是否与参数匹配 id 。否则，此方法将启动超时期限，并等待另一条新消息到达。因此，如果新消息在超时期限内继续到达，则此方法可能会无限期地继续运行，直到超时期限到期且没有任何新消息到达，或者直到到达与 Id 参数匹配 id 的消息。

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。

如果当前线程可以接受，只要新消息在参数指定的timeout超时期限内继续到达队列，则使用此重载ReceiveById(String)。如果为参数指定了值InfiniteTimeouttimeout，或者新消息在参数指定的timeout超时期限内继续到达队列中，线程将至少在给定的时间段内被无限期阻塞。

另外两种方法允许从队列接收消息。方法 Receive 返回队列中的第一条消息，该方法 ReceiveByCorrelationId(String) 用于检索确认、报告或应用程序生成的响应消息，该消息是作为发送到队列的消息而创建的。

若要读取具有指定标识符的消息而不将其从队列中删除，请使用 PeekById(String) 方法。方法 PeekById(String) 始终返回队列中的第一条消息，因此对方法的后续调用将返回相同的消息，除非队列中到达了更高优先级的消息。

下表显示了此方法在各种工作组模式下是否可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

ReceiveById(String, TimeSpan, MessageQueueTransaction)

从事务性队列接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id, TimeSpan timeout, System::Messaging::MessageQueueTransaction ^ transaction);

public System.Messaging.Message ReceiveById (string id, TimeSpan timeout, System.Messaging.MessageQueueTransaction transaction);

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

Public Function ReceiveById (id As String, timeout As TimeSpan, transaction As MessageQueueTransaction) As Message

参数

id: String

要接收的消息的 Id。

timeout: TimeSpan

一个 TimeSpan 指示有新消息可用于检查之前等待的时间。

transaction: MessageQueueTransaction

MessageQueueTransaction 对象。

Message

Message，其 Id 属性匹配传入的 id 参数。

例外

ArgumentNullException

id 参数为 null。

- 或 -

transaction 参数为 null。

ArgumentException

为 timeout 参数指定的值无效，可能是 timeout 小于 Zero 或大于 InfiniteTimeout。

MessageQueueException

在时间超时之前，带有指定 id 的消息没有到达队列。

- 或 -

该队列为非事务性队列。

- 或 -

访问“消息队列”方法时出错。

示例

以下代码示例演示了 ReceiveById(String, TimeSpan, MessageQueueTransaction) 的用法。


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

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

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

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

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

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

    // Receive the message from the queue.
    msg = queue->ReceiveById(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;
    queue->Close();
}


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

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

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

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

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

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

    // Receive the message from the queue.
    msg = queue.ReceiveById(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();
}

注解

使用此方法读取具有已知标识符的消息，并使用参数定义的 transaction 内部事务上下文将其从队列中删除。如果具有参数指定的 id 标识符的消息在队列中，则此方法将立即返回。否则，方法将等待给定的时间段，以便新消息到达。如果新消息在超时到期之前未到达，则会引发异常。

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。

如果当前线程可以接受，只要新消息在参数指定的timeout超时期限内继续到达队列，则使用此重载ReceiveById(String)。如果为参数指定了值InfiniteTimeouttimeout，或者新消息在参数指定的timeout超时期限内继续到达队列，线程将至少在给定的时间段内被无限期阻塞。

由于此方法是在事务队列上调用的，因此，如果事务中止，收到的消息将返回到队列。在提交事务之前，不会从队列中永久删除该消息。

若要读取具有指定标识符的消息而不将其从队列中删除，请使用 PeekById(String) 方法。方法 PeekById(String) 始终返回队列中的第一条消息，因此对方法的后续调用将返回相同的消息，除非队列中到达了更高优先级的消息。没有与调用 PeekById(String)返回的消息关联的事务上下文。由于 PeekById(String) 不会删除队列中的任何消息，因此，如果中止事务，则不会回滚任何消息。

下表显示了此方法在各种工作组模式下是否可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

ReceiveById(String, TimeSpan, MessageQueueTransactionType)

接收与给定的标识符匹配的消息，并且一直等到队列中出现具有指定标识符的消息或超时过期。

public:
 System::Messaging::Message ^ ReceiveById(System::String ^ id, TimeSpan timeout, System::Messaging::MessageQueueTransactionType transactionType);

public System.Messaging.Message ReceiveById (string id, TimeSpan timeout, System.Messaging.MessageQueueTransactionType transactionType);

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

Public Function ReceiveById (id As String, timeout As TimeSpan, transactionType As MessageQueueTransactionType) As Message

参数

id: String

要接收的消息的 Id。

timeout: TimeSpan

一个 TimeSpan 指示有新消息可用于检查之前等待的时间。

transactionType: MessageQueueTransactionType

MessageQueueTransactionType 值之一，它描述与消息关联的事务上下文的类型。

Message

Message，其 Id 属性匹配传入的 id 参数。

例外

ArgumentNullException

id 参数为 null。

ArgumentException

为 timeout 参数指定的值无效，可能是 timeout 小于 Zero 或大于 InfiniteTimeout。

MessageQueueException

在时间超时之前，带有指定 id 的消息没有到达队列。

- 或 -

访问“消息队列”方法时出错。

InvalidEnumArgumentException

transactionType 参数不是 MessageQueueTransactionType 成员之一。

示例

以下代码示例演示了 ReceiveById(String, TimeSpan, MessageQueueTransactionType) 的用法。


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

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

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

// 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),
    MessageQueueTransactionType::Single);

queue->Close();


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

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

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

// 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),
    MessageQueueTransactionType.Single);

注解

使用此方法可读取具有已知标识符的消息，并将其从队列中删除。如果使用由参数定义的transactionType事务上下文，具有参数指定的id标识符的消息位于队列中，则此方法将立即返回。否则，方法将等待给定的时间段，以便新消息到达。如果新消息在超时到期之前未到达，则会引发异常。

如果已将外部事务上下文附加到要用于接收消息的线程，则为 transactionType 参数指定 Automatic 。指定 Single 是否要以单个内部事务的形式接收消息。可以指定 None 是否要从事务上下文之外的事务队列接收消息。

Id消息的属性在消息队列企业中是唯一的，因此队列中最多会有一条消息与给定id参数匹配。如果具有指定标识符的消息位于队列中，而不是与此 MessageQueue 实例关联的队列，则找不到该消息。

如果调用此方法以接收来自事务队列的消息，则事务中止时收到的消息将返回到队列。在提交事务之前，不会从队列中永久删除该消息。

下表显示了此方法在各种工作组模式下是否可用。

工作组模式	可用
本地计算机	是
本地计算机和直接格式名称	是
远程计算机	否
远程计算机和直接格式名称	是

另请参阅

适用于

MessageQueue.ReceiveById 方法

定义

重载

ReceiveById(String)

参数

返回

例外

示例

注解

另请参阅

适用于

ReceiveById(String, MessageQueueTransaction)

参数

返回

例外

示例

注解

另请参阅

适用于

ReceiveById(String, MessageQueueTransactionType)

参数

返回

例外

示例

注解

另请参阅

适用于

ReceiveById(String, TimeSpan)

参数

返回

例外

示例

注解

另请参阅

适用于

ReceiveById(String, TimeSpan, MessageQueueTransaction)

参数

返回

例外

示例

注解

另请参阅

适用于

ReceiveById(String, TimeSpan, MessageQueueTransactionType)

参数

返回

例外

示例

注解

另请参阅

适用于

反馈

其他资源