On December 19, 2000, Microsoft published a new version of its SOAP Toolkit (2.0 Beta 1), supporting WSDL. This latest version SOAP Toolkit provides:

• client-side components for invoking Web Services described by a WSDL document
• server-side components which use the WSDL and WSML (Web Service Meta Language) documents residing on the server to perform mapping between the Web Services invoked and the COM object methods
• components for deserializing (breaking down), transmitting and reserializing (putting back together) SOAP messages

SOAP Toolkit 2.0 Beta 1 makes it possible to call services and publish them according to two Application Program Interface (API) levels: high or low. The choice will depend on the characteristics of the SOAP message that you wish to send or the level of monitoring of the service to be called.

The toolkit also provides a means to generate WSDL from the services described in a COM object. You give the service endpoint, the location of the related DLL, the name of the WSDL file that you wish to build… and the wizard does the rest. For unrecognized parameter types, it sends back '?????' and you will then need to specify the types yourself.

As the old version of SOAP Toolkit for Visual Basic 6.0 used proprietary format SDL files, Microsoft was not making any progress in boosting interoperability of Web Services. But by releasing this new version of the toolkit, Microsoft is changing its strategy and taking a step towards standardization or, at least, interoperability of implementations. Our tests revealed a fair level of interoperability, although some problems were encountered with the Apache implementation.

The purpose of this document is to explain precisely how Microsoft's SOAP Toolkit is used.

Platforms supported

Client and server objects run in a Windows environment.

• SOAP client objects run in Windows 98, ME, NT4.0 and 2000
• SOAP server objects run in Active Server Pages in Windows 2000 and NT4.0 Sp6

When the Toolkit is installed, the XML parser (MSXML3.0) is saved in the system. New DLLs are also registered if you have been using the old version of SOAPToolkit released in November.

The SOAP Toolkit features two approaches for using SOAP: a Usage approach (High API) and a Development approach (Low API).

Usage approach: High API

This approach makes programming easy for developers by keeping all the technical details hidden.

Client side: calling a Web Service with high API

The following example features a Web Service available on http://www.xmethods.net and performs a ping from the Xmethods server to a host using the WSDL of the related service. First of all, the client application instantiates a SoapClient object which is implemented in mssoap1.dll:

set soapclient = CreateObject("MSSOAP.SoapClient")

Once instantiation is complete, the SOAP object can call the mssoapinit() method. This method has three parameters: the URI of the WSDL file, the name of the service (same name as the SERVICE tag in the WSDL) and the port name (the same name as the PORT tag in the WSDL).

Call soapclient.mssoapinit("http://www.xmethods.net/sd/ PingService.wsdl", "PingService", "PingPort")

Once this call is completed, all the WSDL methods become available (the names are those of the OPERATION tag in the WSDL), and all that remains to be done is to choose the required method(s).

wscript.echo soapclient.pingHost("www.yahoo.fr"))

High-API SOAP communication: client side

Server side: Offering a Web Service with high API

To illustrate the server side of the high API, we have directly reproduced an example from Microsoft's SOAP Toolkit 2.0 Beta 1, included in the download file. It shows the standard server-side model for processing a SOAP message requiring WSDL for execution. MS SOAP Toolkit 2.0 is based on ASPs. It starts by invoking a SoapServer object which creates an instance of a COM object defined in the WSML document (this document can be generated by a Toolkit, which requests the COM object in which the services are located, the URL of the SOAP server and the name of the required document).

The SoapServer object decodes the parameters of the SOAP request, and uses them to call the right methods. It retrieves the result of the execution, places the result in a SOAP message and sends it back to the client.

The ASP scripts below correspond to the SOAP Endpoint ASP scripts on the server side.

<%@ LANGUAGE = VBScript %><% Response.ContentType = "text/xml" %> <% set soapserver = CreateObject("MSSOAP.SoapServer") wsdl = Server.MapPath("Sample.wsdl") wsml = Server.MapPath("Sample.wsml") call soapserver.init(wsdl, wsml)call soapserver.SoapInvoke(request, response) %>

High-API SOAP Communication: server side

By using a high API you can send and receive SOAP information without having to write code. The Toolkit uses a WSDL file as a method to reach the requested service. The advantage is to be able to map an existing COM object by making it SOAP-enabled.

Development Approach: Low API

This approach exposes the technical details of the SOAP message. The Toolkit offers several interfaces for low-level transactions. These low-level interfaces enable the client to generate SOAP messages, send them to the server and process the responses.

Client side: Calling a Web Service with a low API

The different objects used to execute SOAP messages are as follows:

• SoapConnector — sends and receives SOAP messages
• SoapSerializer — builds the SOAP message and sends it to the server
• SoapReader — reads the response from the server

Let us use the same service to be called as for the High API (XMethods Ping). First of all, the SoapConnector object is created which manages the sending and receiving of SOAP messages. The EndPoint property is then instantiated with the service address. To initialize and prepare the connection, you can call the Connect method. The SoapConnector's SoapAction property provides the value required for the SOAPAction field in the SOAP header.

Connector.Property("EndPointURL") = "http://services.xmethods.net:80/perl/soaplite.cgi" Connector.Connect Nothing Connector.Property("SoapAction") = "urn:xmethodsSoapPing#pingHost"

