Building Web Services Using ASP.NET

ASP.NET makes it easy to build Web services because it provides a special project type and targeted framework classes for constructing and implementing Web service methods . VS .NET provides even more productivity gains because it handles most of the complex infrastructure issues for you that are required to communicate with the Web service. For example, VS .NET will automatically generate a proxy class from the Web service's WSDL document. Recall that a proxy class enables managed code to call a Web service much like a standard component, without directly assembling and interpreting SOAP request and response envelopes. VS .NET automatically generates a proxy class when you add a Web reference to the Web service directly from the consumer application.

Web service projects are a specialized type of ASP.NET project. Although you can build Web services without ASP.NET and VS .NET, we do not discuss this approach because the productivity benefits are too powerful to ignore. The entry point file for the Web service ends with an .asmx extension and contains the @ WebService directive with attributes that describe the code-behind assembly. For example:

 <%@ WebService Language="vb" Codebehind="wsNorthwind.asmx.vb"          Class="WebService6A.Northwind" %> 

The Web service's code-behind assembly class should derive from the WebService base class, which also provides access to the ASP.NET intrinsic objects. The WebService class is a member of the System.Web.Services namespace, which also provides the WebServiceAttribute and WebMethodAttribute classes. These classes provide members for exposing assembly functions as callable Web service methods. Table 6-1 summarizes the important members of this namespace.

Table 6-1: Important Members of the System.Web.Services Namespace

MEMBER	DESCRIPTION
WebServiceAttribute	Sets and retrieves descriptive properties for a Web service assembly class, including the following: Namespace : The default XML namespace to which the Web service belongs. The namespace is the first part of the XML qualified name for the Web service. Name : The name of the Web service. The name is the second part of the XML qualified name for the Web service. The name displays in the Service Description page for the Web service. Description : A description of the Web service. The description displays in the Service Description page for the Web service.
WebMethodAttribute	Exposes an assembly function as a callable Web service method. It provides properties for controlling the behavior of the Web method, including the following: MessageName : The name of the Web method used in messages to and from the Web service method. Description : A description of the Web method. CacheDuration : The number of seconds to cache response output. This form of output caching varies by parameter ”in other words, a non-cached response is generated if the input parameter values for the current response vary from the cached response. TransactionOption : Sets the level of transaction support by the Web method. Note, Web methods may initiate new root transactions, but they may not participate in existing ones. EnableSession : Indicates whether the Web method enables session state management.
WebService	Sets the base class from which a Web service assembly class should derive. This base class is optional, but it does provide access to the ASP.NET intrinsic objects. This includes the User object, which may be used for authentication purposes.
WebServiceBindingAttribute	Attaches a Web method to an XML binding, which is a collection of related Web methods, similar to an interface.

The programming syntax for using these namespace classes is different from the traditional code-behind approach of creating object instances. Instead, the classes are referenced as annotated attributes directly on the Web service assembly methods. The following code, which uses wire frame code for a Web service with one method, illustrates this:

 Imports System.Data Imports System.Web.Services <WebService(Namespace:="http://tempuri.org/")> _ Public Class Northwind     Inherits System.Web.Services.WebService     <WebMethod(Description:="Generates a DataSet of Employee Sales By Date", _              CacheDuration:=60)> _     Public Function GetEmployeeSales(ByVal BeginningDate As Date, _              ByVal EndingDate As Date) As DataSet     End Function End Class 

Of course, the beauty of the .NET Framework is that its classes are available to any .NET project type, including ASP.NET Web services. So, while coding a Web service, you can continue to leverage useful namespaces such as System.Data for accessing data and System.Xml for manipulating XML.

Generating a Proxy Class Using WSDL

Web services include associated Service Description files that describe the interface that the Web service supports. VS .NET uses the WSDL file to automatically generate a proxy class for accessing the Web service. This proxy class assembles the requests and responses in the correct format and enables the consumer code to focus on the input and output values, without worrying about formats.

You can view the WSDL code directly when you navigate directly to a Web service *.asmx file in the browser and append the ?WSDL query string to the Uniform Resource Locator (URL) entry. Alternatively, you can navigate to the default Service Description file that VS .NET provides, as shown in Figure 6-1.

Figure 6-1: Default Service Description File

You can click any of the Web method hyperlinks to execute the method and view the output directly in the browser, as shown in Figure 6-2.

Figure 6-2: Using the default Service Description file

The response will be returned directly to the browser window as a SOAP response envelope because this Web service uses SOAP as its communication protocol. The following code shows a small section of the response XML:

 <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"     xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1"> <NewDataSet xmlns="">          <Table diffgr:id="Table1" msdata:rowOrder="0">                   <Country>UK</Country>                   <LastName>Suyama</LastName>                   <FirstName>Michael</FirstName>                   <ShippedDate>1996-07-10T00:00:00.0000000-07:00</ShippedDate>                   <OrderID>10249</OrderID>                   <SaleAmount>1863.4</SaleAmount>     </Table> </NewDataSet> </diffgr:diffgram> 

You create proxy classes using VS .NET simply by adding a Web reference to the ASP.NET application that will consume the Web service. We outline the exact steps later in the "Consuming the Web Service" section so as not to get distracted from our conceptual discussion. For now, let's focus on the result. Once the consumer application adds the Web reference, you can switch to its Class View to review the proxy class interface. Figure 6-3 shows the consumer application's Class View once a Web reference has been set to the Northwind Web service on the localhost server.

Figure 6-3: Web service proxy class interface

Notice that the proxy class automatically creates three proxy methods for every Web method. One proxy method is for accessing the Web method synchronously. For example, the GetCustomerList() proxy method is for synchronous access to the GetCustomerList() Web method. In addition, the proxy class contains a Begin[MethodName] and End[MethodName] pair that handles asynchronous access to the GetCustomerList() Web method. We will see examples of each later in the chapter.

Web Service-Supported Data Types

Web services exist to exchange data, which poses a challenge because supported data types may vary between platforms. Microsoft-based Web services support a number of the data types that are outlined in the XML Schema Definition Language (XSD). This includes a mix of primitive and simple data types. Table 6-2 summarizes the supported XSD data types and their equivalent .NET Framework data types.

Table 6-2: Web Service-Supported Data Types

XSD DATA TYPE	.NET FRAMEWORK DATA TYPE
boolean	Boolean
Byte	Byte
decimal	Decimal
enumeration	Enum
Float	Single
Short	Int16 (unsigned version also available: UInt16)
Int	Int32 (unsigned version also available: UInt32)
Long	Int64 (unsigned version also available: UInt64)
String	String
timeInstant	DateTime
Qname	XmlQualifiedName (a .NET class that represents an XML name and its reference namespace)

Microsoft-based Web services support additional complex data types such as the ADO.NET DataSet, which serializes to XML and can be represented in a SOAP response. In fact, the DataSet is represented in XML using a combination of several XSD-standard data types, including the schema and sequence data types. Data type construction is beyond the scope of our discussion, but suffice it to say that Web services may support any data type, including both customer-defined and user-defined data types, as long as they serialize to XML and can be described in an XML specification document.