Web Service using SOAP Toolkit in VB.NET

The world of web services has taken applications by storm. From an era where applications were tightly bound to one another, we have reached a time wherein applications are delivered as a "service". This concept of sharing application logic over the internet promotes a new kind of application development wherein applications are built as "building blocks" with each block capable of performing its work in isolation.

This new notion of programming is what is termed as web services, wherein a piece of application logic is exposed as a programming element for others to consume. The concept of web services is still evolving with Microsoft and a host of other companies proposing various standards for managing security, transactions etc.

What is interesting though is that web services need not mean "external" communication. If you develop enterprise scale applications made of multiple modules, you can leverage web services within your application itself to improve reusability and data sharing.

Till date, the concept of web services has been centric around the usage of the same with the .NET Framework. In this article, I will explain about how to develop web services using the SOAP Toolkit 3.0 from Microsoft and to also consume the same web service from a .NET application. I'm assuming that you are familiar with the various terms associated with web services like SOAP, WSDL, XML and also VB and VB.NET.

What is the SOAP Toolkit

The SOAP Toolkit is a component from Microsoft that enables you to convert existing COM components into web services and to also communicate with external service providers using the SOAP protocol. The SOAP Toolkit consists of the following components:

A client-side component that allows an application to invoke XML Web service operations described by a Web Services Description Language (WSDL) file. This WSDL file describes the service(s) and operations of the service offered by the server.
A server-side component that maps invoked XML Web service operations to COM object method calls as described by the WSDL and Web Services Meta Language (WSML) files. The WSML file is necessary for the implementation of the Microsoft SOAP Toolkit.
The components needed to construct, transmit, read, and process SOAP messages. These processes are collectively referred to as marshalling and un-marshalling.
In addition, the SOAP Toolkit provides a WSDL/WSML Generator tool that generates the WSDL and WSML files for you, relieving you of the tedious process of manually creating such files.

The SOAP Toolkit is available free of cost and can be downloaded from the following site: http://www.microsoft.com/downloads/details.aspx?FamilyID=c943c0dd-ceec-4088-9753-86f052ec8450&DisplayLang=en

Quick Introduction to WSDL

The Web Services Description Language (WSDL) is an XML-based language for describing the network services offered by the server. You use WSDL to create a file that identifies the services provided by the server and the set of operations within each service that the server supports. For each of the operations, the WSDL file also describes the message format that the client must follow in requesting an operation.

Quick Introduction to WSML

In addition to creating a Web Services Description Language (WSDL) file describing the services and operations on the server, you need to create a Web Services Meta Language (WSML) file on the server. A WSML file provides information that maps the operations of a service (as described in the WSDL file) to specific methods in the COM object. The WSML file determines which COM object to load in order to service the request for each operation. The use of a WSML file is specific to the SOAP Toolkit.

Developing a Web Service

To develop a web service using the SOAP Toolkit that is to be consumed by other applications, the following steps have to be followed:

Develop a COM component that contains the necessary code that you want to be exposed as a web service.
Generate a WSDL/WSML file for the COM component.
Register a IIS virtual folder to point to the location where the WSDL/WSML and COM files are present.
Access the web service to test out the operations.

And that's it!! You have a web service that anyone can consume from any platform as long as they talk SOAP. In the following sections, we will outline the details of each of the steps above and develop a simple web service that can be consumed by any client.

Before we get down to the details of how to develop a web service, let's first describe the service. The service that I'm going to show is a simple calculator that has two operations called Add and Subtract. The Add operation adds two numbers and the Subtract operation subtracts two numbers. Very obvious, but I've stated it for completion :-).

Step - 1: Create a COM Component

The first step is to create a VB COM component that encapsulates the above two operations. To do this, follow these steps:

Open Visual Basic 6.0 and create an ActiveX DLL project.
Change the project name to MyService and the class name to Adder.
Type in the following code in the code editor.
Public Function Add(ByVal Number1 As Integer, ByVal Number2 As Integer) As Integer
Add = Number1 + Number2
End Function

Public Function Subtract(ByVal Number1 As Integer, ByVal Number2 As Integer) As Integer
Subtract = Number1 + Number2
End Function
Compile the code to a DLL and store it in a directory. Let's call this directory as MyService.

