Microsoft .NET XML Web Services - 19 Feb 2002

Yeah, yeah, yeah, everybody is talking about XML Web services these days, whether in the generic form, or as provided through .NET, or being easy to develop using Microsoft Visual Studio .NET, or how they will be the backbone of "HailStorm" (still a code name). If you've read any of the various documents, white papers, or press announcements, you have already been bombarded with all the architectural diagrams, business model examinations, services infrastructure discussions, and other such related chest beating as you can probably stomach at the moment. Heck, I've even been shoving this stuff down your throat for the last few months. But what the heck is it all about anyway, and how can you really make use of it?

In this article, I want to show you some very simple code that illustrates how straightforward XML Web services can be, and how you can almost instantly start using them.

For any of us who have any sort of long-standing background with computers, we all remember the early days when it seemed like there were all sorts of competing computer systems out there. I'm not talking about the big boy machines that were owned by universities and data processing businesses, but the home machines. Apple, IBM, Texas Instruments, KayPro, Commodore, Timex, Radio Shack, and even Mattel were producing Personal Computers of every size and shape. There are various debates over why one was more successful then the other, but I remember what my own feelings were back in those days.

As I would read about, and try various computers, the ones that hit home for me were the ones that were instantly functional from a programmer's perspective. I'm talking about the ones that could do more than just run prepackaged programs (normally games). The cool ones for me were those that I could sit down and write some of my own code, without needing to purchase any additional hardware or software. The programs I could write weren't artificially limited, but could essentially access all aspects of the computer. Now that was a functional computer.

My first computer was a TI 99/4A. As computers went, it was pretty cool-built in BASIC, full color display, and programmable screen fonts. But alas, the built in BASIC was limited. To program in Assembler, you had to buy not only additional development software, but also an Extended Memory Module (EMM), and anybody that wanted to run your programs had to have the EMM as well. After a brief time in the spotlight, the TI eventually spiraled down to obscurity. My next computer was an Apple //c. Here was a fully functional computer that you could program in BASIC or Assembler, with Peeks and Pokes aplenty to access low level features built into the firmware. Straight out of the box-no further purchases necessary.

All of this underscores one aspect that I think is important to technological success, which is the broad and common availability, as well as accessibility, without the need for fancy special purpose hardware, software, or whatever. Make a technology accessible and useful to the common individual, and it stands a much better chance of really making a difference. What does this have to do with XML Web services?

It presents the fact that I could rant and rave about how great XML Web services are, but if you couldn't touch them for yourself without all sorts of software installation gymnastics, they wouldn't be real. So, I'm going to show you how you can access XML Web services programmatically running nothing more than Microsoft Windows XP. Granted, this does put one installation barrier in front of us, but it is one that hopefully represents the norm that we will see on all Windows systems in short order.

Two very important components are included in Windows XP that allow you to reach out and touch XML Web services for yourself. The first is the Windows Scripting Host, something that has been included in all versions of Windows for a couple of releases now, and almost taken for granted. The other is the inclusion of the Microsoft SOAP Type Libraries. This provides the necessary programmatic interfaces to access and interact with .NET XML Web services. Enough jabbering about it, lets cut to the chase.

If you are running Windows XP, then do the following:

Create a new text file named Mystic.vbs.
Enter into it the following VBScript code:
SET scEightBall = CreateObject("MSSOAP.SOAPClient")
scEightBall.mssoapinit _
"http://www.gotdotnet.com/playground/services/eightball/EightBallWS.asmx?WSDL"
WScript.Echo scEightBall.Ask("Will I have a date this Friday?")

Now execute the script file. This can be done by double clicking on its icon or by typing in the following at a command prompt:
C:> cscript mystic.vbs

Either way, you should see a response come back with an answer to your important question. You've now written your first application that uses XML Web services. Let's take a quick look at what we did, and how it accomplishes this feat.