The BeginMessage method of the SoapConnector is then ready to send the SOAP message.

The SoapSerializer object is used to manually create the message. This creation process is very intuitive and involves creating the payload step by step. The first step is to create the envelope, followed by the body, then an element for which we define:

• the name of the service which will use this element
• URI, means of coding
• tag prefix.

Next, the name of the element and its value must be indicated. All the Serializer properties have end properties, which means that corresponding to Serializer.startEnvelope is Serializer.endEnvelope. This structure corresponds to the generation of an XML payload.

The EndMessage method of the Connector indicates the end of the SOAP message to be sent to the server.

Serializer.Init Connector.InputStream Serializer.startEnvelope Serializer.startBody Serializer.startElement "pingHost", "urn:xmethodsSoapPing", , "namesp01" Serializer.startElement "hostname" Serializer.writeString CStr("www.yahoo.com") Serializer.endElement Serializer.endElement Serializer.endBody Serializer.end Envelope Connector.EndMessage

The server executes the requested operation and sends back the SOAP message. The returned Response contains either the result of the operation, or a Fault element describing the error. The Response object can be read with the SoapReader object.

The Reader.Load Connector.OutputStream object parses the Document Object Model (DOM) tree and reads the OutputStream message returned. The result can then be displayed.

Reader.Load Connector.OutputStream MsgBox Reader.RPCResult.Text

SOAP Interoperability: SOAP Client (MSSOAP) — SOAP Server (SOAP::Lite hosted by XMethods)

Server side: Offering a Web Service with low API

The different elements used to process SOAP messages are as follows:

• SoapReader — reads the incoming SOAP message request and builds a DOM tree
• SoapSerializer — builds the SOAP message containing the result of the operation and sends it to the client

This example, taken from those provided in Microsoft's SOAP Toolkit 2.0 Beta1, sends 'Hello' or 'Bye Bye' depending on the name of the requested method. The endpoint here is therefore an ASP which manages client requests. Each time the server receives a SOAP request, it instantiates a COM object. Then the server invokes the Process method of this object. Its two parameters are the incoming and outgoing SOAP messages. The Endpoint ASP script is as follows:

<% Set SpeechSrv = Server.CreateObject("TestHello.SpeechSrv") SppechSrv.Process Request, Response %>

On the server side, the process in the COM object involves three steps: retrieving the information, performing the operation, and sending the response.

The following VB code for the COM object gives the key elements required to carry out the operation:

' Process function which performs the operation Public Sub Process(ByVal Request As ASPTypeLibrary.Request, _ ByVal Response As ASPTypeLibrary.Response) ' Load request in Reader object Reader.Load Request ' Retrieve required information ' Base name - with RPCStruc.baseName property MethodName = Reader.RPCStruct.baseName ' Value of element A - with property RPCStruc.selectSingleNode("Tag_Name").text A = CDbl(Reader.RPCStruct.selectSingleNode("A")Text) ' Operation If (MethodName = "Morning") Then Answer = "Hello!" Else Anwser = "Bye Bye!" End If ' Construction of response header Response.ContentType = "text/xml" ' Construction of response XML payload Serializer.Init Response Serializer.startEnvelope Serializer.startBody Serializer.startElement MethodName & "Response", "uri:Speech" Serializer.startElement "Answer", "uri:Speech" Serializer.writeString Answer Serializer.endElement Serializer.endElement Serializer.endBody Serializer.endEnvelope

Low-API SOAP communication: server side

The difference between the low API illustrated here and the high API is that in the former case, incoming and outgoing messages are directly processed by the COM object. For a high API, the SOAP Server automatically takes care of these operations.

The advantage of this programming method is that it makes it possible to monitor the message generator very precisely, and allows customized error management to be developed. The major disadvantage is that such COM objects are solely designed to be called via SOAP. So when using this method, it would be wise to externalize all the business logic to another COM object and to keep only the SOAP processes in the object presented as a Web Service, as the following diagram illustrates:

Recommended use with COM objects in low API

Conclusion

Microsoft's SOAP Toolkit 2.0 Beta 1 enables us to call or create SOAP services using two API levels.

The high API enables the client to make simple calls using the WSDL of the service called. Interoperability is not 100 percent, however, as these clients cannot as yet use services developed with the Apache SOAP implementation, which requires the type of the parameters sent.

Those wishing to offer services can do so via an ASP and a COM object. A WSML file makes the connection between the WSDL and the service itself, which is described in a COM object. Mapping is carried out in the ASP using methods contained in the new libraries.

The low API enables the client to monitor the message independently (or not) from the service described by the WSDL. Server side, the implementation makes it possible to offer services and monitor messages. This low API means that developers can process messages with the methods made available. The advantage is therefore that flows can be monitored and errors managed.

Microsoft is carving itself out a good position by offering an easily accessed, detailed product for calling Web Services using SOAP. The examples given by Microsoft on this new toolkit include insertion of SOAP in Office applications such as Excel, so Office users can now have the current Euro-Dollar exchange rate in their Excel functions, for example. However, few Web Services except those on Microsoft's www.gotdotnet.com site are currently deployed on the Web with this new technology. Nevertheless, the chances are that the advent of .Net will see a whole plethora of Web Services blossom on the Internet.