XML, or Extensible Markup Language, is basically text. You already know that text can be sent across the Internet. More importantly XML is an extensible, self-describing markup language, which means you can use XML to describe objects that haven't even been invented yet. The SOAP protocol is capable of marshalling .NET objects to and from XML and pushing them back and forth across networks. The best part about Web Services is that XML and SOAP do their bit behind the scenes; all you have to do is write the code.
What you will not see is a lot of XML and SOAP. The .NET framework takes care of the XML and SOAP for us and we will allow it to do so without examination. (It is worth noting that writing XML from scratch has valuable applications when describing schemas to work with ADO.NET data providers.) In this article I will demonstrate how easy it is to create, test, and use XML Web Services.
Creating a Web Service Project
If you have IIS installed on your workstation then the host name of the Web site will be localhost. If you are using IIS on another machine you will need the URL for that server. The Web Service project will be created as a sub-folder off the root of the Web directory. If created on your workstation then the physical path will be c:\inetpub\wwwroot\webservice by default.
We will name our project TemperatureConverter, which will create a sub-folder c:\inetpub\wwwroot\TemperatureConverter if we are creating the Web Service on our workstation. (Don't worry when you are finished you can use the Project, Copy Project menu item in VS.NET to deploy the Web Service.)
Using the WebMethod Attribute
The capabilities provided by your Web Services are initiated by consumers calling methods tagged with the WebMethod attribute.
Attributes are classes that add metadata to your .NET assemblies. The WebMethod attribute instructs .NET to add the code necessary to marshal calls using XML and SOAP.
Our Web Service performs conversions from Celsius to Fahrenheit. (The way I always remember these conversions is to remember 5/9, 9/5 and 32 are involved. (Sometimes I forget the exact order of arithmetic, so play with the numbers converting boiling and freezing temperatures—100 and 0 in Celsius and 212 and 32 in Fahrenheit—to double-check the arithmetic.
In a Web Service we write our code in the .asmx codebehind file. To implement a Web Method we write the method as we normally would and add the WebMethod attribute. The two WebMethods are shown in listing 1 next.
Listing 1: WebMethods that convert temperature units.
<WebMethod()> _ Public Function CelsiusToFahrenheit( _ ByVal Temperature As Double) As Double Return Temperature * 9 / 5 + 32 End Function <WebMethod()> _ Public Function FahrenheitToCelsius( _ ByVal Temperature As Double) As Double Return (Temperature - 32) * 5 / 9 End Function
Everything about these methods is the same as any other method, except for the addition of the <WebMethod()> attribute. The code itself is contained in a class that inherits from the System.Web.Services.WebService class. The class is contained in the codebehind .asmx.vb module in an ASP.NET Web Service application project.
Testing Your Web Service in IE
To quickly test your Web Service application, open IE and browse to the folder containing the .asmx file. By default this file will be named service1.asmx. For our example project, entering http://localhost/TemperatureConverter/service1.asmx will open the Web Page shown in figure 1. Click on the hyperlinks to test the Web Methods implemented in our Web Service.
Figure 1: The .asmx file returns a dynamically created web page that allows you test Web Methods.
When you click on one of the method name links, a simple interface will be displayed that will allow you to enter values for the parameters needed by the Web Method. Go ahead and click FahrenheitToCelsius if you've been following along. Enter 212 for the temperature and click the Invoke button. If everything is working correctly you should get a new instance of IE with the XML representing the return value of 100.
<?xml version="1.0" encoding="utf-8" ?> <double xmlns="http://tempuri.org/">100</double>
If all Web Services did was to return XML then we'd be in trouble. Fortunately, this is what the simplified .asmx interface does. When you use Web Services in code all of the murky XML is hidden from you. When you invoke a Web Method you get the correct data type and value, rather than the XML.
Integrating Your Web Service into an Application
When you are ready to use a Web Service you need UDDI. UDDI, or Universal Description, Discovery, and Integration, is the name of the technology that reads the .disco file created when you create a Web Service project using the ASP.NET Web Service template.
You use Web Services in an application by opening the Add Web Reference dialog shown in figure 2. The Add Web Reference dialog can be opened by right-clicking on the References folder in the Solution Explorer.
The Add Web Reference dialog will list some links to Web Service Directories (Web sites that host registered Web Services). The bottom link in the Add Web Reference dialog will refer to the instance of IIS running on your PC. Click on this link to display all of the Web Services—discovered by searching the Web site for .disco files—on your PC. To add the TemperatureConverter to an application, click on the link representing the Web Service you want, and click the Add Reference button.
When you have added the Web Reference, a Web Reference folder will be added to the solution explorer. The Web Reference folder will include the name of the web host. You will need the host name to refer to the classes defined in the Web Service application. By default if the host name of our Web site is localhost then we would need to include localhost when declaring instances of the classes in the WebService. The following code demonstrates how to create an instance of a Web Service and invoke Web Methods.
Dim Converter As New localhost.Service1() TextBox1.Text = Converter.CelsiusToFahrenheit(CDbl(TextBox1.Text))
The code listing demonstrates a Windows Forms-based application that converts the text in a TextBox to a double, converts the value to Fahrenheit and assigns the value back to the TextBox.
XML Web Services involve several technologies. XML and SOAP work behind the scenes to marshal data back and forth between consumer and producer. UDDI facilitates finding Web Services that are created by other vendors. The uddi.microsoft.com site provides a directory service that allows producers to register Web Services.
From the producers—the person creating the Web Services—perspective, creating Web Services entails creating an ASP.NET Web Service project and tagging methods with the WebMethod attribute. After you have tested your Web Service you can continue to use the Web Service on an intranet, publish it to your network, or register it with a directory service.
Web services are based on an open standards protocol and are easier to produce and consume. After .NET is released you should expect to see a new cottage industry of Web Service producers, just as we saw an increase in component manufacturers in the last decade.
About the Author
Paul Kimmel is a freelance writer for Developer.com and CodeGuru.com. Look for cool Visual Basic .Net topics in his upcoming book Visual Basic .Net Unleashed featured on Amazon.com in December, 2001 and January of 2002. Paul founded Software Conceptions, Inc. in 1990. Contact Paul Kimmel at firstname.lastname@example.org for help building VB.NET applications or migrating VB6 applications to .NET.