Web Services Enhancements (WSE)

Web Services Enhancements (WSE, pronounced as"wizzy") is a set of .NET class libraries; WSE is an add-on to the .NET Framework and provides support for several WS-* specifications, such as WS-Security, WS-Routing, DIME, WS-Attachments, and so on. WSE is installed as a set of .NET assemblies. These are implemented as filters that integrate with ASP.NET web services. Clients that consume these web services can expand and interrogate the SOAP message headers using WSE.

WSE provides its functionality by writing headers to outbound SOAP messages and reading headers from inbound SOAP messages. In some cases, it might also need to transform the SOAP message body (such as for encrypt/decrypt as per the WS-Security specification if security is enabled). The functionality is encapsulated as a set of filters, one each for outbound and inbound messages. As shown in Figure B-2, all messages are intercepted by these filters.

WSE input/output filters

You can access the WSE filter chain via the Pipeline class and integrate it with the ASP.NET web service runtime. New proxy base classes called WebServicesClientProtocol expose the new inbound and outbound filters. This new base class extends the default base class (SoapHttpClientProtocol). This new proxy ensures that the filters have a chance to process the SOAP message when a client invokes a remote web service call.

The WebServicesClientProtocol proxy class is implemented using two new classes called SoapWebRequest and SoapWebResponse. The SoapWebRequest implementation is quite straightforward; it parses the incoming request stream for the SOAP message using the SoapEnvelope class and passes the request through the chain of output filters, where each filter gets a chance to process the headers and modify them as needed. The behavior of each filter in turn is controlled via the SoapContext class. Figure B-3 shows the interaction between the various objects.

SoapWebRequest processing an output filter

On the other hand, the behavior of SoapWebResponse is just the opposite of SoapWebRequest. SoapWebResponse parses a response stream for the SOAP message through each filter where the filter can examine and modify the data as needed. Figure B-4 shows the interaction between the various components.

SoapWebResponse processing an output filter

WSE filters are exposed to ASP.NET web services through a SOAP extension via Microsoft.Web.Services.WebServicesExtension on the server. This class copies the inbound or outbound messages to a temporary memory stream, allowing the filters to modify the headers as needed before serialization/deserialization. Figure B-5 shows the integration with ASP.NET.

WSE integrating with ASP.NET

To make ASP.NET web services compatible with WCF services, you can embrace Basic Profiling (BP) conformance, use SOAP 1.1, and keep interoperable schemas as simple as possible. Try avoiding RPC/encoded, because it is not BP compliant. Also try avoiding SOAP extensions because they are harder to migrate.

WSE 1.0

WSE 1.0 replaced the Microsoft Web Services Development Kit (WSDK) and provided support for WS-Security, WS-Routing, WS-Attachments, and DIME specifications for the .NET Framework. The support came only from Microsoft and not from OASIS because OASIS was still ratifying the specification and because other vendors had yet to add support in their respective implementations. With this release, developers now could support various security features such as digital signatures, encryption, message routing capabilities, and the ability to include message attachments that are not serialized in XML.

WSE 2.0

WSE 2.0 is a different assembly and namespace from WSE 1.0. The new assembly name is Microsoft.Web.Services2 instead of Microsoft.Web.Services. The name of the WSE 2.0 configuration element is <microsoft.web.services2>, and the WSE 2.0 root namespace is microsoft.web.services2. Although WSE 2.0 tries to maintain compatibility with the older version, it introduces some noncompatible and breaking changes because it is a major revision from version 1.0 and it keeps up with the rapidly moving web service standards. If there are two different versions of WSE implementations on either end of a web service call, a SOAP fault will always be returned as the two implement different versions of the specification. WSE 1.0 implements WS-Routing and WS-Security, while the new WSE 2.0 implements WS-Addressing and the new OASIS WS-Security standard. To make the transition as easy as possible from WSE 1.0 to 2.0, Microsoft supports side-by-side deployment of both versions. One caveat to this, however, is that any given web service cannot use both WSE 1.0 and 2.0 at the same time—it can be configured to use only one or the other. Consumers of the web service can use either version, though. A few other areas that have changed are as follows:

• Messaging enhancements

• WSDL support

• Security enhancements

• WS-Trust and WS-SecureConversation support

• Next-hop routing

Messaging Enhancements

WSE extends the basic web service functionality of ASP.NET (via the SoapExtension framework) and adds features such as security. The catch to this is that the solution is then tied to using only HTTP as the transport protocol when using ASP.NET web services. WSE, however, provides lower-level APIs (via SoapSender and SoapReceiver) that are transport neutral.

WSDL Support

WSE 2.0 adds complete support both for generating and for consuming WSDL. It can automatically generate WSDL definitions of endpoints when requested. It also has a new command-line tool called WseWsdl2.exe that can generate proxy classes from WSDL definitions and that currently supports HTTP and TCP.

Security Enhancements

WSE 2.0 adds support for the OASIS WS-Security standard, which affects only the message format and not the overall functionality. This adds a role-based authentication model for restricted access and is implemented via the IPrincipal interface along with the IsInRole method for authentication-specific user roles. WSE 2.0 also improves the security token and has a new Security Setting tool that helps create a policy file describing the security requirements of the application.

Support for WS-Trust and WS-SecureConversation

WSE 2.0 also adds support for WS-Trust and WS-SecureConversation, which define how to derive a session token that can be used over multiple operations and hence make the process more efficient and scalable.

Next-Hop Routing

WSE 2.0 supports next-hop routing model where routing decisions are made on a node-to-node basis without requiring an explicit routing path in the header. Because of this all, WS-Routing functionality has been replaced by a new routing model based on WS-Addressing headers.

WSE 3.0

Unlike WSE 1.0 and 2.0, whose main objective was to provide a practical and usable implementation of the emerging WS-* security specifications, the strongest emphasis in WSE 3.0 is the simplification of message-level security and the implementation of interoperability. Broadly, the WSE 3.0 had the following design goals:

• Providing a way to build secure web services easily

• Simplifying the building of SOA solutions

• Future proofing and adding interoperability

Policy and Turnkey Security Profiles

In WSE 2.0 there was no correlation between the code written to secure a message and the declarative policy in place. In WSE 3.0, however, both the declarative and imperative programming models have been provided to secure the message. This is achieved either by using a Policy attribute or by using the SetPolicy method on the client-generated proxy class. Listing B-3 shows an example of how to set the policy to QuickReturnsServerPolicy.

Example. Setting the Policy

[WebService(Namespace = "http://quickreturns.com/samples")]
[Policy("QuickReturnsServerPolicy")]
public class WSSecurityUsernameService : System.Web.Services.WebService
{
   [WebMethod]
   public List<StockQuote> StockQuoteRequest([XmlArray(),
       XmlArrayItem("Symbol"] string[] symbols)
   {
      // Business logic here...
   }
}

Table B-1 lists the turnkey security profiles that over time have become standard in many implementations. For most situations, you would pick one of these policies and devote your time to implementing your business logic.

Hosting ASMX Web Services Without IIS

In WSE 3.0, ASMX web services can be hosted outside IIS and can be in hosted in any type of process called via TCP such as console applications, Windows services, COM+ components, WinForms, and so on. More custom transports such as UDP, MSMQ, and SMTP have also been published.

Using MTOM

Message Transport Optimization Mechanism (MTOM) enables you to send large amounts of binary data efficiently in a SOAP message. MTOM is W3C standardized and replaces DIME and WS-Attachments as the mechanism for sending large amounts of data. One advantage of MTOM is that it composes messages in the context of a security policy, so both the data and the SOAP message are secure. You also get reduced wire size with MTOM because binary characters are sent as MIME attachments over the wire.

Future Proofing

One of the main features of WSE 3.0 is to provide a path to WCF to facilitate the ability to build service-oriented applications based on web services. WSE 3.0 offers wire-level compatibility with WCF and can run side by side with WCF.