Implementing a Web Service with Microsoft SOAP Toolkit Version 2.0

 

Christian Weyer

eYesoft
http://www.eyesoft.de/dotnet/

You can download the source code for the SOAP translation dictionary Web Service here:
 Download

Related downloads:

o         SOAP Toolkit Version 2.0

o         SOAP Toolkit Version 2.0 Installer Merge Module

o         .NET Framework SDK Beta 1

Nearly everybody who is involved in using or researching Microsoft related technologies is very excited about this new 'thing' called .NET. Whereas this excitement may be because of all the new and interesting technologies and possibilities introduced with .NET or because of the big efforts that one or an entire company may make to get up with the new vision, .NET wants to mediate a new way of thinking about software applications in the Internet: software as a service that cannot only be used and accessed by human people interacting via Web browsers but also by machines and other software as well. The so called Web Services form whole new possibilities of how to architect your Intranet or Internet application architectures to build real e-commerce applications.

With this aim in mind a software developer may ask himself if this new type of software can already be realized with exisiting models and technologies. The short answer is: yes it can!

In this article I will make you familiar with some new but still evolving technologies and how they can be implemented in your project needs. Many current and future projects aim on the Windows DNA approach of designing and developing distributed applications. As Visual Basic is the most common and mostly used language to realize this component based model I will focus on using VB as the implementation language of choice for this article (of course it is for TopXML :o).

One of the basing standard on which Microsoft built its .NET Framework is the Simple Object Access Protocol (SOAP). In short, SOAP is a protocol for exchanging XML messages or data between communication endpoints in the Internet. Let's have a look at SOAP.

Simple Object Access Protocol (SOAP) in a Nutshell

Don Box, one of the 'inventors' of SOAP, once said in an interview: "SOAP was desgined to be a better and more powerful DCOM or IIOP". This simple sentence leads us to important clearifications. A communication protocol for exchanging data - especially in case of the Remote Procedure Call (RPC) pattern - needs to be able to reach potentially every host in the Internet. This implies that a) it uses a message format that nearly every Internet device can work with and b) it uses a technology or technology mixture that can pass the corporate Internet firewalls (with respect of security issues involved). SOAP obviously addresses both. SOAP is based on XML and HTTP for the RPC case. The SOAP specification defines how SOAP messages have to be constructed and interpreted by by participating parties. The specification itself consists of three important parts: the first important thing to mention is the SOAP Envelope. The Envelope marks the boundaries for a SOAP compliant XML message or document. When you think of SOAP as being a framework it is this Envelope pattern that describes the framework. You should be familiar with what is depicted in Figure 1.

The second important feature is the optional but widely used Remote Procedure Call (RPC) nature of SOAP. Together with the third point - the SOAP encoding of XML messages - it forms one of the biggest strenghts of SOAP today. It is mostly used in conjunction with HTTP and in a request response manner (as employed by HTTP itself). This RPC encoding is therefore responsible for enabling a platform independent communication. You can think of marshaling and unmarshaling your method parameters or signature in general to and from XML/SOAP into your programming language or component model.

SOAP's major aim from the beginning of the design phase was to be simple. The authors should have shouted out loud "Kiss me!": Keep it simple and stupid. Besides my personal dislike of the naming Simple Object Access Protocol, it is more appropriate to call the SOAP acronym Service Oriented Architecture Protocol. This gives more respect to the desired scenario of realizing Web Service based architectures.

 

 

Figure 1: Characteristics of a SOAP message

 

Rescue for Windows DNA applications: Microsoft SOAP Toolkit

SOAP is more and more used to emphasize the new mindset of Web Services. Web Services are the cornerstone in Microsoft's .NET world - but what to do when using 'plain old' Windows DNA with VB and COM?

There are several toolkits on their way, but Microsoft itself is offering one with the most complete and interesting features For a good resource of SOAP news and implementations regularly visit The SOAP Web Services Resource Center. Starting with the SOAP Toolkit Version 1 in May 2000, Microsoft tried to build a stable and powerful runtime environment for developers to use SOAP in their applications. Of course, as this is one of the important goals for a developer of distributed applications, the SOAP mechanisms and low level features should be hidden from the business logic developer. The Version 1 main actor was called ROPE (Remote Object Proxy Engine) and was realized as a COM component that serves several COM interfaces. But there were some problems and major flaws with and within the ROPE. The most serious one was that not all of the required sections of the official SOAP specification were implemented. For example such an essential feature like encoding arrays of values was not possible. Although you could write your own serialization/deserialization code with the ASP based server-side listener, this was not what a committed developer expected. Another very annoying circumstance was the missing UTF-8 encoding of the XML message over HTTP.

