Many people tried to write programs that parse HTML documents to extract the essential information from the interleaved formatting and factual data with mixed success. Part of the reason that XML was created was to greatly simplify the task before programmers to parse or programmatically generate XML documents. In this regard, XML is very successful as it is is fairly simple to parse or create programmatically.

What the XML efforts did not focus on was how to call or pass parameters to an XML page. The reality is that very few applications get by with "static" HTML or XML documents. Applications require query string parameters or specific form fields be filled in with appropriate values in order to generate the HTML or XML document. The World Wide Web Consortium (W3C) developed the Simple Object Access Protocol (SOAP) that solves this problem. That is, it extends XML such that computer programs can easily pass parameters to server applications, then receive and understand how to parse the XML document returned. Thus, the SOAP specification describes how a distributed application can be built where the "client" and "server" software elements are inter-operating over the Internet using SOAP/XML as the data and object exchange protocol.

More specifically, the SOAP specification is divided into four parts:

1. The SOAP envelope construct defines an overall framework for expressing what is in a message, who should deal with it, and whether it is optional or mandatory.
2. The SOAP binding framework defines an abstract framework for exchanging SOAP envelopes between peers using an underlying protocol for transport. The SOAP HTTP binding [1](SOAP in HTTP) defines a concrete instance of a binding to the HTTP protocol[2].
3. The SOAP encoding rules defines a serialization mechanism that can be used to exchange instances of application-defined datatypes.
4. The SOAP RPC representation defines a convention that can be used to represent remote procedure calls and responses.

SOAP can and has been compared to Microsoft's Distributed Component Object Model (DCOM) and CORBA. For my purposes in this document, that is a very fair comparison. I think of SOAP as providing the framework or "plumbing" to enable to cooperating software programs to inter-operate over the public Internet. Internet and development software vendors are rapidly working on products that support the SOAP specification and simplify the lives of the programmers on many platforms. A variety of vendors and products have announced support for SOAP including Microsoft, IBM, HP, and Apache.

The .NET Framework and Visual Studio .NET

On the Microsoft platform, the .NET Framework product that is currently in Beta testing supports the SOAP standard. The Visual Studio .NET programming environment offers a template so that developers can quickly define, design, implement, and deploy a Web Service that supports the SOAP standard. The .NET Framework and Visual Studio .NET greatly simplify what you need to know and do in order to build or use a Web Service. In fact, you don't even need to know that it is based on the SOAP and XML standards. You simply define do the fun stuff — design the methods and their parameters, design the output data structures, and implement the methods. The actual generation of XML and implementing the SOAP protocol is handled for you by the .NET Framework and Visual Studio .NET.

By the way, the .NET Framework and the Visual Studio .NET generate completely open and compliant SOAP and XML. My very first Web Service was accessed and used by graduate students at MIT taking an Internet programming survey course. The students programmed against the TerraService using UNIX systems, GNU C++, and a SOAP/XML library.

How to Design a Web Service

Designing a Web Service is similar to designing any client/server application where the two communicating parties are on separate nodes. All good client/server implementations pay careful attention to the roundtrip costs over the network between the client and the server. Optimal methods find the "sweetspot" between "too simple methods" that require the caller to access the server to frequently (too many roundtrips) and "too complicated methods" that take to long to execute on the server or return too much data to be swallowed at once. This is similar to designing client/server systems using DCOM or CORBA.

Designers of Web Service client/server systems need to be even more sensitive to the roundtrip overhead for a number of reasons. First, the transmission between client/server will probably be over a wide-area network. Second the transmission may be passed through ancillary systems such as firewalls. And third, the data will have to converted to XML and back to native formats. The benefit to this overhead is worth it. We can now design and build wide-area distributed applications that operate on a multitude of platforms. The downside is more care must be employed at design time.

First lets get some agreement on terminology and make a few assumptions. A Web Service is the "Server" side of a "Client/Server" application. Assume the "Network" between Client and Server is the public Internet. You aren't in control of the performance of the Internet or the distance between Client and Server. Thus, you should assume the worst and plan for high latency and slow data rate between Client and Server. Don't implement frivolous methods on the Server that don't need to be there. Try to find a nice balance between frequency of calls to the server, method execution time, and amount of data transfered back to the client. All three have a huge impact on the performance of the application. I personally have a "1-to-10KB in 1 second" rule of thumb.

The 1-to-10KB in 1 second rule of thumb:

Note to readers. If you have read some book or article by an expert that gives different advice than me, then by all means ignore my advice and follow their guidelines. If you haven't gotten any advice, then follow this rule of thumb until someone smarter than me crosses your path with better advice.

