MessageQueue.BeginReceive Method

Definition

Inicia uma operação de recepção assíncrona informando o Enfileiramento de Mensagens para começar a receber uma mensagem e notificar o manipulador de eventos quando terminar.Initiates an asynchronous receive operation by telling Message Queuing to begin receiving a message and notify the event handler when finished.

Overloads

BeginReceive()

Inicia uma operação de recebimento espiada assíncrona que não tem um tempo limite. A operação não será concluída até que uma mensagem fique disponível na fila.Initiates an asynchronous receive operation that has no time-out. The operation is not complete until a message becomes available in the queue.

BeginReceive(TimeSpan)

Inicia uma operação de recebimento assíncrona que tem um tempo limite especificado. A operação não será concluída até que uma mensagem fique disponível na fila ou que ocorra o tempo limite.Initiates an asynchronous receive operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginReceive(TimeSpan, Object)

Inicia uma operação de recebimento assíncrona que tem um tempo limite e um objeto de estado especificados, que fornece informações associadas durante o tempo de vida da operação.Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginReceive(TimeSpan, Object, AsyncCallback)

Inicia uma operação de recebimento assíncrona que tem um tempo limite e um objeto de estado especificados, que fornece informações associadas durante o tempo de vida da operação.Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. Essa sobrecarga recebe uma notificação, por meio de um retorno de chamada, da identidade do manipulador de eventos da operação.This overload receives notification, through a callback, of the identity of the event handler for the operation. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginReceive(TimeSpan, Cursor, Object, AsyncCallback)

Inicia uma operação de recebimento assíncrona que tem um tempo limite especificado e usa um cursor especificado e um objeto de estado especificado.Initiates an asynchronous receive operation that has a specified time-out and uses a specified cursor and a specified state object. O objeto de estado fornece informações associadas em todo o tempo de vida da operação.The state object provides associated information throughout the lifetime of the operation. Essa sobrecarga recebe uma notificação, por meio de um retorno de chamada, da identidade do manipulador de eventos da operação.This overload receives notification, through a callback, of the identity of the event handler for the operation. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginReceive()

Inicia uma operação de recebimento espiada assíncrona que não tem um tempo limite. A operação não será concluída até que uma mensagem fique disponível na fila.Initiates an asynchronous receive operation that has no time-out. The operation is not complete until a message becomes available in the queue.

public:
 IAsyncResult ^ BeginReceive();
public IAsyncResult BeginReceive ();
member this.BeginReceive : unit -> IAsyncResult
Public Function BeginReceive () As IAsyncResult

Returns

IAsyncResult

O IAsyncResult que identifica a solicitação assíncrona postada.The IAsyncResult that identifies the posted asynchronous request.

Exceptions

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.An error occurred when accessing a Message Queuing method.

Examples

O exemplo de código a seguir encadeia solicitações assíncronas.The following code example chains asynchronous requests. Ele assume que há uma fila no computador local chamada "MyQueue".It assumes there is a queue on the local computer called "myQueue". A função Main inicia a operação assíncrona que é tratada pela rotina de MyReceiveCompleted.The Main function begins the asynchronous operation that is handled by the MyReceiveCompleted routine. MyReceiveCompleted processa a mensagem atual e inicia uma nova operação de recebimento assíncrono.MyReceiveCompleted processes the current message and begins a new asynchronous receive operation.

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

using namespace System;
using namespace System::Messaging;
using namespace System::Threading;

ref class MyNewQueue
{
public:

   // Define static class members.
   static ManualResetEvent^ signal = gcnew ManualResetEvent( false );
   static int count = 0;

   // Provides an event handler for the ReceiveCompleted
   // event.
   static void MyReceiveCompleted( Object^ source, ReceiveCompletedEventArgs^ asyncResult )
   {
      try
      {
         // Connect to the queue.
         MessageQueue^ mq = dynamic_cast<MessageQueue^>(source);

         // End the asynchronous receive operation.
         mq->EndReceive( asyncResult->AsyncResult );
         count += 1;
         if ( count == 10 )
         {
            signal->Set();
         }

         // Restart the asynchronous receive operation.
         mq->BeginReceive();
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle sources of MessageQueueException.
      }

      // Handle other exceptions.
      return;
   }
};

// Provides an entry point into the application.
//         
// This example performs asynchronous receive
// operation processing.
int main()
{
   // Create an instance of MessageQueue. Set its formatter.
   MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
   array<Type^>^p = gcnew array<Type^>(1);
   p[ 0 ] = String::typeid;
   myQueue->Formatter = gcnew XmlMessageFormatter( p );

   // Add an event handler for the ReceiveCompleted event.
   myQueue->ReceiveCompleted += gcnew ReceiveCompletedEventHandler( MyNewQueue::MyReceiveCompleted );

   // Begin the asynchronous receive operation.
   myQueue->BeginReceive();
   MyNewQueue::signal->WaitOne();

   // Do other work on the current thread.
   return 0;
}
using System;
using System.Messaging;
using System.Threading;

namespace MyProject
{
    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {
        // Define static class members.
        static ManualResetEvent signal = new ManualResetEvent(false);
        static int count = 0;

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example performs asynchronous receive
        // operation processing.
        //**************************************************

        public static void Main()
        {
            // Create an instance of MessageQueue. Set its formatter.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(String)});

            // Add an event handler for the ReceiveCompleted event.
            myQueue.ReceiveCompleted +=
                new ReceiveCompletedEventHandler(MyReceiveCompleted);
            
            // Begin the asynchronous receive operation.
            myQueue.BeginReceive();

            signal.WaitOne();
            
            // Do other work on the current thread.

            return;
        }

        //***************************************************
        // Provides an event handler for the ReceiveCompleted
        // event.
        //***************************************************
        
        private static void MyReceiveCompleted(Object source,
            ReceiveCompletedEventArgs asyncResult)
        {
            try
            {
                // Connect to the queue.
                MessageQueue mq = (MessageQueue)source;

                // End the asynchronous receive operation.
                Message m = mq.EndReceive(asyncResult.AsyncResult);
                
                count += 1;
                if (count == 10)
                {
                    signal.Set();
                }

                // Restart the asynchronous receive operation.
                mq.BeginReceive();
            }
            catch(MessageQueueException)
            {
                // Handle sources of MessageQueueException.
            }
            
            // Handle other exceptions.
            
            return;
        }
    }
}
Imports System.Messaging
Imports System.Threading




' Provides a container class for the example.

Public Class MyNewQueue

        ' Define static class members.
        Private Shared signal As New ManualResetEvent(False)
        Private Shared count As Integer = 0



        ' Provides an entry point into the application.
        '		 
        ' This example performs asynchronous receive
        ' operation processing.


        Public Shared Sub Main()
            ' Create an instance of MessageQueue. Set its formatter.
            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                {GetType([String])})

            ' Add an event handler for the ReceiveCompleted event.
            AddHandler myQueue.ReceiveCompleted, AddressOf _
                MyReceiveCompleted

            ' Begin the asynchronous receive operation.
            myQueue.BeginReceive()

            signal.WaitOne()

            ' Do other work on the current thread.

            Return

        End Sub



        ' Provides an event handler for the ReceiveCompleted
        ' event.


        Private Shared Sub MyReceiveCompleted(ByVal [source] As _
            [Object], ByVal asyncResult As ReceiveCompletedEventArgs)

            Try
                ' Connect to the queue.
                Dim mq As MessageQueue = CType([source], MessageQueue)

                ' End the asynchronous receive operation.
                Dim m As Message = _
                    mq.EndReceive(asyncResult.AsyncResult)

                count += 1
                If count = 10 Then
                    signal.Set()
                End If

                ' Restart the asynchronous receive operation.
                mq.BeginReceive()

            Catch
                ' Handle sources of MessageQueueException.

                ' Handle other exceptions.

            End Try

            Return

        End Sub

End Class

O exemplo de código a seguir enfileira solicitações assíncronas.The following code example queues asynchronous requests. A chamada para BeginReceive usa o AsyncWaitHandle em seu valor de retorno.The call to BeginReceive uses the AsyncWaitHandle in its return value. A rotina Main aguarda a conclusão de todas as operações assíncronas antes de sair.The Main routine waits for all asynchronous operations to be completed before exiting.

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

using namespace System;
using namespace System::Messaging;
using namespace System::Threading;

ref class MyNewQueue
{
public:

   // Provides an event handler for the ReceiveCompleted
   // event.
   static void MyReceiveCompleted( Object^ source, ReceiveCompletedEventArgs^ asyncResult )
   {
      try
      {
         // Connect to the queue.
         MessageQueue^ mq = dynamic_cast<MessageQueue^>(source);

         // End the asynchronous receive operation.
         mq->EndReceive( asyncResult->AsyncResult );

         // Process the message here.
         Console::WriteLine( "Message received." );
      }
      catch ( MessageQueueException^ ) 
      {
         // Handle sources of MessageQueueException.
      }
      // Handle other exceptions.
      return;
   }
};

// Provides an entry point into the application.
//         
// This example performs asynchronous receive
// operation processing.
int main()
{
   // Create an instance of MessageQueue. Set its formatter.
   MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
   array<Type^>^p = gcnew array<Type^>(1);
   p[ 0 ] = String::typeid;
   myQueue->Formatter = gcnew XmlMessageFormatter( p );

   // Add an event handler for the ReceiveCompleted event.
   myQueue->ReceiveCompleted += gcnew ReceiveCompletedEventHandler( MyNewQueue::MyReceiveCompleted );

   // Define wait handles for multiple operations.
   array<WaitHandle^>^waitHandleArray = gcnew array<WaitHandle^>(10);
   for ( int i = 0; i < 10; i++ )
   {
      // Begin asynchronous operations.
      waitHandleArray[ i ] = myQueue->BeginReceive()->AsyncWaitHandle;
   }

   // Specify to wait for all operations to return.
   WaitHandle::WaitAll( waitHandleArray );
   return 0;
}
using System;
using System.Messaging;
using System.Threading;

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

        //**************************************************
        // Provides an entry point into the application.
        //		
        // This example performs asynchronous receive
        // operation processing.
        //**************************************************

        public static void Main()
        {
            // Create an instance of MessageQueue. Set its formatter.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(String)});

            // Add an event handler for the ReceiveCompleted event.
            myQueue.ReceiveCompleted +=
                new ReceiveCompletedEventHandler(MyReceiveCompleted);
            
            // Define wait handles for multiple operations.
            WaitHandle[] waitHandleArray = new WaitHandle[10];
            for(int i=0; i<10; i++)
            {
                // Begin asynchronous operations.
                waitHandleArray[i] =
                    myQueue.BeginReceive().AsyncWaitHandle;
            }

            // Specify to wait for all operations to return.
            WaitHandle.WaitAll(waitHandleArray);

            return;
        }

        //***************************************************
        // Provides an event handler for the ReceiveCompleted
        // event.
        //***************************************************
        
        private static void MyReceiveCompleted(Object source,
            ReceiveCompletedEventArgs asyncResult)
        {
            try
            {
                // Connect to the queue.
                MessageQueue mq = (MessageQueue)source;

                // End the asynchronous receive operation.
                Message m = mq.EndReceive(asyncResult.AsyncResult);
        
                // Process the message here.
                Console.WriteLine("Message received.");
            }
            catch(MessageQueueException)
            {
                // Handle sources of MessageQueueException.
            }
            
            // Handle other exceptions.
            
            return;
        }
    }
}
Imports System.Messaging
Imports System.Threading


' Provides a container class for the example.

Public Class MyNewQueue


        ' Provides an entry point into the application.
        '		 
        ' This example performs asynchronous receive
        ' operation processing.


        Public Shared Sub Main()

            ' Create an instance of MessageQueue. Set its formatter.
            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                {GetType([String])})

            ' Add an event handler for the ReceiveCompleted event.
            AddHandler myQueue.ReceiveCompleted, AddressOf _
                MyReceiveCompleted

            ' Define wait handles for multiple operations.
            Dim waitHandleArray(10) As WaitHandle

            Dim i As Integer
            For i = 0 To 9
                ' Begin asynchronous operations.
                waitHandleArray(i) = _
                    myQueue.BeginReceive().AsyncWaitHandle
            Next i

            ' Specify to wait for all operations to return.
            WaitHandle.WaitAll(waitHandleArray)

            Return

        End Sub



        ' Provides an event handler for the ReceiveCompleted
        ' event.


        Private Shared Sub MyReceiveCompleted(ByVal [source] As _
            [Object], ByVal asyncResult As ReceiveCompletedEventArgs)

            Try
                ' Connect to the queue.
                Dim mq As MessageQueue = CType([source], MessageQueue)

                ' End the asynchronous receive operation.
                Dim m As Message = _
                    mq.EndReceive(asyncResult.AsyncResult)

                ' Process the message here.
                Console.WriteLine("Message received.")

            Catch

                ' Handle sources of MessageQueueException.

                ' Handle other exceptions.

            End Try

            Return

        End Sub

End Class

Remarks

No processamento assíncrono, você usa BeginReceive para gerar o evento ReceiveCompleted quando uma mensagem tiver sido removida da fila.In asynchronous processing, you use BeginReceive to raise the ReceiveCompleted event when a message has been removed from the queue.

ReceiveCompleted também será gerado se uma mensagem já existir na fila.ReceiveCompleted is also raised if a message already exists in the queue.

