This section shows you how to write a SOAP client using the Microsoft SOAP Toolkit. The MS SOAP Toolkit is a set of DLLs which can be exploited from an any language within the COM (Component Object Model) family (as long, of course, as the executable is running on a Win32 system). The language we will be looking at in this tutorial is Visual Basic.

Introduction
We will be writing a very simple VB SOAP client which will exploit the Quotation Service as described and developed in the Section 4 of Server-Side SOAP.

The SOAP-related VB code in the client we will develop here can easily be incorporated into a VB Macro to SOAP-enable an Excel Spreadsheet. We will take a look at how to do that as well. While it is true that you can exploit the MS SOAP Toolkit DLLs from many languages other than VB, it is not our intention to cover them all.

As is the case when writing clients to any SOAP service, ensure in advance that you are familiar with the service and its method signatures.

We will build a single VB client which will exploit all three service methods.

Note that there are actually two APIs in the Microsoft SOAP Toolkit. They are the so-called High Level API (which involves the use of wsdl and wsml files for service description) and the Low Level API (which does not require the preparation of such files and is as a result more verbose in terms of code but at the same time more powerful). The API used in this tutorial is the Low Level API.

Check your Visual Basic Version
You will need Visual Basic 6.0 Service Pack 4 or later (this is the version delivered with Visual Studio 6.0 Service Pack 4). To check your version open up Visual Basic and choose Help / About Microsoft Visual Basic.

If you have Visual Basic 6.0 but are at an earlier Service Pack level you can download SP4 from Microsoft Product Support Services.

If you have a version prior to 6.0, or do not have Visual Basic at all, unfortunately, unlike the rest of the packages used on this site, you cannot download it for free. You can however still go through the source code here and run the VB demo found in the Demo Section.

Installing the MS SOAP Toolkit
Before you install the actual toolkit, you will need to ensure that you have the following on your system:

• Internet Explorer 5.5 or later (this will ensure you have the correct version of the HTTP connector libraries) - if you have a prior version then 5.5 can be downloaded free of charge from Microsoft's IE download page.
• Microsoft Installer (MSI) functionality (which allows you to run the SOAP toolkit installer) - this comes standard with Windows 2000 and Windows Me so users of these systems will not need to do anything. If you are using Windows NT then download MSI 1.1+ for NT. If you are using Win95 or Win98 then download MSI 1.1+ for Win9x.

Now for the toolkit itself. We will be using Microsoft SOAP Toolkit 2.0 SP2. To install this on your machine go to the MS SOAP Toolkit download area and choose the download entitled "Soap Toolkit 2.0 SP2", read and accept the license agreement (if you are happy with the terms) and save the file to your machine. You should now have a file called soaptoolkit20.exe. This is a self-extracting executable that exploits MSI functionality. Run it and follow the onscreen instructions to install the toolkit. When asked, opt for the COMPLETE install.

Understanding the API
Following is the bare-essentials VB code required to exploit the API. It is paraphrased from the VB source downloadable further down this page. Note that we have chopped out just the SOAP-related code, so what you see when you open up the downloaded source will be basically the same but slightly rearranged and more verbose to handle the GUI aspects of the client (which we will not bother to explain as they are trivial). Follow these steps in order to invoke a service via the API:

• Define some constants which will be used to build the SOAP Envelope (if you want to know more about these URLs see the section on SOAP Messages) as well as your service identification data (SOAP Server URL, Service URI and service method name).

  Private Const ENC = "http://schemas.xmlsoap.org/soap/encoding/"
  Private Const XSI = "http://www.w3.org/1999/XMLSchema-instance"
  Private Const XSD = "http://www.w3.org/1999/XMLSchema"
  URL = "http://localhost:8080/soap/servlet/rpcrouter"
  URI = "urn:QuotationService"
  Method = "getQuotationsByAuthor"

• Instantiate your SOAP Connector, Serializer and Reader. The Connector will handle the HTTP Connection, the Serializer will help you build the SOAP Envelope and the Reader will help you to access the result.

  Dim Connector As SoapConnector
  Dim Serializer As SoapSerializer
  Dim Reader As SoapReader
  Set Connector = New HttpConnector
  Set Serializer = New SoapSerializer
  Set Reader = New SoapReader

• Prepare the Connector to talk to the SOAP Server. Note that the "SoapAction" data is not consequential on the server side so the contents can be anything at all - It is a good idea to set it to the URI and Method name for easier identification when you are debugging and reading the SOAP messages.

  Connector.Property("EndPointURL") = URL
  Call Connector.Connect
  Connector.Property("SoapAction") = URI & "#" & Method
  Call Connector.BeginMessage

• Associate your Serializer with your Connector.

  Serializer.Init Connector.InputStream

• Start the SOAP Envelope and specify the Encoding and XML-Schema.

  Serializer.startEnvelope , ENC
  Serializer.SoapNamespace "xsi", XSI
  Serializer.SoapNamespace "SOAP-ENC", ENC
  Serializer.SoapNamespace "xsd", XSD

• Start the body of the message - the root element is always the Service URI and method.

  Serializer.startBody
  Serializer.startElement Method, URI, , "method"

• Write each method parameter out as a child to the root element.

  Serializer.startElement "Author"
  Serializer.SoapAttribute "type", , "xsd:string", "xsi"
  Serializer.writeString "Wilde, Oscar"
  Serializer.endElement

• End the root element, the body and the envelope.

  Serializer.endElement
  Serializer.endBody
  Serializer.endEnvelope

• Ending the message causes it to be sent.

  Connector.EndMessage

• Load the result into the Reader.

  Reader.Load Connector.OutputStream

• If no fault loading the Reader then you can go ahead and pull the result of the invocation out of the DOM (Document Object Model) contained in the reader. There are many ways to do this ranging from methods highly specialised to the task at hand (and thus quite efficient) to more general and reusable methods that are not so efficient (like the method you will see in the downloadable source).

  If Not Reader.Fault Is Nothing Then
    MsgBox Reader.faultstring.text, vbExclamation
  Else
    Set Result = Reader.DOM
    //parse the DOM to extract the result set
  End If

Writing the Client
First, download the source code zip file (the VB forms) for the Visual Basic Quotation Service Client. Extract the entire contents of the zip to the directory of your choice. Then open up Visual Basic and Create a new project (of type Standard EXE), remove the default form and add ALL THREE downloaded forms to the project. Ensure that you set the main form (main.frm) to be the Startup Object (use: Project Properties / General tab). Before running you will need to add references to the MS SOAP Toolkit DLLs. Once done they should look like this (the last four references being the ones to add):

Running the Client
You can either compile the project into an executable and run that or just run it from within Visual Basic. The interface is fairly straightforward and does not require any explanation. Once again, the code as is presumes that you have the Quotation Service running on your machine (at localhost:8080). If this is not the case then you can run the clients against our demo SOAP server. To do this simply replace localhost:8080 with services.xmethods.net in the in the space provided for the URL. For more information on our demo server, refer to the Demo Section.