Partilhar via

MessageQueue.ReceiveById Método

  • Referência

Definição

Namespace:
System.Messaging
Assembly:
System.Messaging.dll

Recebe a mensagem que corresponde ao identificador especificado, removendo-a da fila.

Sobrecargas

ReceiveById(String)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila não transacional) e gera uma exceção imediatamente se nenhuma mensagem com o identificador existe atualmente na fila.
ReceiveById(String, MessageQueueTransaction)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila transacional) e gera uma exceção imediatamente se nenhuma mensagem com o identificador existe atualmente na fila.
ReceiveById(String, MessageQueueTransactionType)

Recebe a mensagem que corresponde ao identificador especificado e gerará imediatamente uma exceção se nenhuma mensagem com o identificador especificado existir atualmente na fila.
ReceiveById(String, TimeSpan)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila não transacional) e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.
ReceiveById(String, TimeSpan, MessageQueueTransaction)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila transacional) e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.
ReceiveById(String, TimeSpan, MessageQueueTransactionType)

Recebe a mensagem que corresponde ao identificador fornecido e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.

ReceiveById(String)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila não transacional) e gera uma exceção imediatamente se nenhuma mensagem com o identificador existe atualmente na fila.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

InvalidOperationException

Não foi possível localizar a mensagem com o id especificado.

MessageQueueException

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

Exemplos

O exemplo de código a seguir demonstra o uso de 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);

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila. Esse método gerará uma exceção imediatamente se a mensagem não estiver na fila.

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponda ao parâmetro especificado id .

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada para a fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue na fila.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a

ReceiveById(String, MessageQueueTransaction)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila transacional) e gera uma exceção imediatamente se nenhuma mensagem com o identificador existe atualmente na fila.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

transaction
MessageQueueTransaction

O objeto MessageQueueTransaction.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

- ou -

O parâmetro transaction é null.

InvalidOperationException

Não foi possível localizar a mensagem com o id especificado.

MessageQueueException

A fila é não transacional.

- ou -

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

Exemplos

O exemplo de código a seguir demonstra o uso de 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();
}

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila, usando o contexto de transação interna definido pelo transaction parâmetro . Esse método gera uma exceção imediatamente se a mensagem não estiver na fila

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponda ao parâmetro especificado id .

Como esse método é chamado em uma fila transacional, a mensagem recebida será retornada para a fila se a transação for anulada. A mensagem não será removida permanentemente da fila até que a transação seja confirmada.

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada para a fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue na fila. Não há nenhum contexto de transação associado a uma mensagem retornada por uma chamada para PeekById(String). Como PeekById(String) não remove nenhuma mensagem na fila, não haveria nada a ser revertido se a transação fosse anulada.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a

ReceiveById(String, MessageQueueTransactionType)

Recebe a mensagem que corresponde ao identificador especificado e gerará imediatamente uma exceção se nenhuma mensagem com o identificador especificado existir atualmente na fila.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

transactionType
MessageQueueTransactionType

Um dos valores de MessageQueueTransactionType, que descreve o tipo de contexto de transação associado à mensagem.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

InvalidOperationException

Não foi possível localizar a mensagem com o id especificado.

InvalidEnumArgumentException

O parâmetro transactionType não é um dos membros do MessageQueueTransactionType.

MessageQueueException

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

Exemplos

O exemplo de código a seguir demonstra o uso de 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);

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila. Esse método gerará uma exceção imediatamente se a mensagem não estiver na fila. Caso contrário, a mensagem será removida da fila e retornada ao aplicativo usando um contexto de transação definido pelo transactionType parâmetro .

Especifique Automatic para o transactionType parâmetro se já houver um contexto de transação externo anexado ao thread que você deseja usar para receber a mensagem. Especifique Single se deseja receber a mensagem como uma única transação interna. Você pode especificar None se deseja receber uma mensagem de uma fila transacional fora de um contexto de transação.

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponda ao parâmetro especificado id . Se a mensagem com o identificador especificado estiver em uma fila diferente daquela associada a essa MessageQueue instância, a mensagem não será encontrada.

Se esse método for chamado para receber uma mensagem de uma fila transacional, a mensagem recebida será retornada para a fila se a transação for anulada. A mensagem não será removida permanentemente da fila até que a transação seja confirmada.

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada para a fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue na fila. Não há nenhum contexto de transação associado a uma mensagem retornada por uma chamada para PeekById(String). Como PeekById(String) não remove nenhuma mensagem na fila, não haveria nada a ser revertido se a transação fosse anulada.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a