A Web Service method should take less than 1 second to execute and ideally return between 1,024 and 10,240 bytes of data. Of course there are always valid cases where a method might need more than a second to execute, or even a fraction like a nano-second. But remember, calling a web service method is expensive. You will be putting the client machine through a process transition to call the web service, the web server will go through a process or thread transition to dispatch the call, and process the request. Thus you want to make sure the value of the result was worth all the overhead of the call.

The same is true for the size of the result returned to the client. Again, there are plenty of valid instances where the size of the result will be less than 1K or greater than 10K. But I believe that optimal Web Service methods return results in this range. There are three major activities in sending results back to the client. The server must convert from the Web Service platform's native data type to XML. This naturally increases the size of the data to be returned by 2x or more. The swollen data must be transmitted to the client, typically in 4KB packets. Then the client has to parse the XML and convert it to the client platform's native data type. Thus, you want to keep the amount of data transmitted and converted to something that can be handled reasonably quickly.

What is a Web Service within a Web Server?

On Microsoft servers, the IIS (Internet Information Server) software component handles all HTTP protocol requests. SOAP/XML Web Services ride on top of the HTTP protocol. IIS is effectively a big switch that understands how to dispatch a request, which is typically a URL, to the software that understands how to process it, and how to route data back to the client. There are basically three popular forks that IIS dispatches to — (1) the file system when an HTML, JPEG, GIF or other simple file is called, (2) a DLL that implements the ISAPI protocol for communication with the IIS server, and (3) to an Active Server Page (ASP) script. With the .NET Framework, there will soon be a fourth popular fork — ASP.NET.

Web Services are routed to ASP.NET by the IIS software. The file extension ".ASMX" is used to identify the request as a Web Service in the .NET environment. Query string parameters following the filename identify the Web Service method and parameter values.

An ASMX file is a simple text file that tells the ASP.NET run-time where to locate the .NET Class that implements the Web Service. Typically the .NET Class has the same name as the .ASMX file, but as the .DLL file extension. It is also typically located in the Bin sub-directory beneath the .ASMX file. When IIS dispatches to ASP.NET, ASP.NET reads the ASMX file to find the DLL or EXE to load, loads it into memory if it hasn't done so already, then calls the method in the DLL specified in the URL.

To successfully execute the method, the method must exist with the same name (case doesn't matter), and have parameters with the same name and type as those found on the URL request. ASP.NET returns a SOAP exception message if the caller doesn't get this right. The Visual Studio .NET environment provides a project template that simplifies the construction of a .NET Class that is a Web Service.

What is a Web Service to the Programmer?

From the programming perspective, a Web Service is Class that inherits from the System.Web.Services class. You create Public methods that are decorated with annotations that identify the public methods that should be published and advertised as Web Services by the ASP.NET system. There are restrictions on the data-types that are acceptable as parameters and return values from Web Service methods.

Off the top of my head I can't remember the exact list. But the simple thing to remember is that a Web Service is the server side of a client/server protocol. Realistically, only data can be marshalled over the wire in a vendor-neutral way. Thus, string, integers, floating point, dates, arrays, etc. are examples of valid data-types that can be passed as parameters or returned by Web Service methods. A Class reference or object is an example of something that cannot be passed there is currently no open way to transmit a class over the wire to a different platform.

In my Web Services, I define Web Service methods that take simple data-types as parameters, e.g. integers, strings, real numbers, and dates. My Web Service methods return the same list of simple data-types, an array of simple data-types, a struct of simple data-types or arrays of simple data-types, or a complicated struct of arrays, structs, or arrays of structs. There is also a new concept of a "DataSet" that can be returned from a Web Service (maybe it can be passed as a parameter too, I dunno.)

A DataSet is conceptually to a collection of result-sets returned by a complicated set of database query statements. Said another way, a DataSet is a collection of relational tables where each table might contain multiple columns and multiple rows. The system understands how to convert multiple relational tables into an XML document and un-pack on the other end. While a very cool concept, I avoid using DataSets in my Web Servies figuring that not every platform's programming environment is going to understand DataSet's yet. Since struct's have been around since the early days of C programming, I stick with them.

Creating a Web Service with Visual Studio .NET

So when you

Creating a Web Service is a very easy thing to do. Run the development environment and create a New Project. One of the choices in the list of the Web Applications will be a Web Service project, select it. The Web Service project will create a class definition for you that inherits from the System.Web.Services class. This gets you all the plumbing you need to marshall data to/from XML and send/receive SOAP messages. Thus if you bought a bunch of XML or SOAP books, you can throw them away now:)

Remainder of this page is under construction...