|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
Communicating with XML Web Services Asynchronously
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.
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:
|Method name in proxy class||Description|
Sends a message for the Web service method named <NameOfWebServiceMethod> synchronously.
Begins asynchronous message communication with a Web service method named <NameOfWebServiceMethod>. The client instructs the Begin method to start processing the service call, but return immediately. The return value is not the data type specified by the Web service method, but rather a type implementing the IAsyncResult interface.
Ends an asynchronous message communication with a Web service method named <NameOfWebServiceMethod>, returning a value that is the result of the Web service method call.
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.
Asychronous Web Service Clients Using the Event-Driven 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 . For details about client implementations using the new model, see .
To see how to build a Web service using the event-driven pattern, see.