ReceiveById(String, TimeSpan)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila não transacional) e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

timeout
TimeSpan

Um TimeSpan que indica o tempo de espera até que uma nova mensagem esteja disponível para inspeção.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

ArgumentException

O valor especificado para o parâmetro timeout não é válido, possivelmente timeout é menor que Zero ou maior que InfiniteTimeout.

MessageQueueException

Uma mensagem com o id especificado não chegou à fila antes do tempo limite expirar.

- ou -

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

Exemplos

O exemplo de código a seguir demonstra o uso de 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));

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila. Esse método retornará imediatamente se a mensagem com o identificador especificado pelo id parâmetro estiver na fila. Caso contrário, o método aguardará o período de tempo determinado para que uma nova mensagem chegue. Se uma nova mensagem não chegar antes do tempo limite expirar, uma exceção será gerada.

O timeout parâmetro não especifica o tempo total de execução para esse método. Em vez disso, ele especifica o tempo de espera para que uma nova mensagem chegue à fila. Sempre que uma nova mensagem chega, esse método examina o Id da nova mensagem para ver se ele corresponde ao id parâmetro . Caso contrário, esse método inicia o período de tempo limite e aguarda a chegada de outra nova mensagem. Portanto, se novas mensagens continuarem a chegar dentro do período de tempo limite, é possível que esse método continue em execução indefinidamente, seja até que o período de tempo limite expire sem que novas mensagens cheguem ou até que uma mensagem chegue cujo Id parâmetro corresponda id .

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponda ao parâmetro especificado id .

Use essa sobrecarga de ReceiveById(String) quando for aceitável que o thread atual seja bloqueado, desde que novas mensagens continuem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro . O thread será bloqueado pelo menos pelo período de tempo determinado ou indefinidamente se você especificou o valor InfiniteTimeout do timeout parâmetro ou se novas mensagens continuarem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro .

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada para a fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue na fila.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a

ReceiveById(String, TimeSpan, MessageQueueTransaction)

Recebe a mensagem que corresponde ao identificador fornecido (de uma fila transacional) e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

timeout
TimeSpan

Um TimeSpan que indica o tempo de espera até que uma nova mensagem esteja disponível para inspeção.

transaction
MessageQueueTransaction

O objeto MessageQueueTransaction.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

- ou -

O parâmetro transaction é null.

ArgumentException

O valor especificado para o parâmetro timeout não é válido, possivelmente timeout é menor que Zero ou maior que InfiniteTimeout.

MessageQueueException

Uma mensagem com o id especificado não chegou à fila antes do tempo limite expirar.

- ou -

A fila é não transacional.

- ou -

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

Exemplos

O exemplo de código a seguir demonstra o uso de 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();
}

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila, usando o contexto de transação interna definido pelo transaction parâmetro . Esse método retornará imediatamente se a mensagem com o identificador especificado pelo id parâmetro estiver na fila. Caso contrário, o método aguardará o período de tempo determinado para que uma nova mensagem chegue. Se uma nova mensagem não chegar antes do tempo limite expirar, uma exceção será gerada.

O timeout parâmetro não especifica o tempo total de execução para esse método. Em vez disso, ele especifica o tempo de espera para que uma nova mensagem chegue à fila. Sempre que uma nova mensagem chega, esse método examina o Id da nova mensagem para ver se ele corresponde ao id parâmetro . Caso contrário, esse método inicia o período de tempo limite e aguarda a chegada de outra nova mensagem. Portanto, se novas mensagens continuarem a chegar dentro do período de tempo limite, é possível que esse método continue em execução indefinidamente, seja até que o período de tempo limite expire sem que novas mensagens cheguem ou até que uma mensagem chegue cujo Id parâmetro corresponda id .

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponda ao parâmetro especificado id .

Use essa sobrecarga de ReceiveById(String) quando for aceitável que o thread atual seja bloqueado, desde que novas mensagens continuem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro . O thread será bloqueado pelo menos pelo período determinado ou indefinidamente se você especificou o valor InfiniteTimeout do timeout parâmetro ou se novas mensagens continuarem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro .

Como esse método é chamado em uma fila transacional, a mensagem recebida será retornada para a fila se a transação for anulada. A mensagem não será removida permanentemente da fila até que a transação seja confirmada.

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada para a fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue na fila. Não há nenhum contexto de transação associado a uma mensagem retornada por uma chamada para PeekById(String). Como PeekById(String) não remove nenhuma mensagem na fila, não haveria nada a ser revertido se a transação fosse anulada.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a

ReceiveById(String, TimeSpan, MessageQueueTransactionType)

