.NET Web Services Basics

A Web service is a software component stored on one machine that can be accessed by an application (or other software component) on another machine over a network. The machine on which the Web service resides is referred to as a remote machine. The application (i.e., the client) that accesses the Web service sends a method call over a network to the remote machine, which processes the call and returns a response over the network to the application. This kind of distributed computing benefits various systems. For example, an application without direct access to certain data on another system might be able to retrieve this data via a Web service. Similarly, an application lacking the processing power necessary to perform specific computations could use a Web service to take advantage of another system's superior resources.

A Web service is typically implemented as a class. In previous chapters, we included a class in a project either by defining the class in the project or by adding a reference to a compiled DLL. All the pieces of an application resided on one machine. When a client uses a Web service, the class (and its compiled DLL) is stored on a remote machinea compiled version of the Web service class is not placed in the current application's directory. We discuss what happens shortly.

Requests to and responses from Web services created with Visual Web Developer are typically transmitted via SOAP. So any client capable of generating and processing SOAP messages can interact with a Web service, regardless of the language in which the Web service is written. We say more about SOAP in Section 22.3.

It is possible for Web services to limit access to authorized clients. See the Web Resources at the end of the chapter for links to information on standard mechanisms and protocols addressing Web service security concerns.

Web services have important implications for business-to-business (B2B) transactions. They enable businesses to conduct transactions via standardized, widely available Web services rather than relying on proprietary applications. Web services and SOAP are platform and language independent, so companies can collaborate via Web services without worrying about the compatibility of their hardware, software and communications technologies. Companies such as Amazon, Google, eBay and many others are using Web services to their advantage. To read case studies of Web services used in business, visit msdn.microsoft.com/webservices/understanding/casestudies/default.aspx.

22.2.1. Creating a Web Service in Visual Web Developer

To create a Web service in Visual Web Developer, you first create a project of type ASP.NET Web Service. Visual Web Developer then generates the following:

• files to contain the Web service code (which implements the Web service)
• an ASMX file (which provides access to the Web service)
• a DISCO file (which potential clients use to discover the Web service)

Figure 22.1 displays the files that comprise a Web service. When you create an ASP.NET Web Service application in Visual Web Developer, the IDE typically generates several additional files. We show only those files that are specific to Web services applications. We discuss these files in Section 22.2.2.

Figure 22.1. Web service components.

(This item is displayed on page 1167 in the print version)

Visual Web Developer generates code files for the Web service class and any other code that is part of the Web service implementation. In the Web service class, you define the methods that your Web service makes available to client applications. Like ASP.NET Web applications, ASP.NET Web services can be tested using Visual Web Developer's built-in test server. However, to make an ASP.NET Web service publicly accessible to clients outside Visual Web Developer, you must deploy the Web service to a Web server such as an Internet Information Services (IIS) Web server.

Methods in a Web service are invoked through a Remote Procedure Call (RPC). These methods, which are marked with the WebMethod attribute, are often referred to as Web service methods or simply Web methodswe refer to them as Web methods from this point forward. Declaring a method with attribute WebMethod makes the method accessible to other classes through RPCs and is known as exposing a Web method. We discuss the details of exposing Web methods in Section 22.4.

22.2.2. Discovering Web Services

Once you implement a Web service, compile it and deploy it on a Web server (discussed in Section 22.4), a client application can consume (i.e., use) the Web service. However, clients must be able to find the Web service and learn about its capabilities. Discovery of Web services (DISCO) is a Microsoft-specific technology used to locate Web services on a server. Four types of DISCO files facilitate the discovery process: .disco files, .vsdisco files, .discomap files and .map files.

DISCO files consist of XML markup that describes for clients the location of Web services. A .disco file is accessed via a Web service's ASMX page and contains markup specifying references to the documents that define various Web services. The resulting data that is returned from accessing a .disco file is placed in the .discomap file.

