Communicating with XML Web Services Asynchronously

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

Communicating with a Web service asynchronously follows the two asynchronous method invocation design patterns specified by the .NET Framework. Before you get to those details, however, it is important to note that a Web service does not have to be specifically written to handle asynchronous requests to be called asynchronously.

Wsdl.exe and the .NET Framework Asynchronous Design Pattern

When the Web Services Description Language tool (Wsdl.exe) generates a client proxy class to access a specified Web service, it provides the proxy class with two mechanisms for communicating with each Web service method asynchronously. The first mechanism is the Begin/End pattern. The second mechanism is the event-driven asynchronous programming pattern available in version 2.0 of the .NET Framework. For a brief description of using the patterns with Web services, see the following sections. For complete details about both patterns, see Asynchronous Programming Design Patterns.

The Begin/End Invocation Pattern

Wsdl.exe automatically creates three methods for each operation (a Web service method in ASP.NET) published in the Web service. One method is for synchronous access; the other two are for asynchronous access. This is true even if there is only a synchronous implementation of the Web service method. The following table describes those three methods:

The Begin and End methods follow the naming convention for the .NET Framework's asynchronous design pattern. The design pattern predicates that there are two asynchronous methods named as such for each synchronous method.

For an example, consider a Web service class PrimeFactorizer that has a Web service method that searches for prime factors, with the following signature:

public long[] Factorize(long factorizableNum)

Such a method could take a relatively extended period of time to finish processing, depending on the input. Thus, it is a good example of when you should have your Web service client to call the Web service method asynchronously.

If Wsdl.exe used this Web service as an input for generating client proxy code (using the ?wsdl query string for an ASP.NET Web service), it would generate methods with the following signatures:

public long[] Factorize(long factorizableNum)
public System.IAsyncResult BeginFactorize(long factorizableNum, System.AsyncCallback callback, object asyncState)
public long[] EndFactorize(System.IAsyncResult asyncResult)

Implementing a Web Service Client That Makes an Asynchronous Method Call Using the Begin/End Pattern

How does a client know when to call the End method? There are two techniques for implementing a client to determine this, as defined by the .NET Framework:

• Wait technique: Use one of the methods of the WaitHandle class to cause a client to wait for the method to complete.

• Callback technique: Pass a callback function into the Begin method, which is then called to retrieve the results when the method has completed processing.

Note: Regardless of which of the two techniques a client chooses to communicate with a Web service asynchronously, the SOAP messages sent and received are identical to the SOAP messages generated through the synchronous proxy method. That is, there is still only one SOAP request and SOAP response sent and received across the network. The proxy class accomplishes this by handling the SOAP response using a different thread than the thread the client used to call the Begin method. Therefore, the client can continue to perform other work on its thread, while the proxy class handles receiving and processing the SOAP response.

Wait Technique Using the Begin/End Pattern

The WaitHandle class implements methods that support waiting for synchronization objects to be signaled: WaitOne, WaitAny, and WaitAll. The signaling of a synchronization object is an indication that threads waiting upon the specified resource can then access the resource. The Web service client accesses a WaitHandle object through the AsyncWaitHandle property of the IAsyncResult object returned by the Begin method.

For an example of this technique, see How to: Implement an Asynchronous Web Service Client Using the Wait Technique.

Callback Technique Using the Begin/End Pattern

With the callback technique, a callback function implements the AsyncCallback delegate, which enforces the signature:

public void MethodName(IAsyncResult ar)

For an example of this technique, see How to: Implement an Asynchronous Web Service Client Using the Callback Technique.

If the callback requires synchronized/thread-affinity context, it is dispatched through the context dispatcher infrastructure. In other words, the callback might execute asynchronously with respect to its caller for such contexts. That is precisely the semantics of the one-way qualifier on method signatures. It means that any such method call might execute synchronously or asynchronously, with respect to the caller, and the caller cannot make any assumptions about completion of such a call when execution control returns to it.

Calling the End method before the asynchronous operation is complete will block the caller. The behavior for calling it a second time with the same IAsyncResult returned by the Begin method is undefined.

Asynchronous Web Service Clients Using the Event-Driven Asynchronous Pattern

Multithreaded Programming with the Event-based Asynchronous Pattern introduces a new asynchronous programming model that uses events to handle callbacks, making it easier to build multithreaded applications without having to implement complex multithreaded code yourself. For an overview of the new event-driven asynchronous model, see Event-based Asynchronous Pattern Overview. For details about client implementations using the new model, see How to: Implement a Client of the Event-based Asynchronous Pattern.

To see how to build a Web service using the event-driven pattern, see How to: Implement an Event-Driven Asynchronous Web Service Client Using ASP.NET 2.0.

See Also

Tasks

How to: Implement an Asynchronous Web Service Client Using the Wait Technique
How to: Implement an Asynchronous Web Service Client Using the Callback Technique
How to: Make an Asynchronous Call from a Web Service Client

Concepts

Building XML Web Service Clients
Design Guidelines for XML Web Services Created Using ASP.NET

Other Resources

Creating Clients for XML Web Services