Para usar BeginReceive, crie um manipulador de eventos que processa os resultados da operação assíncrona e associe-o ao seu representante de evento.To use BeginReceive, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. BeginReceive inicia uma operação de recebimento assíncrono; o MessageQueue é notificado, por meio da geração do evento ReceiveCompleted, quando uma mensagem chega na fila.BeginReceive initiates an asynchronous receive operation; the MessageQueue is notified, through the raising of the ReceiveCompleted event, when a message arrives in the queue. A MessageQueue pode então acessar a mensagem chamando EndReceive(IAsyncResult).The MessageQueue can then access the message by calling EndReceive(IAsyncResult).

O método BeginReceive retorna imediatamente, mas a operação assíncrona não é concluída até que o manipulador de eventos seja chamado.The BeginReceive method returns immediately, but the asynchronous operation is not completed until the event handler is called.

Como BeginReceive é assíncrono, você pode chamá-lo para receber uma mensagem da fila sem bloquear o thread atual de execução.Because BeginReceive is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. Para receber de forma síncrona uma mensagem, use o método Receive.To synchronously receive a message, use the Receive method.

Quando uma operação assíncrona for concluída, você poderá chamar BeginPeek ou BeginReceive novamente no manipulador de eventos para continuar recebendo notificações.Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

A IAsyncResult que BeginReceive retorna identifica a operação assíncrona que o método iniciou.The IAsyncResult that BeginReceive returns identifies the asynchronous operation that the method started. Você pode usar essa IAsyncResult durante todo o tempo de vida da operação, embora geralmente não a use até que EndReceive(IAsyncResult) seja chamado.You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndReceive(IAsyncResult) is called. No entanto, se você iniciar várias operações assíncronas, poderá inserir seus valores de IAsyncResult em uma matriz e especificar se deseja aguardar a conclusão de todas as operações ou de qualquer operação.However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. Nesse caso, você usa a propriedade AsyncWaitHandle do IAsyncResult para identificar a operação concluída.In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

Se CanRead for false, o evento de conclusão será gerado, mas uma exceção será gerada ao chamar EndReceive(IAsyncResult).If CanRead is false, the completion event is raised, but an exception will be thrown when calling EndReceive(IAsyncResult).

Não use a chamada assíncrona BeginReceive com transações.Do not use the asynchronous call BeginReceive with transactions. Se você quiser executar uma operação assíncrona transacional, chame BeginPeeke coloque a transação e o método (síncrono) Receive dentro do manipulador de eventos criado para a operação de inspeção.If you want to perform a transactional asynchronous operation, call BeginPeek, and put the transaction and the (synchronous) Receive method within the event handler you create for the peek operation. O manipulador de eventos pode conter funcionalidades, conforme mostrado no C# código a seguir.Your event handler might contain functionality as shown in the following C# code.

myMessageQueue.BeginTransaction();  
 myMessageQueue.Receive();  
 myMessageQueue.CommitTransaction();  

A tabela a seguir mostra se esse método está disponível em vários modos de grupo de trabalho.The following table shows whether this method is available in various Workgroup modes.

Modo de grupo de trabalhoWorkgroup mode DisponívelAvailable
Computador localLocal computer SimYes
Computador local e nome de formato diretoLocal computer and direct format name SimYes
Computador remotoRemote computer NãoNo
Computador remoto e nome de formato diretoRemote computer and direct format name SimYes

See also

BeginReceive(TimeSpan)

Inicia uma operação de recebimento assíncrona que tem um tempo limite especificado. A operação não será concluída até que uma mensagem fique disponível na fila ou que ocorra o tempo limite.Initiates an asynchronous receive operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginReceive(TimeSpan timeout);
public IAsyncResult BeginReceive (TimeSpan timeout);
member this.BeginReceive : TimeSpan -> IAsyncResult
Public Function BeginReceive (timeout As TimeSpan) As IAsyncResult

Parameters

timeout
TimeSpan

Um TimeSpan que indica o intervalo de tempo para aguardar uma mensagem se tornar disponível.A TimeSpan that indicates the interval of time to wait for a message to become available.

Returns

IAsyncResult

O IAsyncResult que identifica a solicitação assíncrona postada.The IAsyncResult that identifies the posted asynchronous request.

Exceptions

O valor especificado para o parâmetro timeout não é válido, possivelmente porque ele representa um número negativo.The value specified for the timeout parameter is not valid, possibly because it represents a negative number.

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.An error occurred when accessing a Message Queuing method.

Examples

O exemplo de código a seguir cria uma operação de recebimento assíncrono.The following code example creates an asynchronous receive operation. O exemplo de código cria um manipulador de eventos, MyReceiveCompletede anexa-o ao delegado manipulador de eventos ReceiveCompleted.The code example creates an event handler, MyReceiveCompleted, and attaches it to the ReceiveCompleted event handler delegate. O exemplo de código envia uma mensagem para uma fila de mensagens local e, em seguida, chama BeginReceive(TimeSpan), passando um valor de tempo limite de dez segundos.The code example sends a message to a local message queue, then calls BeginReceive(TimeSpan), passing in a time-out value of ten seconds. Quando um evento de ReceiveCompleted é gerado, o manipulador de eventos recebe a mensagem e grava o corpo da mensagem na tela.When a ReceiveCompleted event is raised, the event handler receives the message and writes the message body to the screen.

#using <System.Messaging.dll>
#using <System.dll>

using namespace System;
using namespace System::Messaging;

// Creates a new queue.
void CreateQueue(String^ queuePath, bool transactional)
{
    if(!MessageQueue::Exists(queuePath))
    {
        MessageQueue^ queue = MessageQueue::Create(queuePath, transactional);
        queue->Close();       
    }
    else
    {
        Console::WriteLine("{0} already exists.", queuePath);
    }
}

// Provides an event handler for the ReceiveCompleted event.
void HandleReceiveCompleted(Object^ source, ReceiveCompletedEventArgs^ e)
{
    // Connect to the queue.
    MessageQueue^ queue = (MessageQueue^)source;

    // End the asynchronous receive operation.
    Message^ msg = queue->EndReceive(e->AsyncResult);

    // Display the message information on the screen.
    Console::WriteLine("Message body: {0}", msg->Body);
    
    queue->Close();
}

int main()
{
    // Create a non-transactional queue on the local computer.
    // Note that the queue might not be immediately accessible, and
    // therefore this example might throw an exception of type
    // System.Messaging.MessageQueueException when trying to send a
    // message to the newly created queue.
    MessageQueue^ queue = nullptr;
    try
    {
        CreateQueue(".\\exampleQueue", false);

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

        // Add an event handler for the ReceiveCompleted event.
        queue->ReceiveCompleted += gcnew
            ReceiveCompletedEventHandler(HandleReceiveCompleted);

        // Send a message to the queue.
        queue->Send("Example Message");

        // Begin the asynchronous receive operation.
        queue->BeginReceive(TimeSpan::FromSeconds(10.0));

        // Simulate doing other work on the current thread.
        System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));
    }

    catch (InvalidOperationException^)
    {
        Console::WriteLine("Please install Message Queuing.");
    }

    catch (MessageQueueException^ ex)
    {
        Console::WriteLine(ex->Message);
    }

    finally
    {   
        queue->Close();
    }

}

