SOAP Architecture

The strength of the SOAP architecture is its simplicity. The goal of the SOAP architecture is not to solve all the problems with distributed applications you have today; instead SOAP focuses on using the minimum of standards to send messages from one application to another. Old distributed applications require secure connections and/or transaction support—neither of which is supported by SOAP in its standard version.

You can really think of SOAP as a method for sending a message from one application to another application—nothing more. Items like RPCs are actually a combination of more SOAP messages with different contents. Security is often provided by the protocol used for SOAP, but can also be integrated into the SOAP message through WS-Security—as we will discuss later in the section "WSE and Security."

The SOAP Message

Let us take a look at the SOAP message in Figure 6-5. This message is constructed with a SOAP envelope, a SOAP header, and a SOAP body. A basic SOAP message is a well-formed XML document consisting of at least an envelope and a body that both belong to an envelope namespace, defined as http://schemas.xmlsoap.org/soap/envelope/. The header and the SOAP fault parts are optional. Since the tags Envelope and Body may exist in the XML document that should be transferred, the tags use namespaces. A name-space is a collection of names that can be used as element or attribute names in an XML document. The purpose of a namespace is to make the combination of the namespace and the tag name unique in the XML document. You need to be able to identify the namespace, and that is done by a Universal Resource Identifier (URI), which is either a Uniform Resource Locator (URL) or a Uniform Resource Number (URN). The important thing is not what the URI points to, but that the URI is globally unique across the Internet.

Figure 6-5: The architecture of the SOAP message

A namespace can be declared as either implicit or explicit. The explicit declaration is used in the SOAP message. With an explicit declaration, you define a shorthand, or prefix, to substitute for the full name of the namespace. You use this prefix to qualify elements belonging to that namespace. Explicit declarations are useful when a node contains elements from different namespaces.

We will refer to SOAP elements using soapenv as the namespace prefix later on in the examples in this chapter.

A simple SOAP message will look like the following:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <SubmitInvoice
      xmlns="http://mycompany.com/shop.net">
      <invoiceData>
          Data goes here!!
      </invoiceData>
    </SubmitInvoice>
  </soapenv:Body>
</soapenv:Envelope>

Envelope

The envelope is the container for the whole SOAP message. This is actually the root XML of the XML document and has the name Envelope. In the beginning Envelope tag, the namespace is specified. The xmlns is the definition for name-space, and the text following the colon is the namespace prefix that will be used in this XML document. It is possible to include many different namespaces in the same XML document by adding them one after another like this:

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:economy="http://mycomp.com/soap/economy/"

This will often occur, because the information sent in the SOAP message may use different namespaces to separate the same tag name.

Header

The header is optional and can contain information about the SOAP message, such as expiration date, encoding information, and so on. Here it is possible to include your own information, and later in the section "SOAP Extensions" you will see how the header can be used for security verification and RPC calls. Here we will show you how to add some header information to a SOAP message. In Listing 6-1, some general information is sent in the header: the date when the SOAP message was posted.

Listing 6-1: Header Information in the SOAP Message

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
<postedDate>
12th of May 2002
</postedDate>
  </soapenv:Header>
  <soapenv:Body>
    <SubmitInvoice xmlns="http://mycompany.com/shop">
      <invoiceData>
      Data goes here!
      </invoiceData>
    </SubmitInvoice>
  </soapenv:Body>
</soapenv:Envelope>

Fault Part

The last part of the SOAP message might be a fault part. This is a child element to the body parts of the SOAP message. The information is generated on the server when an error occurs in the processing of the request. A fault message is easy to create inside a Web service, as you will see in later examples. The SOAP message is put back into the response message, and the fault part tells the user of the Web services what kind of error has occurred. A typical fault message looks like this:

<soap:Fault>
       <faultcode>soap:Client</faultcode>
<faultstring>System.Web.Services.Protocols.SoapException:
A validation error occurred:
The 'http://www.mycompany.com/info.net/schemas/invoice:ItemTotal'
element has an invalid value according to its data type.
</faultstring>
       <detail>
         <Procedure xmlns="http://services.mycompany.com/Invoice/">
                  Validation
         </Procedure>
         <Line xmlns="http://services.mycompany.com/Invoice/">13</Line>
         <Position xmlns="http://services.mycompany.com/Invoice/">15</Position>
       </detail>
     </soap:Fault>

SOAP Message Formats

Today many different kinds of SOAP message formats exist. The formats differ by the way the body element and the data in the header elements are formatted or encoded.

To send a SOAP message, you need to serialize the data into a format that can be understood by the receiver of the SOAP message. If you serialize the data to an XML document and send it in a SOAP message by putting the XML document inside the Body tag, the SOAP message that you end up with is said to be a document-style SOAP message and has a literal payload. This is more often called a document/literal SOAP message. Normally the use of SOAP is separated into two different areas: document/literal use and RPC use.

