Building ASP.NET Web Services

Like ASP.NET Pages, ASP.NET Web services are compiled on their first request, and support a code- behind model, in which the code for the web service can reside in a pre-compiled .NET Assembly.

In this section, we'll discuss the programming model. Our emphasis will be on how to expose application logic as a web service, rather than upon the application logic itself.

Important

ASP.NET Web service files are simply source files (that are part of an ASP.NET application) with a .asmx file extension.

A Simple Web Service

Consider a simple class that calculates the value of an index in a Fibonacci series. A Fibonacci series is a series of numbers beginning with 0 and 1, in which the next number in the sequence is calculated by adding the previous two numbers. So, the third number in the sequence is 0 + 1 = 1, the fourth number is 1 + 1 = 2, and so on. The first seven numbers of the Fibonacci series are 0, 1, 1, 2, 3, 5, and 8. Let's implement this in code.

Fibonacci Application Logic

The following logic allows you to interact with a Fibonacci series. Using VB.NET, you could write:

  Public Class Fibonacci     Public Function GetSeqNumber (fibIndex As Integer) As Integer     If (fibIndex < 2) Then   Return fibIndex   End If     Dim FibArray(2) As Integer   Dim i As Integer     FibArray(0) = 0   FibArray(1) = 1     For i = 2 To fibIndex   FibArray(1) = FibArray(1) + FibArray(0)   FibArray(0) = FibArray(1) - FibArray(0)   Next     Return FibArray(1)   End Function   End Class  

Using C#, you could write:

  public class Fibonacci {     public int GetSeqNumber(int fibIndex){     if (fibIndex < 2)   return fibIndex;   int[] FibArray = {0,1};     for (int i = 1; i< fibIndex; i++){   FibArray[1] = FibArray[0] + FibArray[1];   FibArray[0] = FibArray[1] - FibArray[0];   }   return FibArray[1];   }   }  

