Web Services Enhancements Architecture
At its heart, WSE is an engine for applying advanced Web service protocols to SOAP messages. This entails writing headers to outbound SOAP messages and reading headers from inbound SOAP messages. It may also require transforming the SOAP message body — for instance, encrypting an outbound message's body and decrypting an inbound message's body, as defined by the WS-Security specification. This functionality is encapsulated by two sets of filters, one for outbound messages and one for inbound messages. All messages leaving a process — request messages from a client or response messages from server — are processed using the outbound message filters. All messages arriving in a process — request messages to a server or response messages to a client — are processed using the inbound message filters. The following diagram shows this simple architecture.
.gif)
WSE filter chains are integrated with the SOAP Messaging built-into WSE, as well as the ASP.NET Web services infrastructure.
Integration with ASP.NET Web Service Proxies (Sender-side)
WSE input and output filters are exposed to ASP.NET Web services clients through a new proxy base class called WebServicesClientProtocol. WebServicesClientProtocol extends the default base class for Web service proxies, System.Web.Services.SoapHttpClientProtocol. The new proxy base class ensures that WSE filters have a chance to process the SOAP messages that are exchanged whenever a client sends a SOAP message. In order to use WSE, you need to change the base class of each of your proxies to WebServicesClientProtocol. The easiest way to do this is to use WSE Settings tool. For more details, about using WSE Settings tool, see WSE Settings 2.0 Tool (WseSettingsVS2.dll and WseConfigEditor2.exe).
The WebServicesClientProtocol proxy base class is implemented using two communication classes called SoapWebRequest and SoapWebResponse. These classes derive from the standard System.Net communication classes, i.e., WebRequest and WebResponse, respectively.
SoapWebRequest parses a request stream containing a SOAP message into an instance of the SoapEnvelopeclass, an extension of System.Xml.XmlDocument, the standard .NET DOM API. Then it passes the request through the chain of output filters. Each filter has the chance to modify the request data any way it likes. Often, a filter simply adds protocol headers, but in some cases they modify the body of a message too, such as when the SOAP body is encrypted.
The behavior of the filters is controlled through the SoapContext class. Each SoapContext object records particular protocol options — the presence of a username token or digital certificate, creation and expiration timestamps, and so on. The SoapWebRequest class has a SoapContext property that is an instance of the SoapContext class. When a SoapWebRequest processes a request stream, it is the data in the SoapContext object that tells the output filters what to do.
The following diagram illustrates the behavior of SoapWebRequest and the role of SoapContext.
.gif)
SoapWebResponse operates on the SOAP message the opposite of SoapWebRequest. It parses a response stream containing a SOAP message into an instance of the SoapEnvelope class and passes it through the chain of input filters. Each filter has the chance to examine and modify the response data any way it likes. Input filters check the validity of protocol headers and modify the contents of the message's body as needed to undo the work of an output filter (decryption, for example). Like SoapWebRequest, SoapWebResponse exposes a SoapContext property. However, where the SoapWebRequest class uses its SoapContext for input, SoapWebResponse uses it for output. The SoapContext object attached to a SoapWebResponse is updated to reflect the protocol headers present in the response message when the response stream is read.
The following diagram illustrates the behavior of SoapWebResponse and the role of SoapContext.
.gif)
The WebServicesClientProtocol encapsulates the use of the SoapWebRequest and SoapWebResponse classes so that you don't have to deal with them directly. However, you still need a way to manipulate the protocol properties for both outbound and inbound messages. To that end, the WebServicesClientProtocol class exposes two properties, RequestSoapContext and ResponseSoapContext, both of type SoapContext. These objects reflect the protocol properties of the next message to be sent and the last message that was received, respectively.
Integration with ASP.NET Web Services (Receiver-side)
WSE input and output filters are exposed to ASP.NET Web services through a new server-side SOAP extension, WebServicesExtension. The goal of the new extension is to ensure that WSE filters have a chance to process the SOAP messages that are exchanged whenever a Web service's methods are invoked.
The WebServicesExtension class copies inbound messages into memory streams. It processes them using WSE input filters before the message is deserialized into input parameters for the target method. The extension also sets up a memory stream for the target method to serialize its output parameters into. After that serialization step occurs, the output message is passed through WSE output filter and then sent on its way.
The WebServicesExtension class has to expose the protocol properties for input and output messages to the server code handling a request. To that end, it adds references to two SoapContext objects; one containing information about the request message and the other about the response message to the current System.Web.HttpContext.Items collection, that is, HttpContext.Current.Items, using the keys "RequestSoapContext" and "ResponseSoapContext", respectively. For convenience, these objects are exposed directly as the static read-only properties of WSE RequestSoapContext and ResponseSoapContext classes, respectively.
For the WebServicesExtension to run for a Web service, the WebServicesExtension must be configured in the Web.config file for the Web service. Specifically, add the <add> Element for <soapExtensionTypes> (WSE for Microsoft .NET) to the Web.config file in the virtual directory where the Web service is deployed.
Sending and receiving SOAP Messages using TCP
WSE enables you to send and receive SOAP messages using the TCP protocol. This can be accomplished with or without an HTTP server, making it possible to write extremely flexible and lightweight Web services. WSE supports both a one-way messaging model and a request/response pair model. One-way messaging is accomplished using the SoapSender and SoapReceiver classes, whereas both one-way messaging and request/response messaging can be accomplished using the SoapClient and SoapService classes.