In document/literal use, the document usually contains one or more children called parts. There are no rules for what the body part of the SOAP message should contain in a document/literal SOAP message—it can contain anything that can be serialized and that the receiver and you agree upon. In RPC use, the SOAP body contains a method name that should be invoked on the receiver's server and an element for each parameter that the remote procedure needs. Section 7 in the SOAP specification defines exactly what the body should contain when it is used for RPC. In addition to the previously mentioned two SOAP message styles, there are two formats for serializing data into XML. The format you choose determines how your data is serialized into the soapenv:Body and soapenv:Header elements. We will now show you the different ways you can serialize the SOAP message.

When the serialization method is literal, the data is serialized according to an XML Schema. No specific encoding rules dictate how the data should be serialized in a literal SOAP message. With the literal format, the communication is based on XML documents rather than objects and structures, and the documents may contain anything.

The second serialization method is the encoded format. The data in this case is serialized according to rules that dictate the internal structure of the message. The most common rules are the Section 5 rules of the SOAP specification, which define how objects and object graphs should be serialized. Using section 5 encoding results in the data between the client and the services being based on objects and structures.

The decision of what format to use in a communication between a client and a service is open. In theory, the choice of using document or RPC format is unconnected to your selection of literal or encoded format. This gives you four possible combinations to choose among: document/literal, document/encoded, RPC/literal, or RPC/encoded. In the real world, the choice is reduced down to two—document/literal or RPC/encoded. Why? Because normally you would break down the use of Web services and SOAP into two groups:

The first group is the one that deals with document exchanges between different applications. Our example application in Chapter 9 exposes Web services that send complete time reports (in the form of documents) back to the caller. Such solutions need to describe the data in XML, and the content often does not have complex types in it. The preferred choice for these solutions is the document/ literal combination.

The second group uses SOAP for invoking remote objects. These solutions normally use RPC/encoded SOAP messages instead of document/literal SOAP messages, since the information in the SOAP message is of a more technical nature and includes complex types.

In the beginning, SOAP mainly functioned as a replacement for DCOM. Because SOAP was easy to use and less error prone than DCOM, the market became saturated with implementations of SOAP that mainly focused on its DCOM-replacement aspects. SOAP became popular because of its use of the HTTP protocol for transporting information between a remote object and a server. There was suddenly no need for altering the firewall to allow RPC calls to go through, as there was with DCOM.

In .NET you have two ways you can use Web services: either as Remoting services or as .NET Web services. Remoting, the replacement for DCOM, mainly focuses on remote access to objects on a server. Remoting services are based on RPC/encoded SOAP. The other option, .NET Web services, incorporate document/ literal encoding intended to be used for message-based Web services, like transferring information back and forth between a client and the server.

Document/literal is the format of choice when working with message-based Web services, because you have full control of the format of the message. By using the document/literal format in a business-to-business communication in which orders and invoices are sent between different companies, you can ensure that the documents are valid to a predefined and agreed XML Schema.

So when do you use the RPC/encoded SOAP messages?

The only time we recommend you use RPC/encoded messages is when you expose objects on your server that the client should be able to run (invoking as RPC). This may, for instance, be a calculation object that calculates a customer's price for items at the current time. If the server-side objects are based on COM, you want to use SOAP messages that are RPC/encoded. If you have developed them in .NET, you would use .NET Remoting.

SOAP is very easy to use. All you need to do is write a request as an XML document and put that document into a SOAP body encoded in the document/literal format. SOAP is mostly used when the need for message communication between different programs arises. This feature of SOAP is very important, since it makes it possible for you to tie different applications together, and reuse and extend legacy information in your business environment in a simple way—no matter what environment the legacy system is running in. One of the strengths of SOAP and Web services is the use of standard communication protocols as a carrier for the data. In the next section, we will talk about the benefits of using HTTP for SOAP messages.

SOAP over HTTP

SOAP over HTTP gives you a benefit that many of those who have used DCOM or CORBA sometimes wish they had—free access through firewalls. Since HTTP is a standard protocol that mostly is allowed to pass through firewalls using port 80, the use of HTTP as a protocol for SOAP messages automatically gives you access through the firewalls and proxy servers.

When using SOAP over HTTP, you need to set the HTTP content type header in a SOAP message to text/XML to identify to the receiver of the HTTP request that it contains XML. Also, when sending a SOAP request, you need to set the SOAP action header, which always contains a quoted value and communicates additional information about the SOAP message at the HTTP level. This can be useful for firewalls that filter SOAP/HTTP traffic based on certain values of the HTTP SOAP action header. In this way, it is quite easy for the administrator of a firewall to redirect different SOAP requests or even deny access for specific requests.