A .vsdisco file is placed in a Web service's application directory and behaves in a slightly different manner. When a potential client requests a .vsdisco file, XML markup describing the locations of Web services is generated dynamically, then returned to the client. First, the .NET Framework searches for Web services in the directory in which the .vsdisco file is located, as well as that directory's subdirectories. The .NET Framework then generates XML (using the same syntax as that of a .disco file) that contains references to all the Web services found in this search.

Note that a .vsdisco file does not store the markup generated in response to a request. Instead, the .vsdisco file on disk contains configuration settings that specify the .vsdisco file's behavior. For example, developers can specify in the .vsdisco file certain directories that should not be searched when a client requests a .vsdisco file. Although a developer can open a .vsdisco file in a text editor and examine its contents, this is rarely necessarya .vsdisco file is intended to be requested (i.e., viewed in a browser) by clients over the Web. Every time this occurs, new markup is generated and displayed.

Using .vsdisco files benefits developers in several ways. These files contain only a small amount of data and provide up-to-date information about a server's available Web services. However, .vsdisco files generate more overhead (i.e., require more processing) than .disco files do, because a search must be performed every time a .vsdisco file is accessed. Thus, some developers find it more beneficial to update .disco files manually. Many systems use both types of files. As we discuss shortly, Web services created using ASP.NET contain the functionality to generate a .disco file when it is requested. This .disco file contains references only to files in the current Web service. Thus, a developer typically places a .vsdisco file at the root of a server; when accessed, this file locates the .disco files for Web services anywhere on the system and uses the markup found in these .disco files to return information about the entire system.

22.2.3. Determining a Web Service's Functionality

After locating a Web service, the client must determine the Web service's functionality and how to use it. For this purpose, Web services normally contain a service description. This is an XML document that conforms to the Web Service Description Language (WSDL)an XML vocabulary that defines the methods a Web service makes available and how clients interact with them. The WSDL document also specifies lower-level information that clients might need, such as the required formats for requests and responses.

WSDL documents are not meant to be read by developers; rather, WSDL documents are meant to be read by applications, so they know how to interact with the Web services described in the documents. Visual Web Developer generates an ASMX file when a Web service is constructed. Files with the .asmx filename extension are ASP.NET Web service files and are executed by ASP.NET on a Web server (e.g., IIS). When viewed in a Web browser, an ASMX file presents Web method descriptions and links to test pages that allow users to execute sample calls to these methods. We explain these test pages in greater detail later in this section. The ASMX file also specifies the Web service's implementation class, and optionally the code-behind file in which the Web service is defined and the assemlies referenced by the Web service. When the Web server receives a request for the Web service, it accesses the ASMX file, which, in turn, invokes the Web service implementation. To view more technical information about the Web service, developers can access the WSDL file (which is generated by ASP.NET). We show how to do this shortly.

The ASMX page in Fig. 22.2 displays information about the HugeInteger Web service that we create in Section 22.4. This Web service is designed to perform calculations with integers that contain a maximum of 100 digits. Most programming languages cannot easily perform calculations using integers this large. The Web service provides client applications with methods that take two "huge integers" and determine their sum, their difference, which one is larger or smaller and whether the two numbers are equal. Note that the top of the page provides a link to the Web service's Service Description. ASP.NET generates the WSDL service description from the code you write to define the Web service. Client programs use a Web service's service description to validate Web method calls when the client programs are compiled.

Figure 22.2. ASMX file rendered in a Web browser.

(This item is displayed on page 1169 in the print version)

ASP.NET generates WSDL information dynamically rather than creating an actual WSDL file. If a client requests the Web service's WSDL description (either by appending ?WSDL to the ASMX file's URL or by clicking the Service Description link), ASP.NET generates the WSDL description, then returns it to the client for display in the Web browser.

Generating the WSDL description dynamically ensures that clients receive the most current information about the Web service. It is common for an XML document (such as a WSDL description) to be created dynamically and not saved to disk.

