Share via


Asynchronous Message Processing

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

You can retrieve messages asynchronously if you want to retrieve messages without tying up your application's processing. In asynchronous message processing, the method that starts a task is returned immediately without waiting for a result. The application can continue to do what it was originally doing while the task is completed. When the task finishes, the server can notify the application that the message was successfully processed.

There are two types of asynchronous messaging operations — receiving messages asynchronously and peeking at messages asynchronously. When you retrieve a message asynchronously, you use the BeginReceive method and the EndReceive method to mark the beginning and end of the operation. The actions that occur are as follows:

  • The BeginReceive method returns immediately and raises an event called ReceiveCompleted when a message becomes available on the queue or if the message you are peeking at or receiving already exists.

  • The ReceiveCompleted event returns an object of type IAsyncResult that contains information about the asynchronous operation.

  • After the completed event is received, you call the EndReceive method to complete the operation. Within the end call, you might access the message or retrieve it by accessing the ReceiveCompletedEventArgs class.

You can access the IAsyncResult object throughout the lifetime of the operation, but typically you will not use it until EndReceive is called. 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 individual operation to finish. In this case, you use the AsyncWaitHandle property of the IAsyncResult object to identify completed operations.

Peek, like Receive, uses two methods called BeginPeek and EndPeek to bracket the beginning and end of the asynchronous operation. BeginPeek returns immediately and raises an event called PeekCompleted when a message becomes available. Like ReceiveCompleted, this event returns an IAsyncResult object that you can manipulate for information about the operation.

In addition, both asynchronous receive and peek operations can use a time-out period to specify how long you want to wait for a message to become available. To do so, you use an overloaded form of either method to pass a TimeSpan object that indicates the time to wait. The ReceiveCompleted or PeekCompleted event is raised if the time-out period expires, but the IsCompleted property on the IAsyncResult object is set to false to indicate that a message was not dealt with.

For more information on asynchronous processing, see the following pages:

For

See

Step-by-step instructions on receiving a message asynchronously

How to: Receive Messages Asynchronously

An overview of the BeginPeek method and its members

BeginPeek

An overview of the BeginReceive method and its members

BeginReceive

Receiving Notification of Your Asynchronous Operation

There are two ways you can receive notification when your asynchronous receive or peek operation completes successfully:

  • You can create an event handler that will handle the ReceiveCompleted or PeekCompleted events when they occur.

  • You can use a callback to automatically watch for incoming messages and pass processing to your application when a message arrives.

When you use event notification, you create a method that handles your message processing and returns a notification when the processing finishes. You then call the method that begins the asynchronous processing. The system creates the event handlers for you automatically when you double-click your MessageQueue component in the designer.

Note

In the event-notification scenario, BeginPeek or BeginReceive returns a single message and then stops processing. You must call BeginPeek or BeginReceive again for each message you want to retrieve.

An alternate way to process messages asynchronously is to use a callback. A callback identifies a delegate you want to associate with your BeginPeek or BeginReceive operations. In this scenario, the delegate continues to watch for new event notification after each message is processed.

See Also

Tasks

How to: Receive Messages Asynchronously

How to: Peek at Messages

How to: Receive Messages Programmatically

Other Resources

Reading and Receiving Messages