using System;
using System.Messaging;

public class QueueExample
{
    public static void Main()
    {
        // Create a non-transactional queue on the local computer.
        // Note that the queue might not be immediately accessible, and
        // therefore this example might throw an exception of type
        // System.Messaging.MessageQueueException when trying to send a
        // message to the newly created queue.
        CreateQueue(".\\exampleQueue", false);

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

        // Add an event handler for the ReceiveCompleted event.
        queue.ReceiveCompleted += new
                ReceiveCompletedEventHandler(MyReceiveCompleted);

        // Send a message to the queue.
        queue.Send("Example Message");

        // Begin the asynchronous receive operation.
        queue.BeginReceive(TimeSpan.FromSeconds(10.0));

        // Simulate doing other work on the current thread.
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

        return;
    }

    // Creates a new queue.
    public static void CreateQueue(string queuePath, bool transactional)
    {
        if(!MessageQueue.Exists(queuePath))
        {
            MessageQueue.Create(queuePath, transactional);
        }
        else
        {
            Console.WriteLine(queuePath + " already exists.");
        }
    }

    // Provides an event handler for the ReceiveCompleted event.
    private static void MyReceiveCompleted(Object source,
        ReceiveCompletedEventArgs asyncResult)
    {
        // Connect to the queue.
        MessageQueue queue = (MessageQueue)source;

        // End the asynchronous receive operation.
        Message msg = queue.EndReceive(asyncResult.AsyncResult);

        // Display the message information on the screen.
        Console.WriteLine("Message body: {0}", (string)msg.Body);
    }
}

Remarks

No processamento assíncrono, você usa BeginReceive para gerar o evento ReceiveCompleted quando uma mensagem for disponibilizada na fila ou quando o intervalo especificado de tempo tiver expirado.In asynchronous processing, you use BeginReceive to raise the ReceiveCompleted event when a message becomes available in the queue or when the specified interval of time has expired.

ReceiveCompleted também será gerado se uma mensagem já existir na fila.ReceiveCompleted is also raised if a message already exists in the queue.

Para usar BeginReceive, crie um manipulador de eventos que processa os resultados da operação assíncrona e associe-o ao seu representante de evento.To use BeginReceive, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. BeginReceive inicia uma operação de recebimento assíncrono; o MessageQueue é notificado, por meio da geração do evento ReceiveCompleted, quando uma mensagem chega na fila.BeginReceive initiates an asynchronous receive operation; the MessageQueue is notified, through the raising of the ReceiveCompleted event, when a message arrives in the queue. O MessageQueue pode então acessar a mensagem chamando EndReceive(IAsyncResult) ou recuperando o resultado usando o ReceiveCompletedEventArgs.The MessageQueue can then access the message by calling EndReceive(IAsyncResult) or retrieving the result using the ReceiveCompletedEventArgs.

O método BeginReceive retorna imediatamente, mas a operação assíncrona não é concluída até que o manipulador de eventos seja chamado.The BeginReceive method returns immediately, but the asynchronous operation is not completed until the event handler is called.

Como BeginReceive é assíncrono, você pode chamá-lo para receber uma mensagem da fila sem bloquear o thread atual de execução.Because BeginReceive is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. Para receber de forma síncrona uma mensagem, use o método Receive.To synchronously receive a message, use the Receive method.

Quando uma operação assíncrona for concluída, você poderá chamar BeginPeek ou BeginReceive novamente no manipulador de eventos para continuar recebendo notificações.Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

Se CanRead for false, o evento de conclusão será gerado, mas uma exceção será gerada ao chamar EndReceive(IAsyncResult).If CanRead is false, the completion event is raised, but an exception will be thrown when calling EndReceive(IAsyncResult).

A IAsyncResult que BeginReceive retorna identifica a operação assíncrona que o método iniciou.The IAsyncResult that BeginReceive returns identifies the asynchronous operation that the method started. Você pode usar essa IAsyncResult durante todo o tempo de vida da operação, embora geralmente não a use até que EndReceive(IAsyncResult) seja chamado.You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndReceive(IAsyncResult) is called. No entanto, se você iniciar várias operações assíncronas, poderá inserir seus valores de IAsyncResult em uma matriz e especificar se deseja aguardar a conclusão de todas as operações ou de qualquer operação.However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. Nesse caso, você usa a propriedade AsyncWaitHandle do IAsyncResult para identificar a operação concluída.In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

Essa sobrecarga Especifica um tempo limite. Se o intervalo especificado pelo parâmetro timeout expirar, esse componente gerará o evento ReceiveCompleted.This overload specifies a time-out. If the interval specified by the timeout parameter expires, this component raises the ReceiveCompleted event. Como não existe nenhuma mensagem, uma chamada subsequente para EndReceive(IAsyncResult) gerará uma exceção.Because no message exists, a subsequent call to EndReceive(IAsyncResult) will throw an exception.

Não use a chamada assíncrona BeginReceive com transações.Do not use the asynchronous call BeginReceive with transactions. Se você quiser executar uma operação assíncrona transacional, chame BeginPeeke coloque a transação e o método (síncrono) Receive dentro do manipulador de eventos criado para a operação de inspeção.If you want to perform a transactional asynchronous operation, call BeginPeek, and put the transaction and the (synchronous) Receive method within the event handler you create for the peek operation. O manipulador de eventos pode conter funcionalidades, conforme mostrado no C# código a seguir.Your event handler might contain functionality as shown in the following C# code.

myMessageQueue.BeginTransaction();  
 myMessageQueue.Receive();  
 myMessageQueue.CommitTransaction();  

A tabela a seguir mostra se esse método está disponível em vários modos de grupo de trabalho.The following table shows whether this method is available in various Workgroup modes.

Modo de grupo de trabalhoWorkgroup mode DisponívelAvailable
Computador localLocal computer SimYes
Computador local e nome de formato diretoLocal computer and direct format name SimYes
Computador remotoRemote computer NãoNo
Computador remoto e nome de formato diretoRemote computer and direct format name SimYes

See also

BeginReceive(TimeSpan, Object)

Inicia uma operação de recebimento assíncrona que tem um tempo limite e um objeto de estado especificados, que fornece informações associadas durante o tempo de vida da operação.Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Object ^ stateObject);
public IAsyncResult BeginReceive (TimeSpan timeout, object stateObject);
member this.BeginReceive : TimeSpan * obj -> IAsyncResult
Public Function BeginReceive (timeout As TimeSpan, stateObject As Object) As IAsyncResult

Parameters

timeout
TimeSpan

Um TimeSpan que indica o intervalo de tempo para aguardar uma mensagem se tornar disponível.A TimeSpan that indicates the interval of time to wait for a message to become available.

stateObject
Object

Um objeto de estado, especificado pelo aplicativo, que contém informações associadas à operação assíncrona.A state object, specified by the application, that contains information associated with the asynchronous operation.

