17.1 Creating an ASP.NET Web Service

You want to create an ASP .NET Web Service.

Technique

Web Services are represented as a set of standards specifying everything from the actual definition of a Web Service to the protocol used between two machines when exchanging information. The amount of information that you must have to create a simple Web Service is not something you can pick up in a day. However, Visual Studio .NET has created a rich Web Services infrastructure, so someone new to the topic can quickly create and use a Web Service, assuming knowledge in a .NET language, of course.

To create a new Web Service, select the ASP.NET Web Service template from the New Project dialog. The project is created within a virtual directory in Internet Information Server (IIS), just like an ASP.NET Web Application, and also contains several defaults that you want to change before publishing the Web Service.

When the project opens, you see a special design view that you can use to drag and drop any necessary components your Web Service might need. Because a Web Service isn't a visual entity, only toolbox items on the Components tab are available. The next recipe describes how to add methods to your Web Service to expose its functionality. To open the code-behind file for a Web Service, click on the corresponding link in design view or right-click on the .asmx file in Solution Explorer and select the View Code menu item.

An ASP.NET Web Service itself appears as an ordinary class library. The New Project Wizard has already created a default class whose name you will want to change to better fit the description of your Web Service. Each Web Service contains an associated Web Service Description Language (WSDL) document describing various facets of the service, including the methods it supports. This WSDL file is handled by the ASP.NET runtime, which means you can only view it. However, you are able to inject additional information by applying the WebService attribute to your Web Service class.

The WebService attribute contains a few parameters that add information to the generated WSDL file. The Description parameter, as its name implies, allows you to enter a descriptive statement explaining what the Web Service does. The Name parameter is the actual name of the Web Service. If you omit this parameter, the name of the class is the name of the Web Service. Finally, the Namespace class serves the same purpose here as it does in XML documents, which is to uniquely identify your Web Service to alleviate any ambiguities that might arise if someone else were to create a Web Service of the same name. This chapter demonstrates a random-number generator Web Service called the Lottery Web Service. The service itself allows a connecting client to request a specified series of numbers within a certain range that might or might not include duplicate numbers . Listing 17.1 shows the WebService attribute for this Web Service.

Listing 17.1 Attributes Help Describe Web Services

 using System; using System.Collections; using System.ComponentModel; using System.Data; using System.Diagnostics; using System.Web; using System.Web.Services; namespace _1_LotteryService {     [ WebService( Namespace="http://samspublishing/1_LotteryService",     Description="Provides the ability to generate a set of random numbers",     Name="Lottery Web Service")]     public class LotteryNumberGenerator : System.Web.Services.WebService     {         public LotteryNumberGenerator()         {             InitializeComponent();         }         private IContainer components = null;         private void InitializeComponent()         {         }         protected override void Dispose( bool disposing )         {             if(disposing && components != null)             {                 components.Dispose();             }             base.Dispose(disposing);         }     } } 

Comments

Once you create the initial project for the ASP.NET Web Service, you can view its output using your browser because of the internal framework that is automatically provided by ASP.NET. After you run the application, the browser is open, displaying your Web Service's .asmx file. The .asmx file is initially opened in design view and by default does not contain a lot of information. In fact, if you open the .asmx file in a text header, all you see is the ASP.NET Web Service directive:

 <%@ WebService Language="c#" Codebehind="LotteryService.asmx.cs" Class="_1_LotteryService.LotteryNumberGenerator" %> 

This header is similar to that of an ASP.NET application that uses the @Page directive in that it specifies the language of the service along with the filename of the code-behind file and the class that implements the Web Service. With just this information, ASP.NET can automatically generate the WSDL file using the Reflection methods discussed in Chapter 23, "Reflection." To view the current WSDL file for the Web Service, click on the Service Description link in the .asmx file within the browser. As you might have guessed, WSDL, like all other Web Service technologies, is XML based. Listing 17.2 provides the generated WSDL file for the Lottery Web Service.

Listing 17.2 Lottery Web Service WSDL File

 <?xml version="1.0" encoding="utf-8" ?> <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"     xmlns:tns="http://samspublishing/1_LotteryService"     xmlns:s="http://www.w3.org/2001/XMLSchema"     xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"     xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"     xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"     xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"     targetNamespace="http://samspublishing/1_LotteryService"     xmlns="http://schemas.xmlsoap.org/wsdl/">     <types/>     <service name="Lottery_x0020_Web_x0020_Service">         <documentation>Provides the ability to generate a set             of random numbers</documentation>     </service> </definitions> 

The first thing you see in a WSDL file is all the namespace declarations. The targetNamespace attribute is the namespace that was added in the Namespace parameter of the WebService attribute. After the namespace declarations is the types element, which will be filled in with the schema definitions for the Web Service method names and their associated parameter names and types. Finally, the service element holds general information about the Web Service, and it is here where you see the Name of the Web service along with its Description , which were both supplied as parameters to the WebService attribute.