All in all, the Version 1 of the SOAP Toolkit was an unsupported MSDN code sample, with no future inside of Microsoft. One of the positive facts, though, was the source code availability, so tha tyou could enhance it for your personal needs. Therefore the December 2000 release was the last release and the SOAP Toolkit Version 2.0 (STK) took in that place.

With the advent of the STK, Microsoft delivers an official and supported product. It also plans to release at least 'some parts' if not all of the underlying source code - just pray. It can be used on Win 98 and higher and of course on Windows NT 4.0 and higher systems. Unfortunately the STK has deployment and functional dependency on Internet Explorer 5 and on MSXML 3.0 SP1 because the Windows 98 and Windows ME SoapConnectors use WinInet for communications and this comes with IE 5 and above - so don't forget to have these two installed when deploying your STK-based client applications.

SOAP Toolkit V 2.0 client working mechanisms

A very important goal for the development of the STK was to achieve as high compatibility with the SOAP spec as possible. And this work has been done quite good so far - and in fact it is known that the SOAP spec at some points is too fuzzy and therefore leaves too much space for SOAP implementors for their interpretations of the subject (see http://jake.soapware.org/ for an ongoing effort of guaranteeing compatibility between available SOAP implementations, including STK and .NET).

Just like Version 1 the STK now provides several COM objects to interact with. On the client you can use two kinds of abstraction to the SOAP layer: if you would like to all happen automagically behind the scenes and you do not have special requirements to the SOAP communication then you can use the high-level interface in most cases. The object to use is called SoapClient. It has the following methods and properties:

 

Method Name	Description
mssoapinit	Initializes the SoapClient object using the Web Services Description Language (WSDL) file as input.
HeaderHandler	Sets the header handler for the next call against this client instance.
Property Name	Description
ClientProperty	Sets and retrieves properties specific to the SoapClient object.
ConnectorProperty	Sets and retrieves properties specific to the transport protocol connector used by a SoapClient object.
detail	(read-only) Provides the value of the <detail> element of the <Fault> element in the SOAP message.
faultactor	(read-only) Provides the Universal Resource Identifier (URI) that generated the fault.
faultcode	(read-only) Provides the value of the <faultcode> element of the <Fault> element in the SOAP message.
faultstring	(read-only) Provides the value of the <faultstring> element of the <Fault> element in the SOAP message.

Figure 2: Methods and properties of SoapClient object

As said above, this will suffice in most cases. When you want to make an RPC like operation with STK then initialize the SoapClient object by passing the required metadata about the SOAP based Web Service. This metadata resides in a WSDL (Web Service Description Language) file. After having been initialized you can simply call any of the Web Service methods directly on your SoapClient instance. An example for Web Service that acts as a simple calculator:

Set oSOAPClient = CreateObject("MSSOAP.SoapClient")
oSOAPClient.mssoapinit("CalcData.wsdl", "", "", "")
MsgBox oSOAPClient.AddNumbers(17,4)

In the above sample you can simply call the add method on your object instance just as if it were a method of SoapClient - cool, and all made possible through the IDispatch interface. Unfortunately currently there is no plug-in for VB 6 that enables the use of IntelliSense feature at design time for the WSDL metadata … perhaps someone from Microsoft reads this. WSDL is a standard, structured way of describing SOAP messages and Web Services. The STK is dependent on WSDL to create and interpret SOAP Messages so a WSDL file is required for any SOAP Toolkit 2.0 client or server when using the high-level interface. A developer does not have to code the WSDL by hand for every component or interface. STK provides a tool called WSDL Generator: wsdlstb.exe for command line usage and wsdlgen.exe for a GUI version. It takes a COM component as input and analyzes its type library. From these collected data a new WSDL and WSML (see below) file is generated automatically.

There also is another style of SOAP communication coming with STK, the so called SMO (SOAP Messaging Object) framework - this is a document oriented approach opposed to the Remote Procedure Call paradigm. But this feature is so complex and powerful that it really is worth an own article.

You can see an overview of the client side working mechanisms in Figure 3.

 

Figure 3: SOAP Toolkit client side model (from Microsoft SOAP Toolkit documentation)

 

In words, the initialization and method invocation goes like this.

After having read in the WSDL for the SOAP endpoint, the client builds an internal representation of the WSDL in-memory. The methods are all dynamically published through IDispatch so that any COM Automation capable client can use the SAOP service like any other COM object. When now invoking such a SOAP method (like Add(17,4)) then the SoapClient object automatically serializes the data into a SOAP compatible XML message and sends the request to the SOAP endpoint. Currently, the transport protocol supported in 2.0 is HTTP, but it is intended to provide more protocols like SMTP or MSMQ. When returning from the SOAP service the SoapClient object deserializes the SOAP response and returns the appropriate COM data types to the calling client program. The WSML depicted in Figure 3 is optional and only needed when transferring complex types using the STK's Complex Type Mappers.

SOAP Toolkit V 2.0 server working mechanisms

As expected, things work similar on the server side. First of all, you have to choose between two types of endpoint implementation: ASP or ISAPI. The ASP soultion is more flexible. You can inject pre and post processing code that can perform your desired operations. Of course, the ISAPI listener is much more powerful in means of performance and throughput. Additionally it is easier to use than an ASP page so unless you need to do something the ISAPI doesn't do you should always use ISAPI.

And as on the client side, you also can choose between the low-level or the high-level API. You can see the internal ongoings on the server side in Figure 4.

 

Figure 4: SOAP Toolkit server side model (from Microsoft SOAP Toolkit documentation)

 

The details are nearly identical for both the ASP and the ISAPI listener. The server reads in the required WSDL and WSML. So what is WSML? It stands for Web Services Meta Language) and also is a special XML file. One of the easiest way to describe WSML is the analogy of a STK configuration file. It contains the information required to map the SOAP message described by a WSDL file to a COM interface. This includes the standard COM issues like ProgIDs. Other than WSDL, WSML will never be a standard because it only makes sense to the STK from Microsoft. If you like you can think of WSDL as the public header (interface definition) file and WSML as the internal implementation file.

