WSE 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.

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 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 the WSE Settings tool. For more details, about using WSE Settings tool, see WSE Settings 3.0 Tool.

The WebServicesClientProtocol proxy base class is implemented using two communication classes from the standard System.Net communication classes: WebRequest and WebResponse. At a high-level, the WebRequest instance sends SOAP requests and the WebResponse instance receives SOAP responses.

The WebRequest instance parses a request stream containing a SOAP message into an instance of the SoapEnvelope class, 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 set of filters and their behavior is controlled through the policy associated with the SOAP message. This policy is comprised of one or more ordered policy assertions, each of which defines a set of input and output filters for a SOAP message exchange between a client and a Web service. Each policy assertion's output filter is passed the SoapEnvelope in the order specified by the policy.

The following diagram illustrates how SOAP requests are passed through a set of filters.

The WebResponse operates on the SOAP message the opposite of the WebRequest instance. 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 WebRequest, the set of filters are defined by the policy associated with the SOAP request.

The following diagram illustrates how SOAP responses are passed through a set of filters.

The WebServicesClientProtocol encapsulates the use of the WebRequest and WebResponse classes so that you don't have to deal with them directly. However, you still need a way to get 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 server-side SOAP protocol factory, WseProtocolFactory. The goal of the new SOAP protocol factory 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 WseProtocolFactory 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.

For the WseProtocolFactory to run for a Web service, the WseProtocolFactory must be configured in the Web.config file for the Web service. Specifically, add the <soapServerProtocolFactory> Element 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.

See Also

Tasks

How to: Secure a Web Service Using a Policy File
How to: Secure a Client Using a Policy File

Concepts

Overview of WSE