When you think ASP, think...
Recent Articles xml
All Articles
ASP.NET Articles
Related Web Technologies
User Tips!
Coding Tips
spgif spgif

Book Reviews
Sample Chapters
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Stump the SQL Guru!
Web Hosts
Author an Article
spgif spgif

ASP ASP.NET ASP FAQs Feedback topnav-right
Print this Page!
Published: Wednesday, January 21, 2004

An Extensive Examination of Web Services: Part 7

By Scott Mitchell

An Extensive Examination of Web Services Index
An Extensive Examination of Web Services is a multi-part article series spanning several months. Listed below are the current "parts," along with a very brief synopsis and the date published.
  • Part 1 - Examines the basics of Web services, what Web services are, and the technologies and standards that serve as the underpinnings of Web services. (October 8th, 2003)
  • Part 2 - Examines creating Web services using Visual Studio .NET. Looks underneath the hood of the code created by VS.NET. (October 15th, 2003)
  • Part 3 - Examines creating a client application that consumes a Web service. Discusses the purpose and structure of a WSDL document, along with creating and using proxy classes to consume a Web service. (November 5th, 2003)
  • Part 4 - Examines the utility of Web services and common scenarios where Web services make sense. A business-oriented look at Web services. (November 19th, 2003)
  • Part 5 - Takes an in-depth look at XML serialization, which is the process of converting a data type, such as an integer, array, or custom class, into its XML representation, and back again. Every time a message is passed to or from a Web service, XML serialization transpires. (December 17th, 2003)
  • Part 6 - Looks at sending metadata to a Web method through the use of SOAP headers. Examines defining and accepting a SOAP header on the Web service end, and looks at sending a populated SOAP header from the client. (December 31st, 2003)
  • Part 7 - Examines how the incoming and outgoing messages to a Web service can be programmatically modified via SOAP Extensions. (January 21st, 2004)
  • Part 8 - Learn about the Web Service Enhancements (WSE) and Microsoft's free class library for implementing the WSE standards. (June 30th, 2004)
  • Part 9 - See how to implement UsernameToken authentication using the WSE 2.0 Toolkit. (July 14, 2004)
  • Part 10 - Learn how to send large amounts of data as attachments using DIME and WS-Attachments. (September 8th, 2004)
  • Part 11 - Create (and consume) client-side script-accessible Web Services using Microsoft's ASP.NET AJAX framework. (September 26th, 2007)


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:

- continued -

  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:
			case SoapMessageStage.AfterSerialize:
			case SoapMessageStage.BeforeDeserialize:
			case SoapMessageStage.AfterDeserialize:
				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

    Beginner's .NET XML Web Services

    Beginner's .NET XML Web Services DVD

    Beginner's .NET XML Web Services offers nearly eight hours of training on .NET XML Web services in a video format. This two-disc DVD set, presented by author Scott Mitchell, offers a unique opportunity for learning about the fundamentals of Web services. The 14 lessons begin with an examination of the core Web service standards, and then quickly move into showing you how to create and consume Web services in Microsoft's .NET Framework. There are in-depth lessons for each of the core Web service standards - XML, SOAP, and WSDL - along with examples of the Web Service Enhancements (WSE). Scattered throughout each of these chapters are extensive demos, depicting how to build, deploy, and access Web services using Microsoft's Visual Studio .NET. The DVD also contains a thorough examination of a real-world, end-to-end Web service application.

    Scott Mitchell is the editor and founder of 4GuysFromRolla.com, author of the An Extensive Examination of the Web Services article series, and author of numerous ASP and ASP.NET books.

    [Buy this DVD]

    Why get stuck with a 600-page paperweight when you can learn about .NET Web Services through an interesting and interactive video presentation?

  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article