HTTP Modules vs. SOAP Extensions

Before we start coding, it’s worth understanding the differences between the two types of components. Both allow you to process a request message before the Web method is actually called and to process the response before it leaves the Web server and is returned to the client—but at different points in the message’s life cycle.

A Message’s Life Cycle

As you’ll recall from Chapter 5, SOAP messages use the same pipeline as requests for ASP.NET pages to get to the service they are destined for.

A request is guided by Microsoft Internet Information Services (IIS) into the application domain of the Web application the target service is a part of. The HttpRuntime object generates an HttpApplication object to maintain the state of the application, if one doesn’t already exist, and it generates an HttpContext object that maintains information specific to the request in the application. When the HttpApplication object receives the request, it checks machine.config to see whether any HttpModule objects should be created to perform preprocessing and to see which HttpHandler object will actually handle the request. When the HttpHandler object has prepared a response to the request, those HttpModule objects might also postprocess the response message, if needed, before the HttpApplication object sends it back to the client. This cycle is depicted in Figure 10-1.

Figure 10-1: A closer look at HTTP modules in the grand scheme of the ASP.NET pipeline

It’s easy to see from this description where HTTP modules fit into the scheme of things. They work at the HTTP level and are implemented as autonomous parts of the ASP.NET pipeline. That is, if the .config file for a Web application includes an HTTP module in the pipeline, the HTTP module gets a crack at every message going in or out of the application’s pipeline, irrespective of the handler that will deal with the request or the target of the message.

SOAP extensions work at a different level. In fact, they bolt onto the default ASMX handler provided by ASP.NET and are therefore not easy to use in conjunction with your own handlers. Once the HttpApplication object has requested an instance of the ASMX handler from the ASP.NET WebServiceHandlerFactory class, that handler checks to see whether any extensions have been defined within the application. Each extension that is present and that is applicable to the request gets access to objects representing the request and response messages themselves rather than the streams carrying them. Figure 10-2 shows how extensions fit into the message life cycle.

Figure 10-2: SOAP extensions work within the default ASMX handlers.

SOAP extensions are more adaptable than HTTP modules. You can set them up to work autonomously with every response and request, just like HTTP modules, or you can apply them declaratively to individual methods exposed by a Web service. The second option offers flexibility that HTTP modules can’t provide. You can also use SOAP extensions on the client side when required. For instance, there would be little point in decompressing a SOAP request on the server side if it were not compressed by the client first. You can write a single extension and apply it on both the client side and the server side.

Practical Applications

Modules and extensions are suited to different tasks because they have different levels of access, autonomy, and applicability. Modules, for instance, give you access to the HTTP request and response messages in their entirety—not just the SOAP message in their body (if a SOAP message is to be found). Also, modules are specific not to Web services but to the Web applications that contain them. They react to a request for any item in a Web application, not just items with an .asmx file extension.

Uses for modules include the following:

• Implementing security (authentication, authorization, or encryption of HTTP messages)

• Caching responses

• Acting as an intermediary and routing requests to a different server

• Making the handling of the request a transaction

• Parsing HTTP headers for some reason other than those listed here

• Logging and tracing requests

• Logging server response times to requests

• Incorporating performance counters in the Web application

In contrast, an extension is the last code to see the request before the method is called and the first to see the method’s response. It has access only to the SOAP message (that is, no access to HTTP information), but it can access it as the XML contents of a stream (like a module does) and as the message is deserialized into .NET classes and objects. Extensions should thus implement small tasks, specific to a Web service or perhaps to just a Web method. They can do more than encapsulate a business rule, but a business rule is a good indication of the complexity of the tasks you should take on with extensions.

Uses for SOAP extensions include the following:

• Implementing security (encrypting and decrypting the SOAP message payload)

• Compressing and decompressing the SOAP message

• Converting messages intended for old versions of the method to the current version

• Parsing SOAP headers for some reason other than those already listed here

• Validating SOAP messages against their schemas

• Applying business rules to request parameters and return values

These lists of uses are not exhaustive, but they should get you thinking about which components might best serve your application. The remainder of this chapter will look at how each is implemented.