One example of this is to use the SOAP action header for extra customer information that validates the request to access the Web. In this way, access to the Web services is filtered at an early stage. (This is not always the best solution; we mention it merely as an example of the use of a SOAP action header.) Normally you should not design your Web services to rely on information located in the Action header, as there are other places to put it—for instance, in the SOAP header. Another use of the SOAP header is to block the SOAP message from passage through a firewall and only allow "standard" HTTP traffic. This enables a company to make sure that no Web services are accidentally invoked from outside the firewall. Here is a short SOAP message sent via HTTP:

POST /msyhop/orders/orderWS/
orders.aspx HTTP/1.0SOAPAction: "urn:OrderAction"
Content-Type: text/XML
Accept-Language: en-us
Content-Length: 800
Accept: */*
User-Agent: Mozilla/4.0 (compatible; Win32; WinHttp.WinHttpRequest.5)
Host: localhost
Connection: Keep-Alive
<soapenv:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">..</soapenv:Envelope>

SOAP over HTTPS

HTTP is perfect to use as a transport protocol for SOAP, but SOAP has no built-in security. Hence the SOAP message is transferred via HTTP, open for anyone to explore—not the best solution for critical business information. Anyone who knows how to sniff for TCP/IP packages will easily collect your business critical information, or even worse, manipulate it and send it to its destination! One solution is to use HTTPS. HTTPS employs Secure Sockets Layer (SSL) over port 443 (normally).

The encryption of packages prevents most persons from decoding your information. The strength of the communication depends on how long the encryption key used is. The length is described in bits, and longer is better. The key is based on prime numbers and has, until now, been quite safe to use. This security solution will work fine in regards to point-to-point communication—that is, the sender and the receiver are aware of each other and are the only ones interacting with the SOAP messages. This security solution can also be very fast, because it is possible to buy hardware that handles the SSL encryption.

When more actors on the SOAP message path are involved, the use of WS-I specifications such as WS-Security, WS-Policy, and WS-Routing is a better choice than relying on HTTPS security when you reroute your SOAP messages. The Web services architecture in a more complex application cannot rely on Transport Layer Security because a SOAP intermediary node may need to process the document before forwarding it on to the endpoint. This means that SSL can only be deployed in peer-to-peer environments. The important thing to note is that the number of potential SOAP intermediaries increases as the deployment scale increases.

This decreases the likelihood of encrypting your data successfully at the transport layer, increases the amount of access to each SOAP envelope, and increases the possibility of a passive sniffing attack against your text-based SOAP messaging framework. Message layer encryption and digital signatures are a must for a secure deployment. By using WS-Security, you ensure that the message itself is encrypted—no matter what kind of transport protocol is in use.

Later in the section "Web Services Enhancements (WSE) SDK," we will show you examples of how to use the WS-Security specifications from VB .NET via the Web Services Enhancements (WSE) software development kit (SDK) from Microsoft. This is an implementation of the WS-Security, WS-Policy, and WS-Attachment specifications.

RPC and SOAP

Rewriting an existing application to move from DCOM to SOAP is often too arduous, since many parts in such an application would need to be changed. You would have to make changes to the server side of the application to receive and process incoming XML documents and send responses as outgoing XML documents back to the client. You would also have to rewrite the client side of the application to format and send requests as XML documents and receive and parse responses.

Not only that, but most difficult of all, you would have to adopt a programming model that is probably different from the one you are used to: Serialize all data to XML, send it as a request to the server, and when the answer arrives back from the server, deserialize the incoming XML document and process the return values. Finally, if the existing application architecture does not lend itself to messaging, by using stateful server objects for example, replacing DCOM with SOAP messaging requires a major rearchitecture and/or some custom SOAP extensions.

To ease the transition process from DCOM to SOAP in an application, you could add an extra layer to the client application. The purpose of this layer is to simulate the previously used DCOM object, but instead of calling the object via DCOM, this proxy makes a SOAP message of the request and sends it to the server. On the server side resides a similar proxy that receives the SOAP message and deserializes it. The server then calls the object on the server, serializes the result, and returns it to the calling client proxy.

The specification for using SOAP for RPC (Section 7 of the SOAP specification) defines a standard format for communicating this kind of information. In addition, the SOAP specification contains many definitions, including one that defines a standard way of serializing/deserializing native application types (arrays, strings, and the like), which is important to enable interoperation among clients and servers from different vendors. This standard serialization format is commonly called Section 5 encoding, after the SOAP specification section where it is defined. Although the SOAP specification indicates you can use SOAP for RPC without necessarily using the standard Section 5 encoding, we do not recommend this because Section 5 encoding ensures your application will be able to operate with other applications. Common sense is to stick to a standard if one exists. Most SOAP stacks and SOAP tools combine RPC with Section 5 encoding. Instead of writing your own proxy layers, you can use existing third-party proxies, like those found in Microsoft's SOAP SDK. These proxies enable remote communication via SOAP messages in old Windows DNA environments, where applications are built on COM objects.

We will not continue to talk about older technologies here; instead we will focus on all the new features in the Windows .NET architecture that make Web services and SOAP even simpler to use, yet more powerful than they were in Windows DNA.

Error Messages in SOAP

Sometimes things do not work out the way they should, and you need to report an error back to the caller. This is possible to do by using the fault part in the SOAP specification. In .NET this part is populated with error information from the thrown error object, which makes it easy to return an error message. All you need to do is throw an error inside the called Web services method. The fault message contains a fault code, fault string, fault actor, and detail element, as described in the following list:

• Fault code: The fault code element is intended for software to provide a number that identifies the error. It must be present in the SOAP fault element, and the fault code value must be a qualified name.

• Fault string: The fault string is provided to give you a chance to see what kind of error has occurred and is not intended for algorithmic processing. For processing, use a fault code. The fault string is similar to the description string found in the error object in VB 6 in that it contains a description of the reason why the error occurred.

• Fault actor: The fault actor element is intended to provide information about what caused a fault within the message path. It contains a URI that identifies the source. Applications that are not the final destination for the SOAP message must include the fault actor in the response. The final destination may use it to indicate that the fault actor caused the error itself.

• Fault detail: The fault detail element is intended to carry detail error information related to the body of the SOAP message. It must be present, or processing of the message body will not be successful. The detail part may not carry information about faults that have occurred in the SOAP header. To return information about errors in SOAP headers, a fault message should be carried within header elements in the detail part. In the section "SOAP Exceptions," we will give you a more extensive look into SOAP and SOAP errors and how you can use them to return fault information to the caller.

Step 1: Modeling the UDDI Entry

The first step is to model your UDDI entry. Several key pieces of data need to be collected before establishing a UDDI entry.

First you need to determine which WSDL files your Web service implementation uses. Similar to a traditional COM or CORBA application, your Web service has been developed based on an existing interface or a proprietary one. The WSDL file can be generated in .NET by adding the WSDL parameter to the query string on the Web service as in this example: http://www.mycompany.com/SampleWebService.asmx?wsdl.

You then need to specify the name of your company and give a brief description of it as well as the central contacts for its Web services. This gives companies that would like to use your Web service the ability to get in touch with your support team if they need to.

Next, you define the categories and identifications that are appropriate to your company. To do this you browse, for instance, Microsoft's UDDI server (http://uddi.microsoft.com/default.aspx). The currently supported taxonomies are North American Industry Classification System (NAICS), ISO 3166, Universal Standard Products and Services Codes (UNSPSC), Standard Industry Classification (SIC), and GeoWeb Geographic Classification. Here you choose which categories best represent your company to allow others to narrow their searches for your Web service.

At this point you determine the Web services your company should provide through UDDI. You add the Web services you want to publish and define the different access points they may have (a Web service may have different access points). It is important to realize that registering a Web service in UDDI does not mean that everyone has access to it. Security, authorization, and authentication can exist in tandem with a UDDI registry entry. Just because someone knows your Web service exists does not mean he or she can actually invoke it.

Finally, you categorize the Web services you would like to publish, just as you previously categorized your company, so that it will be possible for potential users to find a Web service by searching on a category.

Now you have a complete UDDI registry entry. The next important step is to register it in the UDDI server.

Step 2: Registering the UDDI Entry

All communications with the UDDI publishing server holding information about your Web services use authenticated connections, and therefore you need to register to get a username and a password. The registration contains simple data about you and your business or organization, including the name of the business and an optional description of it. You must also agree to the terms of use statement, so this step cannot be done programmatically. Microsoft requires a Passport for authentication, so you need to have one before you can proceed to register your UDDI entry in the UDDI server.

The main purpose of this registration is to let others know your Web service exists. There are two ways to do the registration: either using a Web-based registration form or performing the registration programmatically.

If you are making frequent updates to your UDDI, you should use the UDDI .NET SDK to do so programmatically. After downloading and installing the SDK, it is quite easy to register your information in the UDDI server. But if you do not need to update the information frequently, you can use a Web-based registration form.

Due to space constraints, we will not show the complete registration process here; instead, we suggest you take a look at Microsoft's copy of a real UDDI registration at http://test.uddi.microsoft.com/default.aspx.

After you complete the registration of your UDDI entry, in 24 hours Microsoft's UDDI server will replicate your registration to the other UDDI servers around the world, and your Web service will be searchable and ready for others to use.