Microsoft & .NET.NETUnwrapping Microsoft's SOAP Toolkit

Unwrapping Microsoft’s SOAP Toolkit

"Web services let you provide information from other sites rather than developing the resources yourself."

SOAP, the Simple Object Access Protocol, is gaining steam as a way to make method calls across the Web. Based on XML, it allows application and object activation across platforms, a feature crucial to distributed Web applications. Microsoft has been one of the biggest proponents of the proposed SOAP standard, and is actively designing it into the next generation of their Web and development tools. The company has released the SOAP Toolkit, the preview edition of tools they hope will banish script from the Web forever and make Visual Basic and Visual C++ the Web development tools of choice. SOAP itself and the tools in the SOAP toolkit seem to have what it will take to make this kind of a fundamental change to the Web.

The toolkit is not a separate product in itself, but is a technology preview of some of the features the company is developing for its next version of Visual Studio and Web servers. It supports Web Services, programmable URL addresses that can process and return data. For example, you can develop a single Web page with the current time in Malaysia, the weather in Sri Lanka, and translations into ten languages of a greeting appropriate to the time of day. Nothing particularly new in that. But Web services let you provide this information from other sites rather than developing the resources yourself.

Web architects envision that sites will develop and market these kinds of services. SOAP provides the remote method invocations across HTTP, the transport protocol of the Web. By using HTTP, it is able to support multiple platforms and avoid messy network security issues such as firewalls by sticking to port 80.

These are the features that Microsoft is building into Visual Studio 7—still its working name—and the SOAP toolkit lets developers start working with the technologies now. The toolkit brings together several technologies that developers can use together—XML, HTTP, SOAP, Service Description Language (SDL), COM, and IIS—some old, some new. More now than ever, developers will need to have a good mix of both traditional programming language and Web technology skills.

SOAP Toolkit Goodies

The toolkit contains a mix of documentation, tools, preliminary specifications, and sample code, enough to fill a couple of days of exploration and play. But beware: the user is constantly reminded that this is a work in progress, both in its informality and sparseness, and can change in its entirety at almost any time.

Documentation consists of a reasonably good HTML help file and Service Description Language (SDL) specification in the form of a Word document. The help file provides introductory material, explanations of the sample code in the toolkit, and a complete ROPE API reference (discussed more below). The SDL specification describes a standard XML document format used to expose the methods, parameter types, and return types of the particular Web service. Other documentation covers using SOAP with low-level ISAPI development, troubleshooting, and data conversions between COM and XML.

The sample application provides a good introduction to the use of SOAP, ROPE, and Web Services. The client application, shown in Figure 1, retrieves the current stock price for a given stock symbol, the current time on the server, the current Universal Coordinated Time from the U.S. Naval Observatory, and translates text among six language. The client sample is initially set up to use a server that Microsoft has set up on its own servers for the application, but the toolkit also provides all the source for setting up your own server for testing. The client also includes code to use SOAP directly and to use the ROPE automation objects—discussed below—that simplify coding on the client side, so you can get a feel for how everything works.

As Figure 1 shows, the sample client application in the SOAP toolkit is a forms-based Visual Basic app that demonstrates how clients can consume Web services. Clients don’t need to be browser-based.

A Sample Application from the Kit
Figure 1. The Kit includes a sample forms-based VB application.

While this all may feel a bit mystical in its simplicity, there really is nothing very extraordinary on the server. SOAP takes care of packaging the method call on the client, and unpackages the request on the server. For the code that implements the GetStockQuote method, there are but three important lines of code in the services.asp file.

set oWire = Server.CreateObject("Rope.WireTransfer") sBuffer = "" & Symbol sBuffer = oWire.GetPageByURI(CStr(sBuffer))

The WireTransfer object provides functionality for conducting HTTP POST and GET operations, and the GetPageByURI retrieves a page based on a supplied URI, which in this case invokes the Web service and returns the requested data to the client. Another dozen or so lines of code in GetStockQuote prettify and extract the data from the returned sBuffer string.

The code to return the server system time from the GetServerTime function demonstrates just how much rocket science is involved:

GetServerTime = Now

It just doesn’t get simpler than that!