First off, it is important to find a .NET Service that could be used for this purpose. This is perhaps the hardest part of the entire process. UDDI is a services directory that is designed for locating Internet-based services. One drawback is that it isn't just for listing services that we can consume in the manner that my code above illustrates, so we have to make our choices a carefully. Of specific importance is that we end up with a URI that ends in .asmx?WSDL. This is where ASP .NET is being requested to provide a WSDL (Web Services Description Language) for the XML Web service being provided. It is through the WSDL that the Microsoft Soap Type Library is able to figure out what the exposed interfaces are of an XML Web service, and how to interact with them.

I happened to know that www.GotDotNet.com has a few examples of XML Web services that it exposes, which helped in finding something that I could use for this example. Here's how I got to the point where I knew exactly what the three lines of code above needed to look like:

First I went to http://uddi.microsoft.com, which is a broad-based directory of various businesses and the services that they provide. In the Search by business name field, I entered in GotDotNet. There is a variety of other ways that I could have preceded with the search, but this was the most straightforward given the situation. The search result came back with a listing/link for: GotDotNet
The .NET Framework Community Web site

Which of course is what I was after, and I naturally clicked on this link.

This brought up a list of the services that have been registered for GotDotNet, and included:
Name Description
.NET Resources The GotDotNet Resource Center is your portal to a diverse directory of .NET Framework links. In it, you will find links to many .NET Framework Web sites.
Thumbnail Generator The Thumbnail Generator Web Service creates a .gif image of a specified URL. The service stores the image on the server for a predetermined amount of time and returns the URL to access it.
Quote of the Day This example returns an interesting, new quote every day.
EightBall The EightBall Web Service simulates the well-known eight ball toy we've all come to know and love. It does so by randomly selecting one of a number of standard answers from an XML file. test This Web service serves as a test. Not to exciting, but handy when you need it.

The two on this list that looked interesting were the Quote of the Day and EightBall. Since the response coming back from EightBall sounded like it might be a more dynamic because it changes more than once a day, I figured that was a good choice, and clicked on it. This next page, which is still on the UDDI Web site, contains more detail about the EightBall Web Service. It includes a link to http://www.gotdotnet.com/playground/services/eightball/EightBallWS.asmx which is the base URL for the XML Web service, and the next target for your fearless mouse to click on.
The page that comes up is the result of clicking on the ASMX file. It is important to note that what you will see is not the contents of the ASMX file, but rather the content that has been created for you by ASP .NET, which is interpreting the contents of the ASMX file and creating the appropriate HTML that essentially documents the XML Web service and its available operations. In this particular case, all that we see listed is the name of this service (EightBallWS), and that it exposes a single operation (Ask).
If you were to click on Ask, it not only shows you the SOAP description of this interface. From this I can see that this function takes a string as input, and provides a string as a result. This page also provides you with a simple form that you can use to test this service. Entering a question in the input box and hitting the Invoke button will bring back a Web page with the XML of the actual response.
I now know the key things that I need in order to code my use of this function. Specifically I know:

That the URL of the service is
http://www.gotdotnet.com/playground/services/eightball/EightBallWS.asmx.
That the name of the service is EightBallWS.
That the function I want to call is Ask, which takes a string as an input parameter, and returns back a string as a result.
Let's take another look at my code, and dissect it step by step:

SET scEightBall = CreateObject("MSSOAP.SOAPClient")

This is the code that creates the SOAP client object that I'll be using.

scEightBall.mssoapinit _
"http://www.gotdotnet.com/playground/services/eightball/EightBallWS.asmx?WSDL"

This code initializes my SOAP object, and points it at the XML Web service that I want to consume. I could have also listed the second (optional) parameter to mssoapinit, which would have been EightBallWS (the name of the service I wanted to attach to). This leaves us with:

WScript.Echo scEightBall.Ask("Will I have a date this Friday?")

This bit of code simply calls the one method that I am accessing from this service, and displays the results to the screen.

All of this illustrates how amazingly straightforward it is to write a simple application that utilizes a .NET XML Web service. With Windows Scripting providing an elegant way to programmatic interaction between the user and XML Web services, the level of programming comes down to a real plane that we can all experience first hand.

For the sake of completeness, I've continued with the development of the simple application, and created a more robust version that allows you to dynamically enter in the question to which you want an answer. I've also done up the code so that it will work properly from command line execution or from double-clicking on the icon directly.