One overriding recommendation I would make for writing code that performs well is to use the asynchronous pattern for all I/O operations, such as file, disk, and network access (including Web service calls).

This pattern isn't at all difficult to use: You just need to know how to create delegates for callbacks. For example, imagine that you are calling a Web service operation called SubmitPO. When you use wsdl.exe to create a proxy class, three methods will be created:

public POReceipt SubmitPO(PO po); 
public System.IAsyncResult BeginSubmitPO(
               PO po,
               System.AsyncCallback callback,
               object asyncState);
public POReceipt EndSubmitPO(
     System.IAsyncResult asyncResult);

The first thing to do is to write a function of your own that will be called when the operation is finished and has returned:

public static void MyCallback(IAsyncResult ar) 
{
     POClass class = (POClass) ar.AsyncState;
     POReceipt receipt = (POReceipt) class.EndSubmitPO(ar);
     //do something with the receipt
}

Next, you need to create an AsyncCallback that points to the callback function, and then call the BeginSubmitPO operation:

POClass client = new POClass(); 
AsyncCallback cb = new AsyncCallback(SomeClass.MyCallback);
IAsyncResult ar = client.BeginSubmitPO(po, cb, client);

At this point, when the Web service call returns, the callback will be called, and the return value can be accessed. By doing this, you can continue to work on the calling thread. This means that your user interface doesn't need to become unresponsive; and even in nonvisual applications, you can call multiple services nearly simultaneously. Instead of ten serial calls of 1 second each, for an elapsed time of 10 seconds, you can call the ten services simultaneously and get it over in 1.1 seconds. Of course, your results may vary based on hardware and other factors.

One of the fallacies that many developers fall into is trying too hard to optimize the size of a message. For example, a cursory flick of logic may make one think that if a Web service is running at 400 requests per second, then cutting the message size in half would make it run at 800 requests per second. On second thought, it's apparent that this is not necessarily true. In fact, the extra processing power needed to make the message smaller may actually slow down the service.

Keeping an entire message under the MTU (Maximum Transmission Unit) size of a TCP/IP packet may result in a slight performance gain. In general, however, the thing to optimize is network latency. For example, even if you take your code's processing time from 0.2 seconds to 0.1 seconds, if the network latency is still 4 seconds, then the improvement doesn't make a big difference!

Optimizing latency on the network, especially when the Internet is involved, is challenging—you have to examine the actual physical topology of the network involved. Figure 15.1 shows the optimal network topology between a Web service and its client. It is an overly simplistic network, but the fact remains that from a latency standpoint, it is optimal. The typical Internet-based topology looks more like Figure 15.2, encompassing a large number of machines, such as bridges, routers, and hubs. The more you can get away from the topology in Figure 15.2 and the closer you can get to the topology in Figure 15.1, the faster your Web service will respond to its clients.

Figure 15.1. A Development Network …

Figure 15.2. … and the Real Internet

In the end, I highly recommend not worrying excessively about performance. It's important, and you should think about it up front. But the Internet and the Web are not conducive to high performance. No matter how much you do, you may never achieve your performance objectives. Even if you do, the cost for each gain in speed will take a logarithmic amount of work. Are you willing to spend a week to get a 1-percent gain? Do what you can, but don't expect miracles.

The first thing to realize is that your intended audience should dictate many of the interoperability steps you take. If you are building a service for use by a single partner on a J2EE platform running Linux, then factor that data into your decision up front. If you're exposing a service that an unknown number of people will use on an unknown number of platforms, then your decision will be different.

To begin with, educate yourself about the actual interoperability results that exist between any two platforms. The best way to do that is to review the interoperability results matrix found at http://www.xmethods.net/ilab or http://www.whitemesa.net. Like all URLs, these may not exist by the time you read this (although they've been very stable for the past 2 years). In that case, check my Web site at www.keithba.com/book for the new URLs.

If you are interested in the interoperability results for .NET or other Microsoft SOAP stacks, then also try http://www.mssoapinterop.org. This site contains the actual results for the SOAP Toolkit, ASP.NET Web Services, and .NET Remoting.

Once you know what stack your partner is using, the next step is to review these interoperability results and find a platform with good results that you feel comfortable developing on. For example, if your partner or partners are using ASP.NET Web Services and you are experienced J2EE developers, then Apache Axis or The Mind Electric's GLUE would be a great choice, offering a large amount of interoperability. Alternatively, if your partner is using Systinet's WASP for C++ and you are a Perl shop, then SOAP::lite may be your best choice.

