Creating Web Services

Web Services are programs that enable a client program to run a task on the server without needing a visual front end. For example, suppose you created a function for converting currency from one country to another. Users may reach these functions in one of two ways. You could add a Web Form to your application that lets users visually enter an amount, the origin and destination countries , and then press a button named Convert that displays the conversion results.

Another possibility is to offer a Web Service. A Web Service doesn't have a visual front end. It is a program that listens for requests to a function, such as the Convert function. Companies then write programs with their own visual front end that interact with your Web Service. These programs communicate through the Internet with your Web Service and invoke your conversion function, passing you all the parameters you need; your Web Service then transmits the answer through the Internet. A Web Service gives the illusion that the client is simply making a method call; it's just that the method call happens through the Internet.

To create a Web Service:

1. Run VS.NET.

2. Select File > New Project from the menu bar.

3. Click the ASP.NET Web Service icon from the New Project dialog ( Figure 13.13 ).

   Figure 13.13. A Web Service is conceptually equivalent to having a DLL running remotely on a Web server. It doesn't provide visual elements, only functions.

   

4. Enter a name for the Web Service in the Location field and press OK. For example: CurrencyService .

5. Right-click on the Service1.asmx file (the wizard generated this file) in the Solution Explorer window, and select Properties.

6. Change the File Name in the Properties. For example: CurrencyConverter.asmx ( Figure 13.14 ).

   Figure 13.14. The extension .asmx is very important because that is the way ASP.NET knows to treat the file as a Web Service.

   

7. Right-click on the newly named file on the Solution Explorer window and select View Code.

8. Change the class name from Service1 to something more meaningful like CurrencyConverter . Don't forget to rename the constructor to match the class name ( Figure 13.15 ).

   Figure 13.15 The easiest way to write a Web Service is to write a public class that is derived from System.Web.Services.WebService. Deriving from WebService gives the class access to the ASP.NET intrinsic objects, like Session and Application.

    using System; using System.Collections; using System.ComponentModel; using System.Data; using System.Diagnostics; using System.Web; using System.Web.Services; namespace  CurrencyService  {    public class CurrencyConverter :    System.Web.Services.WebService    {       public  CurrencyConverter()  {          //CODEGEN: This call is required          //by the ASP .NET          //Web Services Designer          InitializeComponent();       }    } } 

9. Add a public function to the class that you want other programs to invoke through the Web. In front of the method declaration add the [WebMethod] attribute ( Figure 13.16 ). For example: [WebMethod] public decimal Convert(decimal original, string srcCountry, string dstCountry) .

   Figure 13.16 The WebMethod attribute tells ASP.NET that the method should get exposed through the Internet. This attribute also has other properties that are useful, for example: Description, EnableSession, etc.

    using System; using System.Collections; using System.ComponentModel; using System.Data; using System.Diagnostics; using System.Web; using System.Web.Services; namespace CurrencyService {    public class CurrencyConverter :    System.Web.Services.WebService    {       public CurrencyConverter()       {          //CODEGEN: This call is required          //by the ASP .NET          //Web Services Designer          InitializeComponent();       }  [WebMethod] public decimal Convert(   decimal original,   string srcCountry,   string dstCountry)   {   //of course, a full currency   //conversion function   //is beyond the scope of this   //book   return original - 1;   }  } } 

10. On top of the class declaration, type: [WebService(Namespace="http://www.josemojica.com/CurrencyServices/")] , where www.josemojica.com is any URL that you want to associate with your service. This attribute gives your classes a unique name to distinguish it from other companies' classes ( Figure 13.17 ).

    Figure 13.17 The WebService attribute lets you assign a unique namespace to the service. This is necessary to distinguish your service from other companies' services. The WebService attribute has other useful properties, like Description and Name for example.

     namespace CurrencyService {  [WebService(Namespace=   "http://www.josemojica.com/CurrencyServices/")]  public class CurrencyConverter :    System.Web.Services.WebService    {       public CurrencyConverter() 

11. Select Build > Build Solution from the menu bar to create the service.

Tips

• Web Service consumers communicate with the Web Service through XML, a text-based markup protocol. On top of XML we use a protocol called SOAP (Simple Object Access Protocol). SOAP is a specification that describes how to format XML to make a method call and receive a result ( Figure 13.18 ).

  Figure 13.18 SOAP is a text-based protocol on top of XML for making method calls through the Internet. If you notice, the parameters are being sent in literal form; the tags, original, srcCountry, dstCountry dictate the parameters the values are for, and the first element in the soap:Body is the name of the function we want to invoke: Convert.

   <?xml version="1.0" encoding="utf-8"?> <soap:Envelope ...>      <soap:Body>            <  Convert  ...>                 <  original  >5.25<  /original  >                 <  srcCountry  >USA<  /srcCountry  >                 <  dstCountry  >CAN<  /dstCountry  >            </  Convert  >      </soap:Body> </soap:Envelope> 

• A client can get information about a Web Service by entering http://www.josemojica.com/CurrencyService/CurrencyConverter.asmx , where www.josemojica.com is the URL to the server hosting the service, CurrencyService is the name of the project (or, more exactly, the name of the virtual directory that VS.NET creates for you) and CurrencyConverter.asmx is the name you assigned to the file with the Web Service class. When a client accesses the Web Service directly through the browser they will see a help page telling them how a program can talk to the Web Service ( Figure 13.19 ). You can change the look of this page by modifying the configuration file and adding the code in Figure 13.20 . Myhelp.aspx is a file you create. When a client tries to access the Web Service the runtime will call this page for you.

  Figure 13.19. The method Convert is meant to be invoked via SOAP (other mechanisms are possible, but normally SOAP is used). If you enter the name of the file directly, the Web Service generates a help page that lets you test the Web Service.

  

  Figure 13.20 If you don't want to display the usual help page you can create your own, and change it in the Web Service's configuration file web.config .

   <?xml version="1.0" encoding="utf-8" ?> <configuration>      <system.web>  <webServices>   <wsdlHelpGenerator href="myhelp.aspx" />   </webServices>