Returns

IAsyncResult

O IAsyncResult que identifica a solicitação assíncrona postada.The IAsyncResult that identifies the posted asynchronous request.

Exceptions

O valor especificado para o parâmetro timeout não é válido.The value specified for the timeout parameter is not valid.

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.An error occurred when accessing a Message Queuing method.

Examples

O exemplo de código a seguir cria uma operação de recebimento assíncrono.The following code example creates an asynchronous receive operation. O exemplo de código cria um manipulador de eventos, MyReceiveCompletede anexa-o ao delegado manipulador de eventos ReceiveCompleted.The code example creates an event handler, MyReceiveCompleted, and attaches it to the ReceiveCompleted event handler delegate. O exemplo de código envia uma mensagem para uma fila de mensagens local e, em seguida, chama BeginReceive(TimeSpan, Object), passando um valor de tempo limite de dez segundos e um inteiro exclusivo que identifica essa mensagem específica.The code example sends a message to a local message queue, then calls BeginReceive(TimeSpan, Object), passing in a time-out value of ten seconds and a unique integer that identifies that particular message. Quando um evento de ReceiveCompleted é gerado, o manipulador de eventos recebe a mensagem e grava o corpo da mensagem e o identificador da mensagem de número inteiro na tela.When a ReceiveCompleted event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen.

#using <System.Messaging.dll>
#using <System.dll>

using namespace System;
using namespace System::Messaging;

// Creates a new queue.
void CreateQueue(String^ queuePath, bool transactional)
{
    if(!MessageQueue::Exists(queuePath))
    {
        MessageQueue^ queue = MessageQueue::Create(queuePath, transactional);
        queue->Close();       
    }
    else
    {
        Console::WriteLine("{0} already exists.", queuePath);
    }
}

// Provides an event handler for the ReceiveCompleted event.
void HandleReceiveCompleted(Object^ source, ReceiveCompletedEventArgs^ e)
{
    // Connect to the queue.
    MessageQueue^ queue = (MessageQueue^)source;

    // End the asynchronous receive operation.
    Message^ msg = queue->EndReceive(e->AsyncResult);

    // Display the message information on the screen.
    Console::WriteLine("Message number: {0}", e->AsyncResult->AsyncState);
    Console::WriteLine("Message body: {0}", msg->Body);

    queue->Close();
}

int main()
{
    // Create a non-transactional queue on the local computer.
    // Note that the queue might not be immediately accessible, and
    // therefore this example might throw an exception of type
    // System.Messaging.MessageQueueException when trying to send a
    // message to the newly created queue.
    MessageQueue^ queue = nullptr;

    // Represents a state object associated with each message.
    int messageNumber = 0;

    try
    {
        CreateQueue(".\\exampleQueue", false);

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

        // Add an event handler for the ReceiveCompleted event.
        queue->ReceiveCompleted += gcnew
            ReceiveCompletedEventHandler(HandleReceiveCompleted);

        // Send a message to the queue.
        queue->Send("Example Message");

        // Begin the asynchronous receive operation.
        queue->BeginReceive(TimeSpan::FromSeconds(10.0), messageNumber++);

        // Simulate doing other work on the current thread.
        System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));
    }
    catch (InvalidOperationException^)
    {
        Console::WriteLine("Please install Message Queuing.");
    }

    catch (MessageQueueException^ ex)
    {
        Console::WriteLine(ex->Message);
    }

    finally
    {   
        queue->Close();
    }
}


using System;
using System.Messaging;

public class QueueExample
{
    // Represents a state object associated with each message.
    static int messageNumber = 0;

    public static void Main()
    {
        // Create a non-transactional queue on the local computer.
        // Note that the queue might not be immediately accessible, and
        // therefore this example might throw an exception of type
        // System.Messaging.MessageQueueException when trying to send a
        // message to the newly created queue.
        CreateQueue(".\\exampleQueue", false);

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

        // Add an event handler for the ReceiveCompleted event.
        queue.ReceiveCompleted += new
            ReceiveCompletedEventHandler(MyReceiveCompleted);

        // Send a message to the queue.
        queue.Send("Example Message");

        // Begin the asynchronous receive operation.
        queue.BeginReceive(TimeSpan.FromSeconds(10.0), messageNumber++);

        // Simulate doing other work on the current thread.
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

        return;
    }

    // Creates a new queue.
    public static void CreateQueue(string queuePath, bool transactional)
    {
        if(!MessageQueue.Exists(queuePath))
        {
            MessageQueue.Create(queuePath, transactional);
        }
        else
        {
            Console.WriteLine(queuePath + " already exists.");
        }
    }

    // Provides an event handler for the ReceiveCompleted event.
    private static void MyReceiveCompleted(Object source,
        ReceiveCompletedEventArgs asyncResult)
    {
        // Connect to the queue.
        MessageQueue queue = (MessageQueue)source;

        // End the asynchronous receive operation.
        Message msg = queue.EndReceive(asyncResult.AsyncResult);

        // Display the message information on the screen.
        Console.WriteLine("Message number: {0}",
            (int)asyncResult.AsyncResult.AsyncState);
        Console.WriteLine("Message body: {0}", (string)msg.Body);
    }
}

Remarks

No processamento assíncrono, você usa BeginReceive para gerar o evento ReceiveCompleted quando uma mensagem for disponibilizada na fila ou quando o intervalo especificado de tempo tiver expirado.In asynchronous processing, you use BeginReceive to raise the ReceiveCompleted event when a message becomes available in the queue or when the specified interval of time has expired.

ReceiveCompleted também será gerado se uma mensagem já existir na fila.ReceiveCompleted is also raised if a message already exists in the queue.

Use essa sobrecarga para associar informações com a operação que será preservada durante o tempo de vida da operação.Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. O manipulador de eventos pode detectar essas informações examinando a propriedade AsyncState da IAsyncResult associada à operação.The event handler can detect this information by looking at the AsyncState property of the IAsyncResult that is associated with the operation.

Para usar BeginReceive, crie um manipulador de eventos que processa os resultados da operação assíncrona e associe-o ao seu representante de evento.To use BeginReceive, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. BeginReceive inicia uma operação de recebimento assíncrono; o MessageQueue é notificado, por meio da geração do evento ReceiveCompleted, quando uma mensagem chega na fila.BeginReceive initiates an asynchronous receive operation; the MessageQueue is notified, through the raising of the ReceiveCompleted event, when a message arrives in the queue. O MessageQueue pode então acessar a mensagem chamando EndReceive(IAsyncResult) ou recuperando o resultado usando o ReceiveCompletedEventArgs.The MessageQueue can then access the message by calling EndReceive(IAsyncResult) or retrieving the result using the ReceiveCompletedEventArgs.

O método BeginReceive retorna imediatamente, mas a operação assíncrona não é concluída até que o manipulador de eventos seja chamado.The BeginReceive method returns immediately, but the asynchronous operation is not completed until the event handler is called.

