Controlling the Filters in the Pipeline

As we pointed out earlier, all the filters are enabled by default, but in many cases this won’t be what you need. Passing through unused filters adds overhead to the Web service call, and you might want to use different filters for incoming and outgoing messages. When we look at developing custom filters later in the chapter, you’ll also see that you also need the ability to add and insert filters into the pipeline.

You gain access to the input and output pipelines by using the InputFilters and OutputFilters properties of the FilterConfiguration object exposed by the static WebServicesConfiguration.FilterConfiguration property. These properties return a SoapInputFilterCollection or a SoapOutputFilterCollection that derives from the CollectionBase class. The CollectionBase class provides methods to manipulate the collection; using these, you can add and remove filters from the pipeline.

Note

You also have access to a SoapInputFilterCollection and a SoapOutputFilterCollection object via the Pipeline property of the WebServicesClientProtocol class that’s the base class of the proxies you use. It returns the filters that are in use for the current proxy and allows you to modify the filters that the current proxy is using without modifying the filters that the rest of the application is using. Only by changing the collections returned from the WebServicesConfiguration.FilterConfiguration property can you change the filters for the entire application.

You can easily view the filters that are present in the pipeline by iterating through the relevant collection. For example, if you want to view the input filters, you simply get the SoapInputFilterCollection object and iterate through its members:

// get the input filters SoapInputFilterCollection inputFilters =     WebServicesConfiguration.FilterConfiguration.InputFilters; // loop through the filters for (int x=0; x<inputFilters.Count; x++) {     Console.WriteLine(x + " - " + inputFilters[x].GetType()); }

To remove a filter, you simply call the Remove method of the filters collection and specify either the specific filter to remove or the type of filter to remove. Unless you’re keeping references to the filters that you’re creating, you should always use the Remove method that expects a filter type:

// get the input filters SoapInputFilterCollection inputFilters =     WebServicesConfiguration.FilterConfiguration.InputFilters; // remove the Timestamp filter inputFilters.Remove(typeof(TimestampInputFilter));

The Remove method iterates through the filters collection and removes the first instance of the type specified, shuffling the remaining filters up and filling the gap left by the removal. If there are multiple instances of a specific filter, you obviously need to call the Remove method multiple times.

If you now want to add a filter to the filters collection, you simply call the Add method of the filters collection and pass it a new instance of the filter you want to use. The use of the Add method will become clearer when we look at custom filters later in the chapter, but if you want to move the Timestamp filter to the end of the pipeline, you use the Add method in combination with the Remove method:

// get the input filters SoapInputFilterCollection inputFilters =     WebServicesConfiguration.FilterConfiguration.InputFilters; // move the Timestamp filter to the end of the pipeline inputFilters.Remove(typeof(TimestampInputFilter)); inputFilters.Add(new TimestampInputFilter());

The Add method always adds the filter to the end of the collection, but as you just saw, the pipelines are accessed in opposite directions depending on whether you’re dealing with an outgoing request or an incoming request. For an outgoing request, the filter you’ve added is processed at the end of the pipeline; for an incoming request, the filter is processed at the start of the pipeline.

Simply adding the filter to the pipeline might not be what you want—you might want to place the filter at a specific location in the pipeline. You could remove all of the filters and then add them in the order you require, but it’s much easier to use the Insert method of the filters collection to insert the filter at the given index:

// get the input filters SoapInputFilterCollection inputFilters =     WebServicesConfiguration.FilterConfiguration.InputFilters; // move the Timestamp filter to the start of the pipeline inputFilters.Remove(typeof(TimestampInputFilter)); inputFilters.Insert(0, new TimestampInputFilter());

This code moves the Timestamp filter to the first position in the pipeline (used first for outgoing messages, last for incoming messages), shuffling the remaining filters to accommodate the new filter.

Although we’ve looked exclusively at the input filters so far, the process for modifying (adding, removing, or inserting) output filters is exactly the same, except you start with a SoapOutputFilterCollection instead of a SoapInputFilterCollection.

Note

If you need to alter the filters collection, you must do so as soon as your application is initialized so all Web service calls will use the new pipeline. For clients, you do this in the initialization code; for server-based applications, you should do this in the Application_Start method in global.asax.

When you look at the upcoming Web services and client applications, you’ll see that the filters that aren’t being used have been removed—however, the Trace filters will always be running. For the Web services, this is done in the Application_Start method; for the clients, this is done in the constructor for the form after the call to InitializeComponent.

Adding Filters in the Configuration Files

You can also control the filters used by an application by specifying filters you want to add to the pipelines in the application configuration file. You can add filters to the pipeline, but you cannot remove filters from the pipeline, nor can you control the position at which new filters are added.

To add a filter to the pipelines, you simply add the details to the <filters> element of the configuration file. If you want to see the trace details for what went into the pipeline, as well as what comes out of the pipeline, you can add a second trace filter to both the input and the output pipelines. The default trace filters will catch one end of the pipeline, and the new trace filters you add will catch the other.

You add the new filters as follows:

<configuration>   <microsoft.web.services>     <filters>       <input>         <add type="Microsoft.Web.Services.Diagnostics.TraceInputFilter,Π         Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral,Π         PublicKeyToken=31bf3856ad364e35" />       </input>       <output>         <add type="Microsoft.Web.Services.Diagnostics.TraceOutputFilter,Π         Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral,Π         PublicKeyToken=31bf3856ad364e35" />       </output>     </filters>   </microsoft.web.services> </configuration>

Now that you have filters at either end of the pipeline, whenever you have tracing turned on, you’ll have two messages added to the trace file—one before the filters have processed the message and one after the filters have processed the message.

Recommended Filter Configuration

One problem with the ability to add filters in the configuration files is that third parties can add filters into the pipeline that you weren’t expecting and that might cause problems. If you deliver a client application to a customer, for example, the customer can add its own filters to the pipeline.

We recommend that you remove all of the filters from the input and output pipelines by using the Clear method of the relevant filter collection. You can add back in the filters you require. We recommend adding the Trace filter back into the pipeline so you can turn on tracing for the application if needed—this provides a valuable diagnostic tool for the applications that don’t perform as expected.

All of the filters in the pipeline have the ability to amend the SOAP envelope that you’re passing, and as you’ll see shortly, both the Timestamp and the Routing filter add details to the SOAP envelope if they’re in the pipeline—even if you’re not explicitly using the facilities they provide. If you’re not using them, it’s pointless to transmit the unnecessary data across the wire. Removing the unused filters from both the client and the server will minimize the overhead that WSE introduces.