Walkthrough: Altering the SOAP Message Using SOAP Extensions

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Developer's Guide

Walkthrough: Altering the SOAP Message Using SOAP Extensions

[Note: This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

SOAP extensions can be inserted into the .NET Framework SOAP message processing pipeline to modify or inspect a SOAP request or response message while it is being serialized or deserialized, on either the Web service or client. This step-by-step topic shows how to build and run a SOAP extension. For a picture of how SOAP extensions work, as well as the order in which SOAP extension methods are called in the message processing pipeline, see SOAP Message Modification Using SOAP Extensions.

During this walkthrough, you learn how to:

Derive a class from SoapExtension.
Save references to the Stream objects that represent future SOAP messages before and after the SOAP extension has done its processing.
Initialize SOAP extension specific data.
Process the SOAP messages during the applicable SoapMessageStage or stages.

Configure the SOAP extension to run with specific Web service methods.

Prerequisites

Derive a Class from SoapExtension.

The class that derives from SoapExtension is the class that performs the functionality of the SOAP extension. That is, if the SOAP extension is an encryption SOAP extension, then the class that derives from the SoapExtension class performs the encryption and corresponding decryption.

Save References to Stream Objects Representing Future SOAP Messages

To modify a SOAP message, you need to obtain a reference to the stream that can be used to obtain the contents of future SOAP messages. Your only opportunity to obtain this reference is to override the ChainStream(Stream) method.

To save references to Stream objects representing future SOAP messages

Override the ChainStream(Stream) method.

The ChainStream(Stream) method has the following signature:

public virtual Stream ChainStream(Stream stream)

Visual Basic

Public Overridable Function ChainStream(ByVal stream As Stream) As Stream

Within the ChainStream(Stream) implementation, assign the Stream instance passed as a parameter.
A reference to a Stream is passed into the ChainStream(Stream) once, prior to any SoapMessageStage. This Stream refers to the XML of the SOAP message after SOAP extensions of lower priority (see Configure the SOAP Extension to Run with Web Service Methods for details about SOAP extension priorities) have executed and made their changes to the SOAP message. A SOAP extension should assign this reference to a member variable for later access during the SoapMessageStage , when a SOAP extension inspects or modifies the SOAP message.
The Stream passed into ChainStream(Stream), however, is not the Stream a SOAP extension should modify.
Within the ChainStream(Stream) implementation, instantiate a new Stream, save a reference to it in a private member variable, and return the reference.
The following example demonstrates a common implementation of the ChainStream(Stream) method.

For an example of a common implementation of the ChainStream(Stream) method, see How to: Implement the ChainStream Method to Save References to Stream Objects.

Initialize SOAP Extension Specific Data

The class that derives from SoapExtension has two methods for initializing data, GetInitializer and Initialize(Object).

At what time the ASP.NET infrastructure calls the GetInitializer method, and what parameters are passed to the method, depend on how the SOAP extension is configured. (See SOAP Message Modification Using SOAP Extensions and Configure the SOAP Extension to Run with Web Service Methods.

To initialize data when the SOAP extension is configured using an attribute

Implement the GetInitializer method using the following signature:

public override object GetInitializer(LogicalMethodInfo methodInfo, SoapExtensionAttribute attribute)

Visual Basic

Public Overloads Overrides Function GetInitializer(methodInfo As _
   LogicalMethodInfo, attribute As SoapExtensionAttribute) As Object

The LogicalMethodInfo provides prototype details about the Web service method, such as the number of parameters and their data types.

If necessary, call the Initialize(Object) method, passing the object returned by GetInitializer. For many SoapExtension implementations, the Initialize(Object) method can be left empty.

To initialize data when the SOAP extension is configured in a configuration file

Implement the GetInitializer method with the following signature:
C#
```
public override object GetInitializer(Type WebServiceType)
```
Visual Basic
```
Public Overloads Overrides Function GetInitializer(WebServiceType As Type) As Object
```
The Type parameter is the type of the class of the class that implements the Web service.
If necessary, call the Initialize(Object) method, passing the object returned by GetInitializer. For many SoapExtension implementations, the Initialize(Object) method can be left empty.

For an example of how to initialize cached data when a SOAP extension is configured see, How to: Initialize Cached Data When a SOAP Extension is Configured.

Process the SOAP Messages

In the class derived from SoapExtension, the core piece of implementation is the ProcessMessage(SoapMessage) method. This method is called several times by ASP.NET at each of the stages defined in the SoapMessageStage enumeration.

To process SOAP messages

Implement the abstract ProcessMessage(SoapMessage) method.

The following implementation of the ProcessMessage(SoapMessage) method traces a call to a Web service. During the trace, if the SoapMessageStage indicates the parameters have been serialized into XML, the XML is written to a file.

public override void ProcessMessage(SoapMessage message) 
{
   switch (message.Stage) 
   {
   case SoapMessageStage.BeforeSerialize:
       break;
   case SoapMessageStage.AfterSerialize:
       // Write the SOAP message out to a file.
       WriteOutput( message );
       break;
   case SoapMessageStage.BeforeDeserialize:
       // Write the SOAP message out to a file.
       WriteInput( message );
       break;
   case SoapMessageStage.AfterDeserialize:
       break;
   default:
       throw new Exception("invalid stage");
   }
}

Visual Basic

Public Overrides Sub ProcessMessage(message As SoapMessage)
    Select Case message.Stage
      Case SoapMessageStage.BeforeSerialize
      Case SoapMessageStage.AfterSerialize
        ' Write the SOAP message out to a file.
        WriteOutput(message)
      Case SoapMessageStage.BeforeDeserialize
        ' Write the SOAP messae out to a file.
        WriteInput(message)
      Case SoapMessageStage.AfterDeserialize
      Case Else
        Throw New Exception("invalid stage")
    End Select
End Sub

Configure the SOAP Extension to Run with Web Service Methods

A SOAP extension can be configured to run using a custom attribute or by modifying a configuration file. A custom attribute is applied to a Web service method. When a configuration file is used, the SOAP extension runs with all Web services within the scope of the configuration file. For details on how configuration files work, see Configuring Applications.

To configure a SOAP extension using a custom attribute

Derive a class from SoapExtensionAttribute.
Implement two properties of SoapExtensionAttribute: ExtensionType and Priority. A SOAP extension should return the type of the SOAP extension in the ExtensionType property. The Priority property represents the relative priority of the SOAP extension, as explained in Applying the Priority Group in SOAP Message Modification Using SOAP Extensions.
Apply the custom attribute to each Web service method you want the SOAP extension to run with.

To configure a SOAP extension in a configuration file

If it is not already present, add a soapExtensionTypes XML element to the webServices section of the appropriate App.config or Web.config file.
Within the soapExtensionTypes XML element, add an add XML element for each SOAP extension you want to run with every Web service within the scope of the configuration file.
The add XML element has the following properties.
- type: specifies the type of the SOAP extension and the assembly it resides in.
- priority: Specifies the relative priority of the SOAP extension within its group.
- Group: specifies the group a SOAP extension is a member of.