Como BeginReceive é assíncrono, você pode chamá-lo para receber uma mensagem da fila sem bloquear o thread atual de execução.Because BeginReceive is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. Para receber de forma síncrona uma mensagem, use o método Receive.To synchronously receive a message, use the Receive method.

Quando uma operação assíncrona for concluída, você poderá chamar BeginPeek ou BeginReceive novamente no manipulador de eventos para continuar recebendo notificações.Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

A IAsyncResult que BeginReceive retorna identifica a operação assíncrona que o método iniciou.The IAsyncResult that BeginReceive returns identifies the asynchronous operation that the method started. Você pode usar essa IAsyncResult durante todo o tempo de vida da operação, embora geralmente não a use até que EndReceive(IAsyncResult) seja chamado.You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndReceive(IAsyncResult) is called. No entanto, se você iniciar várias operações assíncronas, poderá inserir seus valores de IAsyncResult em uma matriz e especificar se deseja aguardar a conclusão de todas as operações ou de qualquer operação.However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. Nesse caso, você usa a propriedade AsyncWaitHandle do IAsyncResult para identificar a operação concluída.In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

Essa sobrecarga Especifica um tempo limite e um objeto de estado.This overload specifies a time-out and a state object. Se o intervalo especificado pelo parâmetro timeout expirar, esse componente gerará o evento ReceiveCompleted.If the interval specified by the timeout parameter expires, this component raises the ReceiveCompleted event. Como não existe nenhuma mensagem, uma chamada subsequente para EndReceive(IAsyncResult) gerará uma exceção.Because no message exists, a subsequent call to EndReceive(IAsyncResult) will throw an exception.

O objeto de estado associa informações de estado com a operação.The state object associates state information with the operation. Por exemplo, se você chamar BeginReceive várias vezes para iniciar várias operações, poderá identificar cada operação por meio de um objeto de estado separado definido por você.For example, if you call BeginReceive multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.

Você também pode usar o objeto State para passar informações entre threads de processo.You can also use the state object to pass information across process threads. Se um thread for iniciado, mas o retorno de chamada estiver em um thread diferente em um cenário assíncrono, o objeto de estado será empacotado e passado de volta junto com as informações do evento.If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.

Não use a chamada assíncrona BeginReceive com transações.Do not use the asynchronous call BeginReceive with transactions. Se você quiser executar uma operação assíncrona transacional, chame BeginPeeke coloque a transação e o método (síncrono) Receive dentro do manipulador de eventos criado para a operação de inspeção.If you want to perform a transactional asynchronous operation, call BeginPeek, and put the transaction and the (synchronous) Receive method within the event handler you create for the peek operation. O manipulador de eventos pode conter funcionalidades, conforme mostrado no C# código a seguir.Your event handler might contain functionality as shown in the following C# code.

myMessageQueue.BeginTransaction();  
 myMessageQueue.Receive();  
 myMessageQueue.CommitTransaction();  

A tabela a seguir mostra se esse método está disponível em vários modos de grupo de trabalho.The following table shows whether this method is available in various Workgroup modes.

Modo de grupo de trabalhoWorkgroup mode DisponívelAvailable
Computador localLocal computer SimYes
Computador local e nome de formato diretoLocal computer and direct format name SimYes
Computador remotoRemote computer NãoNo
Computador remoto e nome de formato diretoRemote computer and direct format name SimYes

See also

BeginReceive(TimeSpan, Object, AsyncCallback)

Inicia uma operação de recebimento assíncrona que tem um tempo limite e um objeto de estado especificados, que fornece informações associadas durante o tempo de vida da operação.Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. Essa sobrecarga recebe uma notificação, por meio de um retorno de chamada, da identidade do manipulador de eventos da operação.This overload receives notification, through a callback, of the identity of the event handler for the operation. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Object ^ stateObject, AsyncCallback ^ callback);
public IAsyncResult BeginReceive (TimeSpan timeout, object stateObject, AsyncCallback callback);
member this.BeginReceive : TimeSpan * obj * AsyncCallback -> IAsyncResult
Public Function BeginReceive (timeout As TimeSpan, stateObject As Object, callback As AsyncCallback) As IAsyncResult

Parameters

timeout
TimeSpan

Um TimeSpan que indica o intervalo de tempo para aguardar uma mensagem se tornar disponível.A TimeSpan that indicates the interval of time to wait for a message to become available.

stateObject
Object

Um objeto de estado, especificado pelo aplicativo, que contém informações associadas à operação assíncrona.A state object, specified by the application, that contains information associated with the asynchronous operation.

callback
AsyncCallback

O AsyncCallback que receberá a notificação da conclusão da operação assíncrona.The AsyncCallback that will receive the notification of the asynchronous operation completion.

Returns

IAsyncResult

O IAsyncResult que identifica a solicitação assíncrona postada.The IAsyncResult that identifies the posted asynchronous request.

Exceptions

O valor especificado para o parâmetro timeout não é válido.The value specified for the timeout parameter is not valid.

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.An error occurred when accessing a Message Queuing method.

Examples

O exemplo de código a seguir cria uma operação de recebimento assíncrono.The following code example creates an asynchronous receive operation. O exemplo de código envia uma mensagem para uma fila de mensagens local e, em seguida, chama BeginReceive(TimeSpan, Object, AsyncCallback), passando: um valor de tempo limite de dez segundos; um inteiro exclusivo que identifica essa mensagem específica; e uma nova instância de AsyncCallback que identifica o manipulador de eventos, MyReceiveCompleted.The code example sends a message to a local message queue, then calls BeginReceive(TimeSpan, Object, AsyncCallback), passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of AsyncCallback that identifies the event handler, MyReceiveCompleted. Quando um evento de ReceiveCompleted é gerado, o manipulador de eventos recebe a mensagem e grava o corpo da mensagem e o identificador da mensagem de número inteiro na tela.When a ReceiveCompleted event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen.

#using <System.Messaging.dll>
#using <System.dll>

using namespace System;
using namespace System::Messaging;

// Creates a new queue.
void CreateQueue(String^ queuePath, bool transactional)
{
    if (!MessageQueue::Exists(queuePath))
    {
        MessageQueue^ queue = MessageQueue::Create(queuePath, transactional);
        queue->Close();       
    }
    else
    {
        Console::WriteLine("{0} already exists.", queuePath);
    }
}

// Provides an event handler for the ReceiveCompleted event.
void HandleReceiveCompleted(IAsyncResult^ asyncResult)
{
    // Connect to the queue.
    MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

    // End the asynchronous receive operation.
    Message^ msg = queue->EndReceive(asyncResult);

    // Display the message information on the screen.
    Console::WriteLine("Message number: {0}", asyncResult->AsyncState);
    Console::WriteLine("Message body: {0}", msg->Body);

    queue->Close();
}

