To read the article online, visit http://www.4GuysFromRolla.com/articles/012104-1.aspx

An Extensive Examination of Web Services: Part 7

By Scott Mitchell


Introduction


As we discussed in Part 1 of this article series, a Web service is invoked with a client sending a SOAP-formatted message to the server where the Web service resides. The server then:

  1. Receives this message,
  2. Determines what method the user wants to invoke and with what input parameters,
  3. Invokes the specified method using the specified input parameters, generating a return value, and finally
  4. Sends this result back to the client as a SOAP-formatted message.

If you've read the previous six parts of this article series you're likely very comfortable with this chain of events. Did you know that you can write your own code on the server that can intercept SOAP messages both before and after the Web service method is invoked? This code could do a number of things, such as check to make sure that certain XML elements existed in the SOAP payload. It could also alter the SOAP messages contents.

The technique by which SOAP messages can be intercepted are tinkered with is called SOAP Extensions. In this article we'll examine what SOAP Extensions are, how they work, and their benefits in building Web services.

SOAP Extension Basics


In an earlier article of mine, How ASP.NET Web Pages are Processed on the Server, I looked at what happens when a Web server receives a request for an ASP.NET Web page. As discussed in that article, IIS - the Web server - routes the request to the ASP.NET engine, which then passes the request through specified HTTP modules and then to a specific HTTP handler or HTTP handler factory. When a request comes in for an ASP.NET Web page, the handler invoked is the PageHandlerFactory, which essentially points to the compiled class that represents the ASP.NET Web page.

With Web services, the HTTP handler factory used is WebServiceHandlerFactory. As with requests to ASP.NET Web pages, requests to Web services pass through the specified HTTP modules, but they also pass through any number of configured SOAP Extensions. A SOAP Extension is akin to an HTTP module - it provides a place to add code that will inspect the incoming or outgoing request and, perhaps, do something based on that incoming or outgoing data. The figure below depicts the series of events when a request is made for a Web service.

SOAP Extension diagram.

This diagram shows that an incoming request passes through a pipeline of HTTP modules and then a pipeline of SOAP Extensions before the actual Web service method is invoked. Similarly, when the Web service returns its response the outgoing message goes back through the SOAP Extension and HTTP module pipelines.

SOAP Extensions provide four opportunities for tapping into the message:

  • For incoming messages...
    • BeforeDeserialize - this stage occurs right before the SOAP formatted message is deserialized back into an object.
    • AfterDeserializae - the stage just after the SOAP message has been deserialized back into an object.
  • For outgoing messages...
    • BeforeSerialize - the stage just prior to the object being serialized into a SOAP message.
    • AfterSerialize - the stage after the object has been serialized into a SOAP message.

(If you are unfamiliar with what serialization and deserialization are, be sure to take a look at Part 5 of this article series, which examines XML serialization in .NET Web services in-depth...)

Building SOAP Extensions


SOAP Extensions are created by building a class that derives from System.Web.Services.Protocols.SoapExtension. This base class has a number of methods that need to be overridden, but the one of prime importance is ProcessMessage(). The ProcessMessage() executes four times during each Web service method invocation, once for each of the four stages discussed above. The following shows the shell of the ProcessMessage() method. When writing your own SOAP Extension you'd call methods during one or more of the four stages, depending on what you wanted to accomplish with your SOAP Extension.
public class MySOAPExtension : SoapExtension 
{
	public override void ProcessMessage(SoapMessage message) 
	{
		switch (message.Stage) 
		{
			case SoapMessageStage.BeforeSerialize:
				break;
			case SoapMessageStage.AfterSerialize:
				break;
			case SoapMessageStage.BeforeDeserialize:
				break;
			case SoapMessageStage.AfterDeserialize:
				break;
			default:
				throw new Exception("invalid stage");
		}
	}
}

Unfortunately, SOAP Extensions are not nearly as easy to create as Web services. SOAP Extensions require a number of base class methods to be overridden in addition to ProcessMessage(). Also after creating a SOAP Extension you have to configure it to execute when a Web service or Web service method is called. There are two ways to accomplish this:

  • Add a setting to the Web.config file, which will have the SOAP Extension execute for all methods in the Web service, or
  • Create an Attribute class that can be applied to methods. Then you can indicate what Web service methods should use the SOAP Extension by adding the Attribute to the method. (An example of an Attribute is the [WebMethod()] attribute that prefixes methods of a Web service...)

There are numerous articles on the Web that delve into creating your own SOAP Extensions. I am not going to illustrate building a fully functional SOAP Extension here, but rather direct you to these other resources. The articles I recommend that you read before trying to build your first Web service include:

The Benefits of SOAP Extensions


The main benefit of SOAP Extensions is that they provide a way to plug code inbetween the incoming SOAP message and the Web method that will handle the request. The Web service's methods are oblivious to the existence of SOAP Extensions, meaning that SOAP Extensions provide a level of encapsulation for Web services. For example, in Part 6 of this article series we looked at SOAP Headers and how a username and password could be passed through SOAP Headers. With this approach we examined in Part 6, each Web method that required the user authenticate themselves would then have to ensure that the username and password were valid. Using SOAP Extensions we could move this check out of the method and into a SOAP Extension.

That is, a SOAP Extension could be created that would examine the SOAP Headers, pick out the username and password, and make sure that the credentials were valid. If not, it could terminate the Web method request. If the credentials were valid, the request would pass on to the applicable Web method. With this technique, the Web service method would not need to check to ensure that the user's credentials were valid - if the method got invoked it could be certain that it was dealing with an authorized user.

In the next part of this article series we'll begin our examination of the Web Service Enhancements (WSE). The Web service standards, as we've seen, only spell out how messages are formatted (SOAP) and how a Web service is formally defined (WSDL). WSE introduces standards for accomplishing a bevy of commonly needed Web service-related functionality, such as:

  • Authentication
  • Sending binary attachments
  • Encryption
  • Addressing
  • And many more!

WSE, as we'll see, relies heavily on SOAP Headers to provide the needed functionality. Microsoft provides a WSE Toolkit for .NET Web services that makes utilizing the WSE standards incredibly easy. The WSE Toolkit uses SOAP Extensions to provide WSE support. More on all of this later!

Happy Programming!

  • By Scott Mitchell


  • Article Information
    Article Title: ASP.NET.An Extensive Examination of Web Services: Part 7
    Article Author: Scott Mitchell
    Published Date: January 21, 2004
    Article URL: http://www.4GuysFromRolla.com/articles/012104-1.aspx


    Copyright 2014 QuinStreet Inc. All Rights Reserved.
    Legal Notices, Licensing, Permissions, Privacy Policy.
    Advertise | Newsletters | E-mail Offers