One nice tool in the toolkit is the SDL wizard. The wizard can generate a Service Definition file from any existing COM component that provides the Web service. The wizard creates the XML file necessary to expose the COM object as a Web Service as well as a skeleton listener file that receives client requests, instantiates the COM object, and calls the requested method. All you need to do is add any additional code to the ASP or ISAPI listener file to make the service work properly. The wizard saves a lot of work and helps you learn how to structure SOAP on the server.

Figure 2 shows how the SDL Wizard steps you through the process of auto-generating and XML file that describes the services provided by a COM object. Here you can select which methods you want to include in the Web service.

SDL sample program image
Figure 2. A SDL sample app from the Toolkit


Proving that the punmeisters are working hard, the SOAP toolkit introduces ROPE, the Remote Object Proxy Engine. The other parts of the toolkit are sufficient for using SOAP itself, but it can be hard work writing the code that packages everything together into the required formats defined by SOAP that HTTP can handle. So ROPE provides an infrastructure in the form of ActiveX objects to build SOAP applications on both the client and server.

On the client, ROPE assists the application with packaging the SOAP message and then unpacking any reply that it receives from the server. On the server, it supports building a listener’ application that can receive, parse, and dispatch SOAP messages back to the client, as well as executing locally the methods requested by the client.

ROPE provides several COM objects, but the one you’re likely to use most often is Proxy. There are but five properties and methods to Proxy, making it painless to package and send a SOAP request, here in a non-browser Visual Basic application:

Private Sub btnGetStockQuote_Click()Dim sBuffer As StringDim oProxy As ROPE.Proxy   Set oProxy = New ROPE.Proxy   oProxy.LoadServicesDescription icSTRING, ServicesDescription   sBuffer = oProxy.GetStockQuote(txtSymbol.Text, "any company")   MsgBox "Share price = " & sBuffer, vbOKOnly, txtSymbol.Text   Set oProxy = NothingEnd Sub

This code retrieves a current stock price from a Web service by providing the stock symbol and description as parameters. After creating an instance of the ROPE Proxy object, it loads the Services Description file that contains information about the methods the Web service makes available, parameter data types, and any return data types. This file is written using the Service Description Language (SDL), an XML file that does for SOAP roughly what a type library does for COM: identify what the component or service can do.

The Services Description file identifies the URL or URI needed to locate the Web service, sets up namespaces, and defines the available methods. For our stock quote example, this is the SDL:

<interface name="QuoteInterface">        <requestResponse name="GetStockQuote">                <request ref="ss:GetStockQuoteInput" />                 <response ref="ss:GetStockQuoteOutput" />                 <parameterorder>symbol description</parameterorder>        </requestResponse></interface>

This is XML as defined in the SDL specification, describing the interface, methods, and parameters used by the Web service methods. SDL is quite flexible, allowing for features such as interface definitions, request and response definitions, and a form of inheritance.

Back in the Visual Basic code, once the Service Description file loads, the Proxy object’s interface is expanded to support the methods of the Web service, allowing immediate invocation of any method. A potential problem with this way of doing things is that the methods of the Web service are late bound even if the Proxy object itself is early bound, since there is no way to know at design time what methods the Web service will provide at run time. I’m not too concerned about that because in my experience any slowness from using late bound objects likely pales to the delay from passing the information over the Internet, even small chunks of text. But it also prevents development environments like Visual Basic and Visual C++ from using Intellisense to provide a list of available Web service methods.

Once the client application invokes the method, it can use any return data and then release the Proxy instance. The whole process should feel remarkably familiar, almost like doing any kind of remote call with DCOM, but with different infrastructure requirements. Using ROPE saves a lot of work in your applications, and makes it easy to accommodate changes in SOAP as the standard evolves. Best of all, the full C++ source code for the ROPE.dll is included in the toolkit.

As I write this, SOAP is still a relatively new W3C Note, the first step on the way to becoming a standard. Changes are sure to come as the standards committee forms and begins its work. But with the weight of Microsoft behind it, and their commitment to make it a part of the next version of the Visual Studio tools, SOAP is sure to have an impact on how we do Web development in the years to come, at least on Windows.

About the author: Don Kiely is a Software Technologist at Third Sector Technologies in Fairbanks, Alaska, and has written and co-written several programming books.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories