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.