In the previous tip, we discussed DiffGrams and I showed what a DiffGram looked like in its native habitat. Since these creatures only come out under the cover of a SOAP message (and are therefore too fast for humans to see with the naked eye) we need a tool to capture a snapshot picture of what a SOAP message looks like during transfer between client and server. To do this, we're going to take a brief detour and talk about how ASP.NET works so we can then explain how SOAP Extensions will allow us to plug into and capture the SOAP stream before (or after) it gets transformed into an object that is processed by your Web Service code, and also capture the objects before (or after) they are transformed back into an outgoing SOAP message.
Consider the following diagram:
In this diagram, note how a request for an ASP.NET page (we'll say, a ASP.NET Web services page with an asmx file extension) is made to IIS. IIS recognizes this file extension and hands off the message to the .NET ISAPI object, which then sends the message down the call chain for Web services. The call chain consists of zero to many HTTP Modules that have been configured to be used for Web services. HTTP Modules are pluggable extensions that allow you to intercept the incoming or outgoing messages from your applications. You could use this to provide encryption/decryption, logging, etc. Finally, after the last HTTP Module is satisfied, the message is routed to the appropriate HTTP Handler that knows how to take care of aspx files. It provides the context and performs the logic of your particular application, then knows how to send a message back up the call chain. The message goes through the HTTP Modules, to IIS and is then routed back to the client.
The HTTP Handler for Web Services provides SOAP Extensions, which basically allow you one more opportunity to intercept the messages before or after they are handled by the HTTP Handler and your application's logic. SOAP extensions allow you to plug into the .NET Framework's SOAP architecture to perform some pre- or post-processing on SOAP messages. When the Web service's HTTP Handler receives a SOAP message, the SOAP message is de-serialized into objects (for example, SoapHeader objects or SoapMessage objects) and eventually passed into your Web method. Then after your Web method has finished, the result, as well as any SoapHeader objects or SoapException objects, are serialized into a SOAP message and sent back up the chain and to the client.
However, you can hook into the request chain before and after the SOAP message is de-serialized into objects, and after the Web method has finished processing and the objects are serialized back into SOAP messages.
When working with extensions, there are four "stages":
- BeforeDeserialize - This stage occurs before the SOAP message is de-serialized into objects and sent to the requested Web Service. Therefore, you still have access to the actual SOAP message.
- AfterDeserialize - This stage occurs after the SOAP message is de-serialized into objects and sent to the requested Web services, so you now have access only to the objects that represent the SOAP message, such as the SoapHeader object and the SoapMessage object.
- Before Serialize - This stage occurs after the Web service has finished processing and before the returned objects are serialized back into a SOAP message and sent to the client. Therefore, you still have access to all the objects that will ultimately be serialized into a SOAP message.
- AfterSerialize - This stage occurs after the Web service has finished processing and after the returned objects are serialized back into a SOAP message and sent to the client, so you now have access to the SOAP message being sent back to the client.
You might be wondering how SOAP extensions differ from HTTP Modules. First, you can selectively place SOAP extensions on certain Web methods, and ignore other ones, which is much more difficult to do with HTTP Modules. Second, you can access the de-serialized objects in the AfterDeserialize and BeforeSerialize stages, but you cannot access these objects in HTTP Modules; HTTP Modules allows you to see only the SoapMessage object, and little else. Third, it is easier to modify values before and after the Web method has processed the request by using extensions instead of HTTP Modules. HTTP Modules still serve a purpose however. It is just a matter of selecting the right tool for the job, so it's important to understand when to use each tool.
So now that I got you all excited about SOAP Extensions, I'm going to make you wait until the next tip to see the SOAP Extension in action because it is a pretty advanced feature of .NET and the code will require quite a bit of explanation. Stay tuned.
About the Author
Robert Tabor is a Microsoft Certified Professional in Visual Basic with over six years of experience developing n-tier Microsoft-centric applications for some of the world's most prestigious companies and consulting organizations, such as Ernst & Young, KPMG, Cambridge Technology Partners, Sprint, American Heart Association, and the Mary Kay Corporation. Bob is the author of Microsoft .NET XML Web services by Sams Publishing, and contributes to
SoapWebservices.com and LearnVisualStudio.NET. He is currently working on initiatives within Mary Kay, the second largest eCommerce site in retail volume on the net, of how to utilize .NET within their e-business group.
