Creating a Simple XML Web Service

In this section, you build a simple XML Web service that converts back and forth between temperatures in degrees Fahrenheit and degrees Celsius. The Web service has two methods : ToCelsius and ToFahrenheit . The complete code for this Web service is included in Listing 22.1.

Listing 22.1 TemperatureService.asmx

 <%@ WebService Class="TemperatureService" %> Imports System Imports System.Web.Services Public Class TemperatureService : Inherits WebService   <WebMethod()> Public Function ToCelsius( TF As Double ) As Double     Return ( 5/9 ) * ( TF - 32 )   End Function   <WebMethod()> Public Function ToFahrenheit( TC As Double ) As Double     Return ( 9/5 ) * Tc + 32   End Function End Class 

The C# version of this code can be found on the CD-ROM.

The first thing you should notice about Listing 22.1 is that very few lines of code are required to build a Web service. Here, you create a public class, named TemperatureService , that inherits from the .NET WebService class.

NOTE

Strictly speaking, you don't even need to inherit a Web service from the .NET WebService class. Doing so simply makes it easier to access intrinsic objects, such as the Application , Session , and Cache objects.

Next, you declare two methods for the class by using Visual Basic functions. They are the two methods exposed by the Web service.

Notice the strange expression that appears in each of the two function declarations. For example, the ToCelsius function is declared like this:

 <WebMethod()> Public Function ToCelsius( TF As Double ) As Double 

The <WebMethod()> expression applies a custom attribute, named WebMethod , to the ToCelsius function. The WebMethod custom attribute exposes the function to the world so that it can be accessed through the Web service.

NOTE

You can use the WebMethod attribute with both methods and properties.

You need to understand the difference between a function declared with the Public modifier and the WebMethod custom attribute. Functions declared with the Public access modifier can be accessed by all procedures in all classes in an application. However, they are not automatically exposed as methods of the Web service. To be exposed as a Web method, the function must be Public and be flagged with the WebMethod attribute.

One last thing that you should notice about Listing 22.1 is that the name of the file ends with the extension .asmx . This extension identifies Web services. When you create a Web service, you must save the file that defines the Web service with the extension .asmx in a directory that your Web server can access.

NOTE

Be careful where you save your Web service file. When you announce your Web service to the world, you cannot easily change its location.

Setting WebMethod Attributes

The WebMethod custom attribute has the following optional properties:

• BufferResponse ” By default, Web service methods and properties buffer responses in chunks . If you want to stream a response back to a client, you can set this property to the value False .

• CacheDuration ” By default, Web service methods and properties do not cache responses. However, you can set this property to an integer value to cache a response for a certain number of seconds.

• Description ” This property contains the description for methods and properties used when Web service description documents are generated.

• EnableSession ” By default, Web service methods and properties do not participate in session state. If you set this property to True , the method or property can use session state.

• MessageName ” This property can be used to create an alias for a Web method name.

• TransactionOption ” This property enables you to specify how the Web service participates in transactions. By default, transactions are disabled.

If you want to provide a description for the ToCelsius method, for example, you would declare the method like this:

[View full width]

 
 [View full width] 
 <WebMethod(Description:="Converts Fahrenheit to Celsius")> Public Function toCelsius( TF  As Double ) As Double     Return ( 5/9 ) * ( TF - 32 ) End Function 

This description is used, for example, in the Web Service Help page. I discuss this file in the section titled "Testing an XML Web Service from a Browser" later in this chapter.

Setting WebService Attributes

In the same way in which you can specify attribute properties for individual methods of a WebService , you can specify attribute properties for a Web service as a whole. To do this, you use the properties of the WebService attribute class. This class has the following three properties:

• Description ” Provides a description for the Web service. This description appears in the Web Service Help page.

• Name ” Specifies a name for the Web service (by default, the class name is used).

• Namespace ” Specifies the XML namespace for the Web service (not to be confused with the .NET namespace).

The last property, Namespace , is particularly important. By default, the XML namespace is set to http://tempuri.org/ . You should specify a new URL for the Namespace property, such as http://www.yourdomain.com/services . The URL that you specify does not need to point to an actual Web page. The URL is simply functioning as a unique identifier so that Web services developed by your company can be distinguished from Web services developed by other companies.

Here's how you would set the Description and Namespace properties when declaring the TemperatureService Web service:

[View full width]

 
 [View full width] 
 <WebService(Description := "Temperature Service", Namespace := "http://www.yourdomain.com  /webservices")>_ Public Class TemperatureService 

Precompiling an XML Web Service

You don't need to compile the class file for a Web service before you can use the Web service. Like an ASP.NET page, a Web service is automatically compiled when it is requested . However, if you are selling a Web service class file or you have other reasons for hiding the source code, you have the option of precompiling the service.

NOTE

There is absolutely no performance difference between a compiled and uncompiled Web service.

To compile the TemperatureService in Listing 22.1, you would need to strip away the first line so that the file contains only a class declaration. The file in Listing 22.2 contains the pure class definition in a VB file (I've renamed the class to CompiledTemperatureService ).

Listing 22.2 CompiledTemperatureService.vb

 Imports System Imports System.Web.Services Public Class CompiledTemperatureService : Inherits WebService   <WebMethod()> Public Function ToCelsius( TF As Double ) As Double     Return ( 5/9 ) * ( TF - 32 )   End Function   <WebMethod()> Public Function ToFahrenheit( TC As Double ) As Double     Return ( 9/5 ) * Tc + 32   End Function End Class 

The C# version of this code can be found on the CD-ROM.

Next, you must compile the CompiledTemperatureService.vb file. To do so, execute the following command from a command-line prompt:

 vbc /t:library /r:System.dll,System.Web.Services.dll CompiledTemperatureService.vb 

This command executes the Visual Basic compiler. The CompiledTemperatureService.vb file is compiled into a DLL file that references both the System.dll and System.Web.Services.dll assemblies. If the CompiledTemperatureService.vb file is successfully compiled, a file named CompiledTemperatureService.dll is produced.

When you have a compiled class file, you need to copy the file to the /bin directory of your ASP.NET application. If the /bin directory doesn't exist, you can create it.

The final step is to create the .asmx file that references the compiled class. The new .asmx file contains only a single line. The complete code for the file is shown in Listing 22.3.

Listing 22.3 CompiledTemperatureService.asmx

 <%@ WebService Class="CompiledTemperatureService" %> 

The C# version of this code can be found on the CD-ROM.

The page in Listing 22.3 contains a single directive. The Class attribute refers to the compiled CompiledTemperatureService class file in the /bin directory.