When a user clicks the Service Description link at the top of the ASMX page in Fig. 22.2, the browser displays the generated WSDL document containing the service description for our HugeInteger Web service (Fig. 22.3).

Figure 22.3. Service description for our HugeInteger Web service.

(This item is displayed on page 1170 in the print version)

22.2.4. Testing a Web Service's Methods

Below the Service Description link, the ASMX page shown in Fig. 22.2 lists the methods that the Web service offers. Clicking any method name requests a test page that describes the method (Fig. 22.4). The test page allows users to test the method by entering parameter values and clicking the Invoke button. (We discuss the process of testing a Web method shortly.) Below the Invoke button, the page displays sample request-and-response messages using SOAP and HTTP POST. These protocols are two options for sending and receiving messages in Web services. The protocol that transmits request-and-response messages is also known as the Web service's wire format or wire protocol, because it defines how information is sent "along the wire." SOAP is the more commonly used wire format, because SOAP messages can be sent using several transport protocols, whereas HTTP POST must use HTTP. When you test a Web service via an ASMX page (as in Fig. 22.4), the ASMX page uses HTTP POST to test the Web service methods. Later in this chapter, when we use Web services in our C# programs, we employ SOAPthe default protocol for .NET Web services.

Figure 22.4. Invoking a Web method from a Web browser.

(This item is displayed on page 1170 in the print version)

Figure 22.4 depicts the test page for the HugeInteger Web method Bigger. From this page, users can test the method by entering values in the first: and second: fields, then clicking Invoke. The method executes, and a new Web browser window opens, displaying an XML document that contains the result (Fig. 22.5).

Figure 22.5. Results of invoking a Web method from a Web browser.

22.2.5. Building a Client to Use a Web Service

Now that we have discussed the different files that comprise a .NET Web service, let's examine the parts of a .NET Web service client (Fig. 22.6). A .NET client can be any type of .NET application, such as a Windows application, a console application or a Web application. You can enable a client application to consume a Web service by adding a Web reference to the client. This process adds files to the client application that allow the client to access the Web service. This section discusses Visual C# 2005, but the discussion also applies to Visual Web Developer.

Figure 22.6. .NET Web service client after a Web reference has been added.

To add a Web reference in Visual C# 2005, right click the project name in the Solution Explorer and select Add Web Reference.... In the resulting dialog, specify the Web service to consume. Visual C# 2005 then adds an appropriate Web reference to the client application. We demonstrate adding Web references in more detail in Section 22.4.

When you specify the Web service you want to consume, Visual C# 2005 accesses the Web service's WSDL information and copies it into a WSDL file that is stored in the client project's Web References folder. This file is visible when you instruct Visual C# 2005 to Show All Files. [Note: A copy of the WSDL file provides the client application with local access to the Web service's description. To ensure that the WSDL file is up-to-date, Visual C# 2005 provides an Update Web Reference option (available by right clicking the Web reference in the Solution Explorer), which updates the files in the Web References folder.] The WSDL information is used to create a proxy class, which handles all the "plumbing" required for Web method calls (i.e., the networking details and the formation of SOAP messages). Whenever the client application calls a Web method, the application actually calls a corresponding method in the proxy class. This method has the same name and parameters as the Web method that is being called, but formats the call to be sent as a request in a SOAP message. The Web service receives this request as a SOAP message, executes the method call and sends back the result as another SOAP message. When the client application receives the SOAP message containing the response, the proxy class deserializes it and returns the results as the return value of the Web method that was called. Figure 22.7 depicts the interactions among the client code, proxy class and Web service.

Figure 22.7. Interaction between a Web service client and a Web service.

The .NET environment hides most of these details from you. Many aspects of Web service creation and consumptionsuch as generating WSDL files, proxy classes and DISCO filesare handled by Visual Web Developer, Visual C# 2005 and ASP.NET. Although developers are relieved of the tedious process of creating these files, they can still modify the files if necessary. This is required only when developing advanced Web servicesnone of our examples require modifications to these files.