As we have seen, WSE gives us the ability to programmatically create and consume SOAP headers in our Web services that conform to the supported Web services specifications. By leveraging WSE s SoapContext class, it s much easier for Web services to use SOAP headers to specify security behaviors, declare message routing, handle attachments, and even coordinate transactions.
To better illustrate the use of WSE-supported headers, I ll take some time to define a reasonably simple Web service that I can use throughout the remainder of this book when demonstrating how to use WSE to implement the various proposed interoperability message headers.
The sample Web service that I ll be using throughout the remainder of this book, named DocumentService, is a simple .NET Web service that stores and retrieves valid XML documents. A variation on this type of service might be used to store and distribute such documents as XML-formatted rsums, engineering documents, or work orders. The service will check submitted documents for valid XML, but it won t enforce a particular XML schema. Submitted XML documents are stored on the local file system and are tracked by uniquely assigned file names . If scalability were a major concern, the documents instead could be stored as XML in a suitable database. While it may seem trivial to use DIME just to transport an XML document (we could easily do this in the body of the SOAP message as long as the text encodings were compatible), this sample Web service could be easily modified to transport Microsoft Word documents or any other type of binary file.
The service allows an authenticated and authorized client to query the stored documents for a specified text string or to use an XPath expression to return the identifier for any matching documents. This identifier can then be presented to the Web service with a request to get a copy of the document.
This sample supports most of the interesting features of WSE, including encrypting and signing SOAP messages and supplying tokens, returning requested XML documents with the SOAP response in a DIME message, and content-based routing for load balancing or for storing similar content on the same server.
The DocumentService sample implements the following Web methods:
This method is used to submit a new XML document to the Web service. Only one document is submitted in each SubmitDocumentRequest message to the service.
public void SubmitDocument(XmlDocument document)
// Validate the document
// Store the document
This Web service method extracts the XML document from within the body of the SubmitDocumentRequest message; validates the document; assigns it a unique identifier, DocumentID; and saves it in a directory or share as DocumentID.xml.
This method is used to retrieve one or more stored XML documents based on the submitted identifiers. GetDocument takes a string array documentID and returns one or more XML documents along with the GetDocumentResponse SOAP response in a single DIME message.
public void GetDocument(string documentID)
// Get the requested documents and return via DIME
Since we re using the WSE implementation of DIME, I don t need to specify a return type for this method. In this case, the requested documents will be returned with the SOAP response method (which contains no response data) in a DIME message.
This method queries the XML documents in the storage directory. The method takes a string (either a query string or an XPath statement) and a Boolean that specifies whether the string is a query text or an XPath statement. This method returns an array of integer values that represent the identifiers of any matching documents.
public int Query(string query, bool isXpath)
// If isXpath is true then validate and search documents
// using the supplied XPath statement. Otherwise, just search
// as text.
// Return the documentID array of matching documents
The documentID array that is returned can be passed to the GetDocument method to retrieve the desired documents.
In the following chapters, I ll demonstrate WSE support for the various interoperability headers where appropriate. However, at this point, I ll briefly cover when it s appropriate to use these headers. In general, the proposed interoperability headers are used to enforce special behaviors for SOAP messages. These behaviors are related to the message itself, transport, reliability, security, and the like, and they aren t related to the actual data being transported in the body of the message. Following are some reasons for using these types of headers.
As we ll see in Chapter 5, WSE lets you encrypt part or all of a SOAP message according to the WS-Security specification so that your data isn t exposed when messages are being transported through an inherently insecure environment such as the Internet. One of the main reasons to implement message-level security rather than transport-level security is because secured transports, such as SSL, are limited to messaging between endpoints and cannot be used easily with message forwarding and other complex messaging topologies.
Also, WSE leverages the functionality specified in WS-Security to let you digitally sign part or all of a message to be able to tell whether anyone has tampered with the signed contents. Signing is the process of executing a special algorithm over a set of data that results in a derived digital signature that is much smaller than the original data but the value of which changes when even small changes occur in the signed data. We ll discuss signatures more in Chapter 5 as well.
In a secure environment, a Web service must require that a Web service request be made by a recognized client that s allowed to have access. Conversely, a client needs to determine that it s accessing the correct Web service and not a malicious service that s intercepting its requests . As we ll discuss in Chapter 5, the parties engaged in secure communication prove their identities by presenting security credentials known as tokens . In accordance with WS-Security, WSE allows you to include a variety of security tokens in the SOAP message header. We ll also describe these tokens in Chapter 5.
In addition to enabling the use of security tokens to secure SOAP messages, WSE supports the ability for participants in a Web services interaction to negotiate trust and exchange tokens that can be used to generate shared session keys for the duration of the interaction. In Chapter 8, we cover WSE support for the WS-SecureConversation and WS-Trust specifications that enable parties to exchange multiple SOAP messages securely and efficiently .
WS-Policy and its related specifications detail a mechanism for Web services to declare messaging requirements to which requesting applications must conform. WSE implements policy support that checks incoming messages for compliance to declared policies for inbound messages and automatically brings outbound messages into compliance to declared policies for outbound messages. We will discuss policy support in greater detail in Chapter 6.
When you need to send one or more binary attachments with a SOAP message, DIME provides a more efficient message-based transport mechanism. As you learned in Chapter 1, DIME is also a good solution with regard to combining multiple SOAP messages or other XML documents or fragments as part of a SOAP message, particularly when the encodings or XML schemas differ . As we ll see in Chapter 3, WSE lets you easily add attachments to SOAP messages.