How to: Create and Add a Custom Output Filter

Article
09/15/2006

Output filters are used by the Web Services Enhancements for Microsoft .NET (WSE) to process the SOAP envelope of an outgoing message. Several filters are built into WSE for features such as security and routing. You can create a custom filter, or a collection of such filters, that can be applied to any outgoing message. This collection of custom filters is added to the collection of filters returned by the OutputFilters property of the Pipeline class. To filter any message, call the ProcessOutputMessage method, which applies each filter in the collection to the outgoing SOAP envelope. As each filter is applied, the ProcessMessage method is called to modify the SOAP envelope.

The following procedure explains how to add a custom output filter to an XML Web application. The procedure consists of two steps:

Creating the custom output filter.
Adding the custom output filter to the Web application.

To create a custom output filter

Create a class library project in Visual Studio .NET 2003 called CustomFilterLibrary.
1. Start Visual Studio .NET 2003.
2. On the File menu, point to New, and then click Project.
3. In the Project Types pane, select Visual C# Projects.
4. In the Templates pane, select Class Library.
5. In the Name box, enter the library name: CustomFilterLibrary
6. Click OK.
Add references to the Microsoft.Web.Services2 assembly.
1. In Solution Explorer, right-click References, and then click Add Reference.
2. Click the .NET tab, select Microsoft.Web.Services2.dll, and then click Select.
3. Click OK.
Add Imports or using directives to the top of the file that implements the custom output filter.
1. In Solution Explorer, right-click the file containing the client code, and then click View Code.
2. At the top of the file, add the Imports or using directives as shown in the following code example.
```
Imports System
Imports System.Xml
Imports Microsoft.Web.Services2
Imports System.Collections
```
```
using System;
using System.Xml;
using Microsoft.Web.Services2;
using System.Collections;
```

Create a class that derives from the SoapOutputFilter class and overrides the ProcessMessage method. Place the class in its own namespace, and implement the method to add a new header.

Note

If the custom filter is signing or encrypting a custom SOAP header, the SOAP header must contain an Id attribute that uses the XML namespace prefix and XML namespace specified by the fields WSUtility.Prefix and WSUtility.NamespaceURI, respectively

Namespace CustomFilterLibrary
    ' Class derives from the SoapOutputFilter class.
    Public Class CustomerGroupOutputFilter
      Inherits SoapOutputFilter

        ' This is an empty constructor.
        Public Sub New()
        End Sub 'New


        ' Override the ProcessMessage method.
        Public Overrides Sub ProcessMessage(envelope As SoapEnvelope)
            If envelope Is Nothing Then
                Throw New ArgumentNullException("No envelope!")
            End If
            Dim CustomerGroupId As String = _
              CType(envelope.Context("CustomerGroupId"),String)
            If Not (CustomerGroupId Is Nothing) Then
                ' Add a new CustomerGroup header.
                Dim node As XmlElement = _
                  envelope.CreateElement("CustomerGroup", _
                  "http://cohowinery.com/CustomFilterSample")
                node.InnerXml = "<Id>" + CustomerGroupId + "</Id>"
                envelope.CreateHeader().AppendChild(node)
            End If
        End Sub
    End Class
End Namespace

namespace CustomFilterLibrary 
{
    // Class derives from the SoapOutputFilter class.
    public class CustomerGroupOutputFilter : SoapOutputFilter
    {
        public CustomerGroupOutputFilter()
        {
            // This is an empty constructor.
        }

        // Override the ProcessMessage method.
        public override void ProcessMessage(SoapEnvelope envelope)
        {
            if (envelope == null)
                throw new ArgumentNullException("No envelope!");
            string CustomerGroupId = 
                envelope.Context["CustomerGroupId"] as String;

            if(CustomerGroupId != null)
            {
                // Add a new CustomerGroup header.
                XmlElement node =
                    envelope.CreateElement("CustomerGroup", 
                    "http://cohowinery.com/CustomFilterSample");
                node.InnerXml = "<Id>" + CustomerGroupId + "</Id>";
                envelope.CreateHeader().AppendChild(node);
            }
        }
    }
}

To add a custom output filter to a Web application

Open the Web service client or Web service project in Visual Studio .NET 2003 and register the output filter for the project.
1. In Solution Explorer, right-click the file containing the application's configuration file.
2. Add a <section> Element (WSE for Microsoft .NET) element to the <configuration> section for the Web.config file that affects the Web service.
  This adds the Microsoft.Web.Services2 configuration section handler for this configuration file. The following code example shows how to add the microsoft.web.services2 configuration section handler.
```
<configuration>
   <configSections>
      <section name="microsoft.web.services2"
               type="Microsoft.Web.Services2.Configuration.WebServicesConfiguration, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   </configSections>
</configuration>
```
3. In the configuration file, add the following XML under the <configuration> element, where CustomFilterLibrary is the namespace of your custom output filter and the library's assembly name and CustomerGroupOutputFilter is the name of the custom output filter class.
```
<microsoft.web.services2> 
    <filters>
        <output>
            <add type="CustomFilterLibrary.CustomerGroupOutputFilter, 
                CustomFilterLibrary"/>
        </output>
    </filters>
</microsoft.web.services2>
```

The following code example shows a sample outgoing SOAP message with the <CustomerGroup> element added.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope
    xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing"
    xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header>
      <wsa:Action wsu:Id="Id-f9c4ab88-fdc3-437b-93d8-26b1fd4442f6">http://tempuri.org/EchoCustomerGroupId</wsa:Action>
      <wsa:MessageID wsu:Id="Id-34772810-76d4-4025-bc6e-e1f92b5e93a4">uuid:289c3840-f48e-4122-902b-4ab3d0b5f233</wsa:MessageID>
      <wsa:To wsu:Id="Id-f2b11a65-1db1-4349-858f-24471753e40a">https://localhost/CustomFiltersService</wsa:To>
      <wsse:Security soap:mustUnderstand="1">
        <wsu:Timestamp wsu:Id="Timestamp-04d43cd9-68c3-4413-958d-b9b13d866f9f">
          <wsu:Created>2004-04-17T15:09:38Z</wsu:Created>
          <wsu:Expires>2004-04-17T15:14:38Z</wsu:Expires>
        </wsu:Timestamp>
      </wsse:Security>
      <CustomerGroup           xmlns="http://cohowinery.com/CustomFilterSample">          <Id >467</Id>      </CustomerGroup>
    </soap:Header>
    <soap:Body>
        <EchoCustomerGroupId 
            xmlns="http://tempuri.org/" />
    </soap:Body>

Share via

How to: Create and Add a Custom Output Filter

To create a custom output filter

To add a custom output filter to a Web application

See Also

Tasks

Concepts

Additional resources