Simplest Example: Writing an XML Web Service


As I always do when trying to learn or explain a new piece of technology, I’ve written the simplest sample program that I could think of to demonstrate XML Web services. The program exposes a single method, called GetTime, that provides the current time on the server machine in the form of a string, either with or without the seconds digits. You can download the sample code for this service from this book’s Web site (http://www.introducingmicrosoft.net) and follow along with this description.

An XML Web service example begins here.

I wrote this XML Web service in the form of an ASP.NET page. I first installed the .NET Framework SDK, a free download from http:// msdn.microsoft.com. I then used the normal Windows 2000 Internet Information Services (IIS) administrative tools to set up a virtual directory pointing to the folder in which I would do my XML Web service file development. Then I wrote my ASP.NET code in a file named TimeServiceVB.asmx (or TimeServiceCS.asmx) on my server. You don’t need Visual Studio for this; in fact, I did the whole thing in Notepad. The program is shown in Listing 4-1.

You don’t need Visual Studio to write an XML Web service; I wrote this one in Notepad.

Listing 4-1: A basic XML Web service.

start example
<%@ WebService Language="VB" %> ‘ The previous header line tells ASP.NET that this file contains ‘ a Web service written in the Visual Basic language ‘ and that the name of the class providing that service ‘ is TimeService. ‘ Import the namespaces (think of them as references) ‘ required for a Web service. Imports System Imports System.Web.Services ‘ Declare a new class for our new service. It inherits ‘ from the system-provided base class WebService. Public Class TimeService : Inherits WebService ‘ Place our functions in the class. ‘ Mark them as WebMethods. <WebMethod()> Public Function GetTime (ShowSeconds as Boolean) _ As String ’ Perform the business logic of our function. ’ Find current time, format as requested, and ’ return the string. If (ShowSeconds = TRUE) Then return DateTime.Now.ToLongTimeString Else return DateTime.Now.ToShortTimeString End if End Function End Class 
end example

While this program is quite simple, it contains a few constructs that are probably new to you, so let’s go over it section by section. The program starts with the standard ASP.NET salutation, <%@ %>. In it we have the directive WebService, which tells ASP.NET that the code on the page should be exposed as an XML Web service. The Language attribute tells ASP which language compiler to use for the code on the page. I’ve used Visual Basic because it’s familiar to the greatest number of my readers (although you’ll also find a C# version with the sample files). ASP.NET will use Visual Basic .NET to compile the code. You don’t have to install Visual Studio; all the language compilers come with the .NET Framework SDK. The Class attribute tells ASP.NET which object class to activate for incoming requests addressed to this service.

Your ASP.NET page specifies which .NET object class to use for the XML Web service.

The rest of the page contains the code that implements the class. I used the Imports directive, a new feature of Visual Basic .NET, which tells the compiler to “import the namespaces,” as I described in Chapter 2.

ASP.NET will automatically compile your Visual Basic code the first time a request comes in for it.

The next line defines the name of our class. You’ve seen and written many classes in Visual Basic, and this one is very similar. My program uses a new keyword at the end of the line that reads Public Class TimeService : Inherits WebService. One of the main enhancements to Visual Basic .NET is its support for an object-oriented programming technique called inheritance, which I described in Chapter 2 and which you will grow to like. When I say that my new TimeService class inherits from the WebService class, I am telling the compiler to take all the code from the system-provided class named WebService (known as the base class) and include it in the TimeService class (known as the derived class). Think of inheritance as cutting and pasting without actually moving anything. In fact, deranged C++ and Java geeks often refer to physically cutting and pasting code as “editor inheritance.” The WebService class is provided by the.NET run-time library, just as many Visual Basic 6 objects were provided by the operating system. This class contains all the prefabricated plumbing required to handle the incoming HTTP requests and route them to the proper methods on your object.

Visual Basic now supports inheritance, which allows you to easily access prefabricated system features.

Now that we’ve defined our class, we need to define the methods of the class. Again, doing this is very similar to the way you do this in Visual Basic 6, with one new twist: you have to add the new attribute <WebMethod( )> to every method that you want exposed to Web clients. This attribute tells ASP.NET that the method in which it appears is to be exposed to clients as a Web service. You’ve seen plenty of attribute-like elements in Visual Basic 6, such as Public, Private, and Const. Visual Basic .NET and the .NET Framework use many more of them, hence the new syntax for specifying them. Just as your class can contain public and private methods, it can contain some methods that are exposed to Web clients and others that are not.

You tell ASP.NET to expose your method as an XML Web service by adding an attribute to the code.

Finally, we get down to the internals of our method. The handling of times might be a little new to you; it was to me. Don’t worry about it today; it’s just how Visual Basic .NET deals with dates and times.

You write your business logic in Visual Basic classes, pretty much as you’ve always done.

Now let’s access our XML Web service from a client. ASP.NET contains good prefabricated support for this as well. If you fire up Internet Explorer and request the ASP.NET page we just wrote, you will see the page shown in Figure 4-4.

click to expand
Figure 4-4: Default screen generated by ASP.NET when you request the XML Web service base page.

ASP.NET detects the access to the XML Web service page itself (as opposed to one of the methods within the service) and responds with a page showing the list of functions supported by the service—in this case, only GetTime. If you click on the name of the function, ASP.NET will respond with a page that provides a test capability for this method, as shown in Figure 4-5. Enter TRUE or FALSE to tell GetTime whether to show the seconds digits, click Invoke, and the test page will call the specified method and return the results, as shown in Figure 4-6. You can see in the Address box that the parameters are passed in the URL and the results returned as XML. Also note that you must open the page in a way that goes through IIS, typing in a URL such as http://localhost/[your virtual directory name]/TimeServiceVB.asmx. If you simply double-click the page in Internet Explorer’s view of your hard disk, you’ll bypass IIS and ASP.NET and simply receive the text of the .ASMX page, which isn’t what you’re looking for.

click to expand
Figure 4-5: ASP.NET responds with a page like this.

click to expand
Figure 4-6: Results returned by the XML Web service.

The convenient logistical and deployment features of .NET objects, described in Chapter 2, apply to my XML Web service as well. For example, ASP.NET does not need registry entries to locate my object as COM did; instead, the URL specifies the location of my object. Updating the code is quite easy; I just copy the new file over the old one. (Try this with the sample code on your local machine.) It isn’t locked as a COM server would be. I don’t even have to restart my IIS server to make it notice the new file. It automatically detects the fact that the file has changed, compiles it just-in-time if necessary, and uses the new version for future object requests.

The XML Web service is as easy to administer and deploy as other .NET objects.

That’s all I had to do to write my XML Web service. It took only 12 lines, counting Else and End If. How much easier does it get?

start sidebar
Tips from the Trenches

XML Web services exist to solve the problems of communicating among heterogeneous parties. If you care only about communicating from one Microsoft box to another, you probably want to at least have a look at .NET remoting. It’s more flexible and gives better performance than XML Web services because it takes advantage of the fact that both client and server are running on Microsoft .NET systems. Chapter 10 of this book describes .NET remoting.

end sidebar




Introducing Microsoft. NET
Introducing Microsoft .NET (Pro-Developer)
ISBN: 0735619182
EAN: 2147483647
Year: 2003
Pages: 110

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net