int main()
{
    // Represents a state object associated with each message.
    int messageNumber = 0;

    // Create a non-transactional queue on the local computer.
    // Note that the queue might not be immediately accessible, and
    // therefore this example might throw an exception of type
    // System.Messaging.MessageQueueException when trying to send a
    // message to the newly created queue.
    MessageQueue^ queue = nullptr;
    try
    {
        CreateQueue(".\\exampleQueue", false);

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

        // Send a message to the queue.
        queue->Send("Example Message");

        // Begin the asynchronous receive operation.
        queue->BeginReceive(TimeSpan::FromSeconds(10.0), messageNumber++,
            gcnew AsyncCallback(HandleReceiveCompleted));

        // Simulate doing other work on the current thread.
        System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));
    }
    catch (InvalidOperationException^)
    {
        Console::WriteLine("Please install Message Queuing.");
    }

    catch (MessageQueueException^ ex)
    {
        Console::WriteLine(ex->Message);
    }

    finally
    {   
        queue->Close();
    }
}

using System;
using System.Messaging;

public class QueueExample
{
    // Represents a state object associated with each message.
    static int messageNumber = 0;

    public static void Main()
    {
        // Create a non-transactional queue on the local computer.
        // Note that the queue might not be immediately accessible, and
        // therefore this example might throw an exception of type
        // System.Messaging.MessageQueueException when trying to send a
        // message to the newly created queue.
        CreateQueue(".\\exampleQueue", false);

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

        // Send a message to the queue.
        queue.Send("Example Message");

        // Begin the asynchronous receive operation.
        queue.BeginReceive(TimeSpan.FromSeconds(10.0), messageNumber++,
            new AsyncCallback(MyReceiveCompleted));
            
        // Simulate doing other work on the current thread.
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

        return;
    }

    // Creates a new queue.
    public static void CreateQueue(string queuePath, bool transactional)
    {
        if(!MessageQueue.Exists(queuePath))
        {
            MessageQueue.Create(queuePath, transactional);
        }
        else
        {
            Console.WriteLine(queuePath + " already exists.");
        }
    }

    // Provides an event handler for the ReceiveCompleted event.
    private static void MyReceiveCompleted(IAsyncResult asyncResult)
    {
        // Connect to the queue.
        MessageQueue queue = new MessageQueue(".\\exampleQueue");

        // End the asynchronous receive operation.
        Message msg = queue.EndReceive(asyncResult);

        // Display the message information on the screen.
        Console.WriteLine("Message number: {0}", (int)asyncResult.AsyncState);
        Console.WriteLine("Message body: {0}", (string)msg.Body);
    }
}

Remarks

Quando você usa essa sobrecarga, o retorno de chamada especificado no parâmetro de retorno de chamada é invocado diretamente quando uma mensagem fica disponível na fila ou quando o intervalo especificado de tempo expirou; o evento ReceiveCompleted não é gerado.When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the ReceiveCompleted event is not raised. As outras sobrecargas de BeginReceive dependem desse componente para gerar o evento ReceiveCompleted.The other overloads of BeginReceive rely on this component to raise the ReceiveCompleted event.

ReceiveCompleted também será gerado se uma mensagem já existir na fila.ReceiveCompleted is also raised if a message already exists in the queue.

Para usar BeginReceive, crie um manipulador de eventos que processa os resultados da operação assíncrona e associe-o ao seu representante de evento.To use BeginReceive, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. BeginReceive inicia uma operação de recebimento assíncrono; o MessageQueue é notificado, por meio da geração do evento ReceiveCompleted, quando uma mensagem chega na fila.BeginReceive initiates an asynchronous receive operation; the MessageQueue is notified, through the raising of the ReceiveCompleted event, when a message arrives in the queue. O MessageQueue pode então acessar a mensagem chamando EndReceive(IAsyncResult) ou recuperando o resultado usando o ReceiveCompletedEventArgs.The MessageQueue can then access the message by calling EndReceive(IAsyncResult) or retrieving the result using the ReceiveCompletedEventArgs.

O método BeginReceive retorna imediatamente, mas a operação assíncrona não é concluída até que o manipulador de eventos seja chamado.The BeginReceive method returns immediately, but the asynchronous operation is not completed until the event handler is called.

Como BeginReceive é assíncrono, você pode chamá-lo para receber uma mensagem da fila sem bloquear o thread atual de execução.Because BeginReceive is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. Para receber de forma síncrona uma mensagem, use o método Receive.To synchronously receive a message, use the Receive method.

Quando uma operação assíncrona for concluída, você poderá chamar BeginPeek ou BeginReceive novamente no manipulador de eventos para continuar recebendo notificações.Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

A IAsyncResult que BeginReceive retorna identifica a operação assíncrona que o método iniciou.The IAsyncResult that BeginReceive returns identifies the asynchronous operation that the method started. Você pode usar essa IAsyncResult durante todo o tempo de vida da operação, embora geralmente não a use até que EndReceive(IAsyncResult) seja chamado.You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndReceive(IAsyncResult) is called. No entanto, se você iniciar várias operações assíncronas, poderá inserir seus valores de IAsyncResult em uma matriz e especificar se deseja aguardar a conclusão de todas as operações ou de qualquer operação.However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. Nesse caso, você usa a propriedade AsyncWaitHandle do IAsyncResult para identificar a operação concluída.In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

O objeto de estado associa informações de estado com a operação.The state object associates state information with the operation. Por exemplo, se você chamar BeginReceive várias vezes para iniciar várias operações, poderá identificar cada operação por meio de um objeto de estado separado definido por você.For example, if you call BeginReceive multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.

Você também pode usar o objeto State para passar informações entre threads de processo.You can also use the state object to pass information across process threads. Se um thread for iniciado, mas o retorno de chamada estiver em um thread diferente em um cenário assíncrono, o objeto de estado será empacotado e passado de volta junto com as informações do evento.If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.

Não use a chamada assíncrona BeginReceive com transações.Do not use the asynchronous call BeginReceive with transactions. Se você quiser executar uma operação assíncrona transacional, chame BeginPeeke coloque a transação e o método (síncrono) Receive dentro do manipulador de eventos criado para a operação de inspeção.If you want to perform a transactional asynchronous operation, call BeginPeek, and put the transaction and the (synchronous) Receive method within the event handler you create for the peek operation. O manipulador de eventos pode conter funcionalidades, conforme mostrado no C# código a seguir.Your event handler might contain functionality as shown in the following C# code.

myMessageQueue.BeginTransaction();  
 myMessageQueue.Receive();  
 myMessageQueue.CommitTransaction();  

A tabela a seguir mostra se esse método está disponível em vários modos de grupo de trabalho.The following table shows whether this method is available in various Workgroup modes.

Modo de grupo de trabalhoWorkgroup mode DisponívelAvailable
Computador localLocal computer SimYes
Computador local e nome de formato diretoLocal computer and direct format name SimYes
Computador remotoRemote computer NãoNo
Computador remoto e nome de formato diretoRemote computer and direct format name SimYes

See also

BeginReceive(TimeSpan, Cursor, Object, AsyncCallback)

Inicia uma operação de recebimento assíncrona que tem um tempo limite especificado e usa um cursor especificado e um objeto de estado especificado.Initiates an asynchronous receive operation that has a specified time-out and uses a specified cursor and a specified state object. O objeto de estado fornece informações associadas em todo o tempo de vida da operação.The state object provides associated information throughout the lifetime of the operation. Essa sobrecarga recebe uma notificação, por meio de um retorno de chamada, da identidade do manipulador de eventos da operação.This overload receives notification, through a callback, of the identity of the event handler for the operation. A operação não é concluída até que uma mensagem se torna disponível na fila ou que ocorra o tempo limite.The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginReceive(TimeSpan timeout, System::Messaging::Cursor ^ cursor, System::Object ^ state, AsyncCallback ^ callback);
public IAsyncResult BeginReceive (TimeSpan timeout, System.Messaging.Cursor cursor, object state, AsyncCallback callback);
member this.BeginReceive : TimeSpan * System.Messaging.Cursor * obj * AsyncCallback -> IAsyncResult
Public Function BeginReceive (timeout As TimeSpan, cursor As Cursor, state As Object, callback As AsyncCallback) As IAsyncResult

Parameters

timeout
TimeSpan

Um TimeSpan que indica o intervalo de tempo para aguardar uma mensagem se tornar disponível.A TimeSpan that indicates the interval of time to wait for a message to become available.

cursor
Cursor

Um Cursor que mantém uma posição específica na fila de mensagens.A Cursor that maintains a specific position in the message queue.

state
Object

Um objeto de estado, especificado pelo aplicativo, que contém informações associadas à operação assíncrona.A state object, specified by the application, that contains information associated with the asynchronous operation.

callback
AsyncCallback

O AsyncCallback que recebe a notificação de conclusão de operação assíncrona.The AsyncCallback that receives the notification of the asynchronous operation completion.

Returns

IAsyncResult

O IAsyncResult que identifica a solicitação assíncrona postada.The IAsyncResult that identifies the posted asynchronous request.

Exceptions

O parâmetro cursor é null.The cursor parameter is null.

O valor especificado para o parâmetro timeout não é válido.The value specified for the timeout parameter is not valid.

Erro ao acessar um método do serviço de Enfileiramento de Mensagens.An error occurred when accessing a Message Queuing method.

Remarks

Quando você usa essa sobrecarga, o retorno de chamada especificado no parâmetro de retorno de chamada é invocado diretamente quando uma mensagem fica disponível na fila ou quando o intervalo especificado de tempo expirou; o evento ReceiveCompleted não é gerado.When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the ReceiveCompleted event is not raised. As outras sobrecargas de BeginReceive dependem desse componente para gerar o evento ReceiveCompleted.The other overloads of BeginReceive rely on this component to raise the ReceiveCompleted event.

ReceiveCompleted também será gerado se uma mensagem já existir na fila.ReceiveCompleted is also raised if a message already exists in the queue.

Para usar BeginReceive, crie um manipulador de eventos que processa os resultados da operação assíncrona e associe-o ao seu representante de evento.To use BeginReceive, create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. BeginReceive inicia uma operação de recebimento assíncrono; o MessageQueue é notificado, por meio da geração do evento ReceiveCompleted, quando uma mensagem chega na fila.BeginReceive initiates an asynchronous receive operation; the MessageQueue is notified, through the raising of the ReceiveCompleted event, when a message arrives in the queue. O MessageQueue pode então acessar a mensagem chamando EndReceive(IAsyncResult) ou recuperando o resultado usando o ReceiveCompletedEventArgs.The MessageQueue can then access the message by calling EndReceive(IAsyncResult) or retrieving the result using the ReceiveCompletedEventArgs.

O método BeginReceive retorna imediatamente, mas a operação assíncrona não é concluída até que o manipulador de eventos seja chamado.The BeginReceive method returns immediately, but the asynchronous operation is not completed until the event handler is called.

Como BeginReceive é assíncrono, você pode chamá-lo para receber uma mensagem da fila sem bloquear o thread atual de execução.Because BeginReceive is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. Para receber de forma síncrona uma mensagem, use o método Receive.To synchronously receive a message, use the Receive method.

Quando uma operação assíncrona for concluída, você poderá chamar BeginPeek ou BeginReceive novamente no manipulador de eventos para continuar recebendo notificações.Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

A IAsyncResult que BeginReceive retorna identifica a operação assíncrona que o método iniciou.The IAsyncResult that BeginReceive returns identifies the asynchronous operation that the method started. Você pode usar essa IAsyncResult durante todo o tempo de vida da operação, embora geralmente não a use até que EndReceive(IAsyncResult) seja chamado.You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndReceive(IAsyncResult) is called. No entanto, se você iniciar várias operações assíncronas, poderá inserir seus valores de IAsyncResult em uma matriz e especificar se deseja aguardar a conclusão de todas as operações ou de qualquer operação.However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. Nesse caso, use a propriedade AsyncWaitHandle do IAsyncResult para identificar a operação concluída.In this case, use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

O objeto de estado associa informações de estado com a operação.The state object associates state information with the operation. Por exemplo, se você chamar BeginReceive várias vezes para iniciar várias operações, poderá identificar cada operação por meio de um objeto de estado separado definido por você.For example, if you call BeginReceive multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.

Você também pode usar o objeto State para passar informações entre threads de processo.You can also use the state object to pass information across process threads. Se um thread for iniciado, mas o retorno de chamada estiver em um thread diferente em um cenário assíncrono, o objeto de estado será empacotado e passado de volta junto com as informações do evento.If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.

Não use a chamada assíncrona BeginReceive com transações.Do not use the asynchronous call BeginReceive with transactions. Se você quiser executar uma operação assíncrona transacional, chame BeginPeeke coloque a transação e o método (síncrono) Receive dentro do manipulador de eventos criado para a operação de inspeção.If you want to perform a transactional asynchronous operation, call BeginPeek, and put the transaction and the (synchronous) Receive method within the event handler you create for the peek operation. O manipulador de eventos pode conter funcionalidades, conforme mostrado no C# código a seguir.Your event handler might contain functionality as shown in the following C# code.

myMessageQueue.BeginTransaction();  
 myMessageQueue.Receive();  
 myMessageQueue.CommitTransaction();  

A tabela a seguir mostra se esse método está disponível em vários modos de grupo de trabalho.The following table shows whether this method is available in various Workgroup modes.

Modo de grupo de trabalhoWorkgroup mode DisponívelAvailable
Computador localLocal computer SimYes
Computador local e nome de formato diretoLocal computer and direct format name SimYes
Computador remotoRemote computer NãoNo
Computador remoto e nome de formato diretoRemote computer and direct format name SimYes

See also

Applies to

Thread Safety

O método não é thread-safe.The method is not thread safe.