Both these sections of code create a Fibonacci class with a single method, GetSeqNumber , that accepts a single parameter, fibIndex , of type Integer (or int in C#), and returns the value of the index in the Fibonacci series. The index into the series begins with 0. So, for example, GetSeqNumber(6) returns 8.

A two-element array is created and initialized with the first series values of 0 and 1. For these numbers in the series, the value is the same as the index number, and so we can just use that as a return value. If the fibIndex parameter is greater than 1, we iterate in a For Next (VB) or for loop (C#), performing the necessary math to calculate the current values. Finally, we return the requested element (the last value calculated in the loop) in the array.

This is simply application logic, and is no different from the type of application logic authored when building ASP.NET pages or components . However, there are some special considerations that you need to be aware of when designing application logic to be a web service, such as supported data types and behaviors specific to web services. We'll cover those later in the chapter.

Next, let's see what needs to be done to enable this simple application logic as a web service, using ASP.NET. You'd want another application to be able to easily call and use your Fibonacci class. The difference is that this Fibonacci class needs to be able to communicate using SOAP. Fortunately, ASP.NET helps to do that very easily.

Fibonacci ASP.NET Web Service

You can use ASP.NET to expose your application logic as a web service by simply adding attributes to your code. An attribute is declarative code that adds additional behavior (such as the ability to support SOAP) to the code without having to add new programmatic code that changes the behavior of the application logic. It sounds complicated, but it's really not.

There are several attributes that a web service makes use of. The most notable of them is the WebMethod attribute. The methods or properties that have this attribute are treated as web services. They can receive, process, and respond with XML messages. All of the internal serialization and deserialization (that is, how the data being sent back and forth as XML is represented) is handled internally.

Let's look at the Fibonacci code, reworked as an ASP.NET Web service: Using VB.NET, you would write:

  <%@ WebService class="Fibonacci"%>   Imports System.Web.Services   Public Class Fibonacci   <WebMethod> Public Function GetSeqNumber (fibIndex as Integer) as Integer  If (fibIndex < 2) Then          Return fibIndex       End If            Dim FibArray(2) as Integer       Dim i as Integer            FibArray(0) = 0       FibArray(1) = 1            For i = 2 To fibIndex          FibArray(1) = FibArray(1) + FibArray(0)          FibArray(0) = FibArray(1) - FibArray(0)       Next            Return FibArray(1)    End Function End Class 

Using C# you would write:

  <%@ WebService Language="C#" class="Fibonacci" %>   using System.Web.Services;   public class Fibonacci : WebService{   [WebMethod]  public int GetSeqNumber(int fibIndex){            if (fibIndex < 2)          return fibIndex;            int[] FibArray = {0,1};            for (int i = 1; i< fibIndex; i++){          FibArray[1] = FibArray[0] + FibArray[1];          FibArray[0] = FibArray[1] - FibArray[0];       }            return FibArray[1];    } } 

The application logic for both files remains identical. The difference is that the code now exists within an ASP.NET Web service source file ( Fibonacci_vb.asmx or Fibonacci_cs.asmx , depending on the language used and has some additional declarative code, such as the use of the WebMethod attribute. The details of these changes will be discussed in a moment, but first let's test the web service.

Testing the Web Service

The Fibonacci ASP.NET Web service code is now a functional web service. To test its functionality, you can use a browser and request the URL that is represented by the ASP.NET Web service file.

Note

A web service is not intended to service requests for web browsers. The web browser functionality shown is only for testing purposes, or design-time information. In the next chapter, we'll look at an IE 5.5 behavior that allows you to consume web services for rich browser clients .

To run the fibonacci_vb.asmx or fibonacci_cs.asmx ( the filename_cs and filename_vb naming convention has been eliminated in this chapter hence ), you must make it accessible through a web server, just as you would do for an ASP.NET page.

Once you've saved the code to a file on your web server, you can navigate to it with your browser. You should see the screen shown in Figure 19-2:

Figure 19-2:

ASP.NET provides an ASP.NET Web service Help file template. On receiving an HTTP GET request, the web service Help file template programmatically examines the code in the . asmx file (using reflection), and generates the UI. This includes details such as the class and method name . Later, you'll see how to get even more information out of this file. The UI also provides some handy ways of testing the functionality of the web service.

The template page that does this is called DefaultWsdlHelpGenerator.aspx , and can be found in the \WinNt\Microsoft.NET\Framework\[version] directory. As it's just an ASP.NET page, it can easily be customized for the application. You can, in fact, have custom Help file templates files for different ASP.NET applications.

The Service Description link in Figure 19-2 provides the WSDL (the XML contract for this web service). The WSDL for any ASP.NET Web service is available as [ webservice name ].asmx?WSDL : so in this case, you can access it as fibonacci.asmx?WSDL .

Note

We'll return to WSDL in the next chapter, where we discuss how to use the WSDL to build a proxy to use a web service.

The other link on the page names the GetSeqNumber method. This represents the method that marked as a WebMethod in the Fibonacci class. If you select this link, you will be presented with information about the GetSeqNumber method exposed as a web service, as shown in Figure 19-3:

Figure 19-3:

You can use the HTML form provided to pass values to the GetSeqNumber method. Enter a value for the parameter textbox and press the Invoke button to view the results.

Note

The .NET Framework 1.1 changed the behavior of how web services can be accessed through the browser. In .NET Framework 1.0, the default behavior was to allow any browser to perform an HTTP-POST or HTTP-GET for testing purposes. In .NET Framework 1.1, this behavior was changed to only allow for localhost . This new 1.1 behavior can be changed by modifying the configuration settings for web services.

Figure 19-4:

Figure 19-4 shows the XML returned from the GetSeqNumber method call. The element is named <int/> , and the return value is 8. Note that the value of fibIndex=6 is passed as an argument in the query string. You could change this argument's value directly, and the web service would return the appropriate result.

This isn't a SOAP return; it's another protocol type that ASP.NET Web services support: HTTP-GET. The web service help page generates a simple HTML form that makes a GET request to the Fibonacci.asmx file. When you build proxies to use the web service, the default protocol will be SOAP.

Let's take a closer look at the changes just made to the code in order to implement it as a web service.