After that the incoming SOAP Envelope (message) is parsed and the appropriate XML elements are converted or deserialzed into corresponding COM types. For a list of some of the most important type mappings please refer to Figure 5. Now the server object - named SoapServer for the high-level API used in ASP - can instaniate the COM objects and perform all needed operation on them. Based on each return value the server object serialzes these values into a valid SOAP message which will be passed back to the calling client.

 

XSD (SOAP) Type	Variant type	VB	IDL	Comments
base64Binary	VT_ARRAY | VT_UI1	Byte()	SAFEARRAY(unsigned char)
boolean	VT_BOOL	Boolean	VARIANT_BOOL
byte	VT_I2	Integer	short	Range validated on conversion.
date	VT_DATE	Date	DATE	Time set to oo:oo:oo
double	VT_R8	Double	double
short	VT_I2	Integer	short
string	VT_BSTR	String	BSTR
unsignedByte	VT_UI1	Byte	unsigned char

Figure 5: Important type mappings

To clarify this procedure have a look at a sample ASP endpoint:

<% Response.ContentType = "text/xml" 
Dim SoapServer, WSDLFilePath, WSMLFilePath 

WSDLFilePath = Server.MapPath("Calc.wsdl") 
WSMLFilePath = Server.MapPath("Calc.wsml") 

' error handling omitted ... 
Set SoapServer = Server.CreateObject("MSSOAP.SoapServer")
SoapServer.Init WSDLFilePath, WSMLFilePath

SoapServer.SoapInvoke Request, Response, "" 

Set SoapServer = Nothing %>

This sample only passes the incoming request directly over to the STK SoapServer object which does all the necessary work.

BTW, the distinction if one uses the ASP or ISAPI solution is done in the WSDL file. Consider the following WSDL fragments:

<service name='SimpleCalc'>
   <port name='SimpleCalcPortType' binding='tns:SimpleCalcBinding'>    
     <soap:address
       location='http://localhost/SimpleCalcTest/Calc1.asp' />
   </port>
</service>

and

<service name='SimpleCalc'>
   <port name='SimpleCalcPortType' binding='tns: SimpleCalcBinding'>
     <soap:address
         location='http://localhost/ SimpleCalcTest / Calc1.wsdl' />
   </port>
</service>

When specifying a .asp extension in the location attribute then STK assumes the usage of an ASP listener, otherwise when specifying a .wsdl extension then it uses the ISAPI based solution.

With these two techniques in mind you can start and build your own SOAP based distributed application. Or more interesting, change your existing ones.

Round up for demo:

Of course both SOAP itself and the SOAP Toolkit V 2.0 from Microsoft offer a so broad range of topics and discussions that I want to leave the space blank for other articles to come. One topic that I want to shed some light on in a next article is the capability of returning complex types with STK. Especially when looking on the zillions of applications out there working with ADO recordset as their 'complex data type', this will easen your SOAP developer's life a lot!

If you like, you can take a look at the example SOAP Web Service I developed in conjunction with this article. It receives a string for which a user wants a translation. This word can be either English or German. The Web Service then contacs on online dictionary, extracts the result and passes back the result to the calling client. My current version simply parses out the first of a probable long list of possible translations and passes this one back as a string. Please be sure to read the included README file and especially the enclosed disclaimer of usage.

In the next version it should be able to pass back an array of a complex type (i.e. a VB class) that encapsulates all relevant information plus some meta data. Stay tuned!