Working With Asynchronous .NET Web Service Clients
by Kenn Scribner of Wintellect
While many developers realize that consuming Web Services using the asynchronous call mechanisms built into .NET is useful, they also find it confusing. If you've had trouble trying to use the asynchronous call methods in your generated proxies—or if you're wondering what asynchronous means in the first place—this article helps clarify some things and makes your programming tasks (at least as related to asynchronous processing) a little easier.
The general discussion focuses on consuming .NET Web Services, but because asynchronous processing is built into .NET, the information is applicable to any asynchronous processing you might want to perform. That is, when you create a proxy for your Web Service, the asynchronous methods are baked in. But, you also have similar asynchronous methods built into your .NET delegate classes and therefore also can utilize delegates in an asynchronous fashion (hmm, perhaps fodder for another article: using .NET delegates as the poor man's multithreaded processing platform?).
Web Service Proxies
To be clear about Web Services and their consumption, Figure 1 presents the basic architecture.
Figure 1: Generalized Web Service Communication Architecture
The ultimate goal of a Web Service is to give the client the illusion that remote resources and processing capabilities are actually present on the client computer. For this to occur, some software on the client must generate and issue the request (as well as interpret the response), and some software on the server must accept requests, translate them into formats the server can work with, and activate the server-side processing itself. The first of these pieces of software is known as the proxy, because it simulates the server on the client. The proxy communicates with some form of stub, whose job is to take the SOAP-based XML and convert it into binary information resident within the server's memory. The stub also initiates the server-side processing.
When you use .NET to consume Web Services, it can create this proxy for you automatically, either with Visual Studio or the tool that ships with .NET itself, Wsdl.exe. Either tool queries the Web Service for its service description, as described by the Web Service Description Language (WSDL), and then generates the proxy source code for you by interpreting the WSDL it finds.
If you open the proxy source code you've been given, you should find all of the Web-based methods exposed by the Web Service. But, you'll also find some curiously named methods beginning with "Begin" and "End" and ending with the Web methods you'd expect. That is, if the Web Service exposed a single method named "CalcPayment," in your proxy you would find executable code for not only CalcPayment itself, but also for BeginCalcPayment and EndCalcPayment. You will use these "begin" and "end" methods for your asynchronous processing.
What exactly is asynchronous processing and why should you be concerned about using it? To answer that, let me first ask you a question: How do you feel when an application's user interface locks for some extended period of time while it processes your selected action? Most of us tend to dislike that kind of application behavior—and I'm being kind here.
Instead, we prefer our user interfaces responsive, even when working on actions we know to be lengthy. If that action involved a call to a Web Service, especially one over the Internet (versus simply a local one found on our intranet), the request might take quite a bit of time to process. Delays from 200 milliseconds up to full seconds are not uncommon. For example, say a given Web Service takes on average of 600 milliseconds to complete, but the user waits over half a second for each call. That might not seem like much, but to a user it could prove to be a major annoyance. Remember, the user interface locks entirely for this call duration.
The process thread used to make the call to the Web Service causes the locking phenomenon. The user interface usually locks up because the thread servicing the user interface (button clicks, painting behavior, and so forth) is also the very same thread making an extended call somewhere else, waiting for data. It might be a Web Service call, but it also might be some lengthy local financial calculation, database query, or whatever. Anything that takes a significant amount of time to process, if serviced by the same thread that manages the user interface, will cause the user interface to cease taking inputs from the user and appear to be locked. In general, try to avoid this. Such behavior has been known to cause users to throw keyboards, break monitors, and worst of all, no longer purchase your software.
Getting back to asynchronous processing, my dictionary defines asynchronous as "pertaining to a transmission technique that does not require a common clock between the communicating devices." Overlooking the clock reference, you could rewrite this definition in its loosest terms to read something like "asynchronous processing is a form of multithreaded programming where a primary thread activates a lengthy process to be managed by a secondary thread." The primary thread's task is complete when the process is activated, so it can (almost immediately) return to its main function, which in this case might be managing the user interface. The secondary thread then begins the lengthy process and sustains the wait, a procedure known as blocking. It locks and ceases processing, waiting for the lengthy process to terminate. It then (optionally) reports back to the primary thread the results of the process.
A side benefit of this is that you then can easily make multiple such processing calls in parallel. If the primary thread made multiple calls (synchronously, on the same thread), each synchronous call would need to be made sequentially, thus increasing the processing time greatly.
Asynchronous .NET Web Requests
In the case of a Web Service called using the proxy's asynchronous call methods, the secondary thread is actually a thread from the .NET thread pool. What's great about that is you don't need to create and manage your own thread (or pool of threads, which is even more complicated). Instead, when you call the "begin" method found in your proxy, you pass into that a callback function .NET will use to provide the Web Service response to your application. Always remember that when your callback function is executed, the .NET thread executes it, not the primary thread (which is most likely the thread that created your user interface). I'll revisit this a bit later in this discussion.
Although not the only way to process asynchronous Web Service calls, I finalize the call to the Web Service by extracting the resultant parameter values, as well as the method return value, in the callback function. This finalization is the call to the "end" method found in your Web Service proxy. The "end" method retrieves the resulting parameter objects (out and ref parameters), as well as the return value, and provides them to you for further processing. The beauty is that your primary thread doesn't have to block while waiting for the Web Service to complete. Instead, a .NET thread is used, and your user interface is free to continue to accept user inputs and be just as responsive and snappy as it was prior to the Web Service invocation. Later, when the call is complete, you can marshal the data back to your user interface thread and do whatever is necessary at that point.
You could, if you desire, perform some wait processing in your main thread (a technique for this is described in the MSDN article "Communicating with XML Web Services Asynchronously"). Personally, I find this to be of limited value because you're still employing the primary thread to perform the wait processing. But, I would be remiss if I didn't at least mention it.
Asynchronous Behavior Is a Client-Side Phenomenon
No matter how you call your Web Service, synchronously or asynchronously, each call is the same to the Web Service. You're still sending in one SOAP packet, and you'll still (hopefully) receive a single SOAP packet in response.
Marshaling—a Side Note for Windows User Interface Programmers
Marshaling—what an ugly sounding word. It harkens back to the old COM programming days when we had to deal with passing data between threads. Oh, but that's exactly what we're doing here! Uh-oh. Actually, it's not so bad. Marshaling basically is the process of converting information for communication between threads.
Because Windows is a virtual, memory-based operating system, memory addresses are meaningless between processes. If you pass information between processes based upon that information's memory address, it will have no meaning in the other process and this second process likely will crash. Old COM programmers (and I include myself here) know this all too well.
Fortunately, .NET handles marshaling for you without too much effort on your part. The age-old Windows rule that only—and I mean only—the thread that created a window can update that window's state also helps. Therefore, you can't just change window text, color, shape, size, or political affiliation willy-nilly without making sure you're doing so from the thread that created the window. Forget this fact and Windows becomes unpredictable. Sometimes things work, and sometimes they don't. If you follow the basic rule, though, and always let the window's creating thread update the window, your code (and application) won't crash and burn.
Delegates in .NET
If you look into your MSDN documentation under System.Windows.Forms.Control, you'll find a curious method called Invoke(). The first sentence of the associated documentation page reads: "Executes a delegate on the thread that owns the control's underlying window handle." Wow, that sounds a lot like "the thread that created the window." But what's this "executes a delegate" stuff?
We're back into the guts of .NET, but this time we're looking at the delegate and its relationship to events and event handling. If you create a delegate that has as its parameters the very same parameters that the Web Service returned, .NET will marshal those parameters for you and ship them to the particular window's creation thread. There you have it! The parameters are now available to the window's creating thread, so at that point you can update the window to your heart's content. Easy, right?
The truth is it isn't too bad, once you've seen it in action. In .NET terms, a delegate is essentially a type-safe callback function. So, what you need to do utilize it is:
- Design a method in your application that accepts the same parameters the Web Service returned;
- Designate it as a delegate data type; and
- Create one of these delegates for use with Invoke().
I'll show some code for this shortly. But first, back to asynchronous Web Service calls in general.