Step - 2: Generate WSDL/WSML File

To generate the necessary web service files for the COM component created in the earlier step, open the WSDL generator that comes with the SOAP Toolkit (this step assumes that you have installed the toolkit). You are now presented with the following UI.

SOAPToolkit1-in-VB.NET.gif

Click [Next] followed by [Next] (2 times). You will then see the following interface:

SOAPToolkit2-in-VB.NET.gif

Here, type a name to identify your service (I've called it MyService) and use the [Select COM Object] button to locate the DLL created in the earlier step. Your interface will now look like this:

SOAPToolkit3-in-VB.NET.gif

Click [Next]. In the next screen, you will see all the Public Functions exposed by the COM component. Here, you can select what functions will have to be exposed for clients to consume. Since we users to access both the operations, click on the check-box next to the MyService node and all the interfaces will be selected. Your interface will now look like this:

SOAPToolkit4-in-VB.NET.gif

Click [Next]. In the next interface, you are presented with the following options:

Listener URI. Here type in a virtual folder path that you want clients to use to access the web site (e.g., MyService). Note that we have not yet created the virtual folder in IIS, but you can specify the name here.
Listener Type. There are two options (ASP or ISAPI). Select ISAPI. This will ensure that any request coming to the URL with a WSDL extension will be routed to the SOAP Toolkit and processed. If you select ASP, the toolkit will auto-generate an ASP file which makes calls to the web service. Your interface will now look like this:

SOAPToolkit5-in-VB.NET.gif

Click [Next]. In this interface, you are given an option to specify the values for various namespaces. For this example, ignore this UI and click on [Next] again. You will be shown a UI where you can specify the path for the WSDL/WSML files. By default the directory selected for the COM component is shown. Accept all the defaults shown in this interface. Your interface will look like the following (the directory drive might be different).

SOAPToolkit6-in-VB.NET.gif

Click [Next]. The toolkit will generate the necessary files into the folder specified above. Click [Finish]. The directory will now contain the following files:

SOAPToolkit7-in-VB.NET.gif

Step - 3: Register a Virtual Folder

To register a virtual folder, open the Internet Services Manager MMC snap-in and create a new virtual folder to point to the MyService folder created earlier (I'm going to call this virtual folder as MyServices). Accept all the defaults that IIS presents to you in the virtual folder creation interface.

Open a command prompt window. Change directory to the C:\Program Files\MSSOAP\Binaries directory (the drive may be different in your machine), and enter the following statement: soapvdir.cmd UPDATE Soap3DocSamples.

The above command will register the ISAPI DLL that will handle requests for the web service.

Step - 4: Test the Web Service

Now we are ready to test the web service. Testing can be done by using a small VBS script. Type in the following code using any text editor (you need to substitute the machine name with your machine name in http://pc-srinivas/...).

Dim oSoapClient
Dim nResult
Set oSoapClient = CreateObject ("MSSOAP.SoapClient30")
If (Err <> 0) Then
MSgBox "Initialization of the SOAP Toolkit failed."
Return
End If
Call oSoapClient.MsSoapInit ("http://pc-srinivas/MyServices/MyService.WSDL", "MyService", "")
If (Err <> 0) Then
MSgBox "Error initializing the WSDL file."
Return
End If
nResult = oSoapClient.Add (3, 4)
MsgBox "Result of 3+4 = " & CStr(nResult)
Set oSoapClient = Nothing

On running this VBS, you should see a message-box which shows the result of the addition. In case you encounter any errors, verify the virtual folder name in the VBS file and whether all the necessary files are present in the virtual folder.

Consuming in .NET

Consuming the above service is very easy in .NET. All you have to do is, create web-reference and point it to the WSDL file and you can access all the methods in the service through the intellisense feature.

Conclusion

In this article, we have seen how to expose COM objects as web service components for others to access. The SOAP Toolkit has many more features that enable applications to provide very robust interfaces for application integration and you are encouraged to try them out. We have just seen only the basics. The .NET Framework provides lots more features for web services, but for starters, the SOAP Toolkit enables applications to interoperate very easily and communicate with external services, without resorting to .NET. In subsequent articles, I will cover more on web-services in the .NET world.