Recebe a mensagem que corresponde ao identificador fornecido e aguarda até uma mensagem com o identificador estar disponível na fila ou tempo limite expirar.

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

Parâmetros

id
String

O Id da mensagem a ser recebida.

timeout
TimeSpan

Um TimeSpan que indica o tempo de espera até que uma nova mensagem esteja disponível para inspeção.

transactionType
MessageQueueTransactionType

Um dos valores de MessageQueueTransactionType, que descreve o tipo de contexto de transação associado à mensagem.

Retornos

Message

O Message cuja propriedade Id corresponde ao parâmetro id passado.

Exceções

ArgumentNullException

O parâmetro id é null.

ArgumentException

O valor especificado para o parâmetro timeout não é válido, possivelmente timeout é menor que Zero ou maior que InfiniteTimeout.

MessageQueueException

Uma mensagem com o id especificado não chegou à fila antes do tempo limite expirar.

- ou -

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.

InvalidEnumArgumentException

O parâmetro transactionType não é um dos membros do MessageQueueTransactionType.

Exemplos

O exemplo de código a seguir demonstra o uso de 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);

Comentários

Use esse método para ler uma mensagem com um identificador conhecido e removê-la da fila. Esse método retornará imediatamente se a mensagem com o identificador especificado pelo id parâmetro estiver na fila, usando um contexto de transação definido pelo transactionType parâmetro . Caso contrário, o método aguardará o período de tempo determinado para que uma nova mensagem chegue. Se uma nova mensagem não chegar antes do tempo limite expirar, uma exceção será gerada.

O timeout parâmetro não especifica o tempo de execução total para esse método. Em vez disso, ele especifica o tempo de espera para que uma nova mensagem chegue à fila. Sempre que uma nova mensagem chega, esse método examina o Id da nova mensagem para ver se ele corresponde ao id parâmetro. Caso contrário, esse método inicia o período de tempo limite e aguarda a chegada de outra nova mensagem. Portanto, se novas mensagens continuarem a chegar dentro do período de tempo limite, é possível que esse método continue sendo executado indefinidamente, até que o período de tempo limite expire sem que novas mensagens cheguem ou até que uma mensagem chegue cujo Id parâmetro corresponda id .

Especifique Automatic para o transactionType parâmetro se já houver um contexto de transação externo anexado ao thread que você deseja usar para receber a mensagem. Especifique Single se deseja receber a mensagem como uma única transação interna. Você pode especificar None se deseja receber uma mensagem de uma fila transacional fora de um contexto de transação.

A Id propriedade de uma mensagem é exclusiva em toda a empresa de Enfileiramento de Mensagens, portanto, haverá no máximo uma mensagem na fila que corresponde ao parâmetro especificado id . Se a mensagem com o identificador especificado estiver em uma fila diferente daquela associada a essa MessageQueue instância, a mensagem não será encontrada.

Use essa sobrecarga de ReceiveById(String) quando for aceitável que o thread atual seja bloqueado, desde que novas mensagens continuem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro . O thread será bloqueado pelo menos pelo período determinado ou indefinidamente se você especificou o valor InfiniteTimeout do timeout parâmetro ou se novas mensagens continuarem a chegar na fila dentro do período de tempo limite especificado pelo timeout parâmetro .

Se esse método for chamado para receber uma mensagem de uma fila transacional, a mensagem recebida será retornada para a fila se a transação for anulada. A mensagem não será removida permanentemente da fila até que a transação seja confirmada.

Dois outros métodos permitem que você receba mensagens de uma fila. O Receive método retorna a primeira mensagem na fila e o ReceiveByCorrelationId(String) método é usado para recuperar uma mensagem de confirmação, relatório ou resposta gerada pelo aplicativo que foi criada como resultado de uma mensagem enviada à fila.

Para ler uma mensagem com um identificador especificado sem removê-la da fila, use o PeekById(String) método . O PeekById(String) método sempre retorna a primeira mensagem na fila, portanto, chamadas subsequentes para o método retornam a mesma mensagem, a menos que uma mensagem de prioridade mais alta chegue à fila. Não há nenhum contexto de transação associado a uma mensagem retornada por uma chamada para PeekById(String). Como PeekById(String) não remove nenhuma mensagem na fila, não haveria nada a ser revertido se a transação fosse anulada.

A tabela a seguir mostra se esse método está disponível em vários modos de Grupo de Trabalho.

Modo de grupo de trabalho Disponível
Computador local Yes
Nome do computador local e do formato direto Yes
Computador remoto Não
Computador remoto e nome de formato direto Yes

Confira também

Aplica-se a