Once you've decided on a platform, you'll need to design your service to maintain high levels of interoperability. For example, if you are using ASP.NET Web Services and you expose a DataSet object in one of your SOAP operations, then you may find that your partners have a difficult time interoperating. On the other hand, if you are expecting to interoperate only with other .NET platforms, then DataSet offers some excellent features.

As well, several of the decisions you can make will offer various levels of tactical (short-term) versus strategic (long-term) interoperability. The next section deals with those.

As of this writing, SOAP interoperability has moved dramatically, and quite far. In particular, there have been a number of advances with respect to interoperability for RPC/encoded style service.

Specifically, the SOAPBuilders Yahoo! Group (http://groups.yahoo.com/group/soapbuilders/) has engaged in a number of rounds of inter-operability testing. Most of the early ones have focused on RPC/encoded SOAP; however, there also has been significant testing of doc/literal, and testing of WSDL. Going to any SOAPBuilders member and examining that member's results against others is usually sufficient research for choosing the right interoperability focus. If you are actually building a SOAP stack, however, it may be useful to think about the various issues that the SOAP-Builders have found.

To begin with, it's important to understand that many SOAP issues actually occur at the basic XML or HTTP level. You need to interoperate at those levels before you can interoperate at the SOAP level.

Typical XML interoperability issues include character set encoding, such as UTF-8 or ASCII, and namespaces and the handling of namespaces. With HTTP, the issues usually are found with HTTP version 1.1 as opposed to HTTP 1.0. There are still several HTTP stacks that either don't do HTTP 1.0, or that do HTTP 1.1 incorrectly. The most common thing to watch out for is lack of keep-alive support.

Most of the problems with Web services interoperability are likely to occur with actual SOAP errors. Section 5 of the SOAP specification, along with Section 7, defines a data encoding that can be used without XML schemas. Even with schemas, Section 5 encoding still is very popular among implementations, but it is also the most likely to be misunderstood and mis-implemented.

For example, Section 5 mentions that you can send the data type of an element with the xsi:type attribute. The message in Listing 15.1 is an example of a method return.

<S:Envelope
     xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<S:Body>
<ns1:echoStringResponse
   xmlns:ns1="http://soapinterop.org/"
   S:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <return xsi:type="xsd:string">Hello, World</return>
</ns1:echoStringResponse>
</S:Body>
</S:Envelope>

This typing information is required only when the data type is itself a polymorphic one. Of course, polymorphism can be hard to define without some kind of out-of-band agreement; however, assuming that both sides think the parameter is a string, this attribute is not required. A few popular implementations have required typing information, but fortunately most of these implementations have newer versions that no longer require this information except for polymorphic types. This is just an example of the kind of interoperability problems that for the most part no longer exist. However, it is still something to keep in mind.

Another, even more fundamental problem involves document and RPC style interfaces. Some toolkits can do only one or the other, and every toolkit has a different default. Apache SOAP is an RPC/encoded toolkit by default, whereas .NET Web Services is document/literal by default. One of the most common problems I've seen is when an Apache client sends an RPC/encoded request message to a .NET server, and the .NET server returns a response, but that response is the response message you would see from a request message that was full of null values. For example, the message in Listing 15.2 could be sent for a simple Add service.

<S:Envelope
     xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<S:Body>
<ns1:Add
   xmlns:ns1="http://soapinterop.org/"
   S:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <A xsi:type="xsd:int">4</A>
      <B xsi:type="xsd:int">4</B>
</ns1:echoStringResponse>
</S:Body>
</S:Envelope>

However, then the response message from the .NET server is null, instead of 8, as shown in Listing 15.3.

<S:Envelope
     xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<S:Body>
<ns1:AddResponse
   xmlns:ns1="http://soapinterop.org/" >
</ns1:AddResponse>
</S:Body>

The problem here is that there was formal communication of the style of SOAP operation involved. The WSDL for the .NET server states that it is document/literal. To avoid this problem, I would recommend always using a WSDL description to define both clients and servers. Modifying the .NET server to be an RPC/encoded endpoint for easy interoperation is simple: Just add the [SoapRpcMethod]attribute to the method attribute:

[WebMethod] 
[SoapRpcMethod]
public int Add( int A, int B )
{
     return A + B;
}

<definitions 
     xmlns:tns="http://tempuri.org/"
     targetNamespace="http://tempuri.org/"
     xmlns="http://schemas.xmlsoap.org/wsdl/">

<portType name="Service1Soap"> 

<binding name="Service1Soap" type="tns:Service1Soap"> 

To begin with, what does versioning mean? There are actually several types of possible versioning schemes:

Typically, interface versioning gets the most attention, but it would be a mistake to not consider the other two types. Each has its own implications. More important, SOAP and the Web service architecture allow us to version each of these in a simple manner. It's a beautiful thing when XML's open content model lets you work such magic.

The most powerful feature in Web services is not interoperability between heterogeneous environments. It is a valuable feature, and the primary reason why most people have migrated toward it. But the more fundamental reason to use Web services is loose coupling. This is a loaded term that means different things to different people. When I refer to loose coupling, I mean that the actual implementation code for the client or server doesn't directly influence the wire format.

Imagine how powerful this is, and how different from previous distributed technologies such as DCOM. Whereas before, the signature of an implementation would have a direct impact on the wire format, now you can completely change your implementation signatures, technologies, or platforms without changing the wire format. The advantage of this is obvious when you consider interoperability, but it also has the benefit of lowering development costs.

Imagine the following scenario: You build a Web service for accepting purchase orders from an important customer. You design it to be document/literal style, and you use the SOAP Toolkit 2.0. Your shop is full of Visual BASIC 6 (VB 6) developers, so this is a natural choice. Over time, however, you may find that you've migrated to a managed code (C# and .NET Framework) development shop. At some point, you will probably find that maintaining the VB 6 code base for your purchasing service isn't cost effective: It's too much time and wasted effort. Luckily, you can move the service to a .NET code base without breaking the wire format that your partners are expecting. This is a large advantage over distributed technologies of the past.

Even within a single platform such as .NET, you may want to change your implementation radically, for reasons ranging from developer fancy, to security, to performance. As a small example, imagine you have a Web method that looks like this:

[WebMethod] 
public string SubmitPO( PurchaseOrder po)
{
     return "Order " + po.Id + " received";
}

The PurchaseOrder class may look like this:

public class PurchaseOrder 
{
     public String Id;
}

The SOAP for the request message would look like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>
    <SubmitPO xmlns="http://tempuri.org/">
      <po>
        <Id>string</Id>
      </po>
    </SubmitPO>
  </soap:Body>
</soap:Envelope>

You can change the signature of the method:

[WebMethod] 
[SoapDocumentMethod(ParameterStyle=SoapParameterStyle.Bare)]
public string SubmitPO2( SubmitPurchaseOrder SubmitPO)
{
     return "Order " + SubmitPO.po.Id + " received";
}

And the request message stays the same. The response message is different, but the code to keep that the same is just as easy. What's important is that this isn't a .NET feature. This is a feature of Web services. The implementation doesn't dictate the wire format. The implementation of a service or a service client is loosely coupled to the SOAP message that flows over the wire.

Put simply, when you version a Web service interface or a data type, you should create a new namespace URI. In fact, all namespace URIs should contain a date, to allow for quick reading to determine which version of a type or interface is being used. For example, instead of the useless http://tempuri.org namespace in our previous example, we could give it a specific namespace with the [WebService] attribute:

[WebService(Namespace="http://foo.com/2002/04/POService")] 
public class PurchaseOrderService

The SOAP request also would change, to the following:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>
    <SubmitPO xmlns="http://foo.com/2002/04/POService">
      <po>
        <Id>string</Id>
      </po>
    </SubmitPO>
  </soap:Body>
</soap:Envelope>

Now, if we decide to create a new service that takes a purchase order, but also takes another SubmitterID, then we should version our interface to be a new URI. There are many ways to do this in .NET. We'll use the same attribute again:

[WebService(Namespace="http://foo.com/2003/08/POService")] 
public class PurchaseOrderService

And the SOAP message changes as well:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>
    <SubmitPO xmlns="http://foo.com/2003/08/POService">
      <po>
        <Id>string</Id>
      </po>
    </SubmitPO>
  </soap:Body>
</soap:Envelope>

You could also imagine versioning the PurchaseOrder type itself. In anticipation of that, you could start by giving it a specific URI:

[XmlRoot(Namespace="http://foo.com/2002/4/PurchaseOrder")] 
public class PurchaseOrder
{
     public String Id;
}

This would create a wire format as follows:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>
    <SubmitPO xmlns="http://foo.com/2002/04/PO">
      <po>
        <Id xmlns="http://foo.com/2002/4/PurchaseOrder">string</Id>
      </po>
    </SubmitPO>
  </soap:Body>
</soap:Envelope>

I would recommend that you always version your data types along with your interfaces. With .NET, this would eliminate the need to put an explicit namespace on each type, because instead you could put it just at the Web method or Web service level. (With .NET, you can use the [XmlRoot] attribute to set namespaces on classes. This would be the easiest way to version.)