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 AttributesThe WebMethod custom attribute has the following optional properties:
If you want to provide a description for the ToCelsius method, for example, you would declare the method like this: [View full width]
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 AttributesIn 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:
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]
Precompiling an XML Web ServiceYou 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.vbImports 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. |