C# ПІДРУЧНИКИ / c# / Hungry Minds - ASP.NET Bible VB.NET & C#

When the test page is displayed, click the CTemp method link once again and enter test values into the form. Click the Invoke button, and you should see the XML-formatted results returned to a new browser window (identical to what happened when testing with the HTTP -GET protocol).

The only difference between the two methods is revealed in the URL that is displayed in the browser Address bar in the results window. Note that the method name is the last segment of the URL and no query string arguments are visible.

Debugging the Web Service

Sometimes, testing your Web service as outlined in the last section will reveal flaws in your implementation or other unexpected results. If this occurs, you may need to debug your Web service. For those of you who have experience in trying to debug priorgeneration ASP applications, you will find that the .NET Framework SDK and ASP.NET have much-improved support for testing and debugging your Web service applications.

To illustrate the general debugging process, we will set a breakpoint in our CTemp method code using the .NET SDK debugger so that we can examine what happens during a call to our Web service method.

The .NET SDK debugger, named Dbgclr.exe, is located in the .NET SDK installation folder, which is typically found at Program Files\Microsoft.NET\ FrameworkSDK\ GuiDebug.

Enabling Debug mode for ASP.NET Web services

Inline ASP.NET Web service implementations rely on the ASP.NET runtime to dynamically compile the Web service at run time. To generate the symbolic debugging information required to debug a Web service, we need to instruct the ASP.NET runtime to compile the application with this additional information.

To configure a Web service to be compiled with symbols, you must include a debug attribute in the <compilation> section of the Web.config file. The following example illustrates a complete Web.config file with the required compilation tag and debug attribute:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

<system.web>

<compilation debug="true"/>

</system.web>

</configuration>

If you do not already have a Web.config file in the CTemp Web service virtual directory, create one with a text editor, include the previous text, and save it. Otherwise, you can simply add the compilation tag to any existing Web.config file.

Starting the ASP.NET runtime

After you have enabled generation of debug symbols for your Web service, you need to request the Web service entry point file from within a Web browser window. This ensures that the ASP.NET runtime process (aspnet_wp.exe) is started and running. This is necessary because the debugger must be attached to this process to intercept the execution of your Web service code.

To start the ASP.NET runtime, open Internet Explorer and type the following URL into the Address bar:

http://localhost/ctemp/ctemp.asmx

This will activate the ASP.NET runtime and return the base your CTemp Web service to your browser window. Keep this documentation page for browser window around, because we will use it shortly to activate the debugging process.

Debugging the CTemp Web service

The .NET SDK debugger is a GUI debugging tool that, by default, can be found at Program Files\Microsoft.NET\FrameworkSDK\GuiDebug\dbgclr.exe. Starting the .NET debugger application displays the window shown in Figure 25-11.

Figure 25-11: .NET SDK Debugger window

Follow these steps to begin debugging your CTemp Web service:

1.Select File → Open → File. This displays the Open File dialog box.

2.Navigate to the inetpub\wwwroot\ctemp folder, select the CTemp.asmx file, and click the Open button. This loads the CTemp Web service code into the main debugger window.

3.Select Tools → Debug Processes. This displays the Processes dialog box, shown in Figure 25-12.

Figure 25-12: .NET Debugger Processes dialog box

4.Check the box labeled Show System Processes, if it is not already checked.

5.Select the aspnet_wp.exe entry from the list of processes and click the Attach button.

6.Click the Close button to close the Processes dialog box.

The .NET debugger is now configured to debug your Web service.

Up to this point, we have simply been preparing the debugging environment so that we can interact with the Web service during run time. You are now ready to set one or more breakpoints in your Web service code and activate the debugging session. We will cover how to do this in the next section.

Setting a breakpoint

To set a breakpoint in the Web service code, simply point your mouse to the left margin of the code window in the .NET debugger application and click the line on which you would like to set a breakpoint. For the purposes of our test, set a breakpoint at the first line of the CTemp method, as shown in Figure 25-13.

Figure 25-13: Setting a breakpoint

The .NET debugger represents a breakpoint using a red circle in the code margin adjacent to the appropriate line of code. You can toggle the breakpoint on and off by clicking in the code margin repeatedly. The .NET debugger also provides menu options to manage breakpoints and other debugger features.

Having set a breakpoint in our CTemp Web service code, let's begin the debugging session.

Testing Web service methods

To activate our Web service, we will use the testing capability built into the Web service documentation page we opened earlier in a Web browser window. This is the base documentation page for the Web service and displays, amongst other things, a link to the CTemp method (called "operations" in the page). Click the CTemp method link now to display the Web method test form.

The Web method test form displayed in your browser window contains text entry boxes for each of the input arguments defined by the CTemp method in the WSDL file. To test the functionality of the method, simply enter values in each of the input argument text boxes and click the Invoke button.

To continue with our example, enter the following argument values in the appropriate text boxes:

§Temperature: 32

§FromUnits: F

§ToUnits: C

After entering these values into the input boxes, click the Invoke button to execute the CTemp method. This action delivers the CTemp method request to the ASP.NET runtime. The runtime dynamically compiles the ASMX file with debugging symbols (if necessary) and then loads and executes the resulting code. This, in turn, causes the debugger to be activated.

Because we had previously set a breakpoint in our CTemp method code, the .NET debugger will be activated and halt execution at our breakpoint. If the Command window is not displayed, choose Debug → Windows → Immediate.

You are now ready to examine data within the method and perform other debugging operations. Let's take a quick look at how to examine program variables.

Examining program variables

You can use the Immediate window in Debug mode to quickly examine the values of variables in your Web service method. One of the first steps you will take when debugging new Web service methods is to examine the values of all input arguments.

Click your mouse in the Immediate window and type the following text:

? Temperature

Then press Enter. This causes the debugger to print the value of the input argument named Temperature. The result of these examinations is shown in Figure 25-14.

Figure 25-14: Examining input arguments

You can repeat this process to examine all the input arguments.

Resuming method execution

After you have examined program variables and performed the other actions necessary to debug your Web service, you can resume execution of the method call by choosing Debug → Continue in the .NET debugger window, or by pressing the F5 key.

When the method completes execution, a new browser window is loaded and displays the results of the method call, as shown in Figure 25-15.

Figure 25-15: Results window of successful method call

As mentioned previously, the Web form that is a part of the Web method documentation page uses the HTTP -GET request/response protocol to invoke the CTemp Web service method. This is evident when you examine the URL that appears in the Address bar of the browser window that displays the result of the method call. Note that the result format conforms to the sample HTTP -GET request/response protocol messages displayed in the Web method documentation page.

Summary

In this chapter, you learned the basics of building an ASP.NET Web service using the features and tools of the .NET Framework SDK, including how to test and debug the service during development.

Now that you have successfully built and tested your first Web service, you are ready to learn how to deploy your service to a production-quality Web server. We will explore how to do this in the next chapter.

Chapter 26: Deploying and Publishing Web

Services

Overview

In this chapter, you will learn how to deploy and publish a Web service. Deploying a Web service enables that Web service to execute on a specific host Web server, whereas publishing a Web service enables potential consumers to locate and interrogate the capabilities of the Web service before actually calling any methods of the service.

We will discuss what you need to do before deploying a Web service, the options available to you for deploying and publishing a Web service using .NET techniques, and the support built into Visual Studio .NET.

Deployment Preparation

Before you deploy a Web service, you must make sure that the Web service specifies a unique XML namespace. This name-space is used within the Web service WSDL document to uniquely identify the callable entry points of the service. As mentioned in Chapter 25, "Building a Web Service," the default Web service namespace is set to http://tempuri.org/ when you first build your Web service. Now that you are ready to deploy and publish your Web service, you must change this temporary namespace designator to a permanent value.

Web service namespaces

The namespace that you choose to identify your Web service must be unique. In general, it is recommended that you choose a namespace URI that is owned or otherwise under your control. Typically, using your Internet domain name as part of the Web service namespace will guarantee uniqueness and also more readily identify the owner of the Web service. Therefore, it is recommended that you use this technique to supply a namespace to all Web services that you make available for Internet consumption.

ASP.NET Web Services support a Namespace property as part of the WebService attribute used to identify the class that implements the functionality of the Web service. For example, the WebService attribute for the CTemp Web service looks like this:

VB.NET:

<%@ WebService Language="VB" Class="TempConverter" %>

Imports System

Imports System.Web.Services

<WebService(Namespace:="http://mydomain.com/ctemp/")>

Public Class TempConverter

' implementation

End Class

C#:

<%@ WebService Language="C#" Class="TempConverter" %>

using System;

using System.Web.Services;

[WebService(Namespace="http://mydomain.com/ctemp/")]

public class TempConverter : WebService{

// implementation

}

Changing the Web service namespace is even more important for ASP.NET Web Services, because a default namespace of http://tempuri.org/ is used. This, unfortunately, makes it even more likely that you will have namespace conflicts with other Web services, unless you change this default.

Setting the CTemp Web se rvice namespace

Before we deploy our CTemp Web service, we need to set the namespace to a permanent value. To do this, follow these steps:

1.Open the Ctemp.asmx file in your favorite text editor.

2.Add the WebService attribute along with the Namespace property (using the appropriate language syntax) and set it to the appropriate value.

The new class declaration should look as follows:

VB.NET:

<WebService(Namespace:="http://mydomain.com/ctemp/")> Public Class TempConverter

' implementation

End Class

C#:

[WebService(Namespace="http://mydomain.com/ctemp/")]

public class TempConverter : WebService{

// implementation

}

Save the changes you have made and use a Web browser to test your Web service. The base documentation page returned to your browser should no longer warn you about the temporary namespace URI. In addition, when you link to the CTemp method test page, you will also notice that the sample SOAP messages now refer to the namespace you specified as part of the SOAPAction header.

You are now ready to deploy your Web service!

Deploying Web Services

Deploying a Web service enables the service to execute on a target Web server. Generally speaking, the deployment process for a Web service involves copying the Web service entry point file (the ASMX file), the Web service assembly (if you are using code behind) along with any dependent assemblies (excluding the .NET Framework assemblies), and related support files (such as the Web service contract file and/or Web.config file) to an appropriately configured virtual directory file structure on the target Web server.

A sharp contrast from deploying previous-generation Windows applications, ASP.NET Web Services are typically easy to deploy and do not require the complicated registration of DLLs, copying to many different target folders, and so forth.

Files deployed with a Web service

Some ASP.NET Web Services may require no more than just the ASMX file. Others (such as those built with Visual Studio) may consist of many files, including the Web service entry point file (the ASMX file), the Global.asa application startup file, the Web.config application settings file, the .NET assembly that contains the implementation classes for the Web service (when using code behind), and any dependent assemblies that the Web service references (excluding the .NET Framework).

In the case of ASP.NET Web Services you build with the .NET Framework, you will usually copy all the files to the target Web server (unless you have created files during the development process that you are sure you do not need for production use). Our CTemp Web service only requires that you copy the ASMX file to the target Web server. ASP.NET Web Services built with Visual Studio typically include many more files, some of which are not necessary for execution on the target server. Table 26-1 summarizes the standard file structure for deploying a Web service built with Visual Studio.

Table 26-1: Files deployed with the CTemp Web service

Deployment using XCOPY

The DOS XCOPY command is perhaps the simplest method for deploying a Web service to a target Web server. However, as is the case with the Visual Studio Copy Project feature, XCOPY simply copies files from one location to another. It does not create or configure virtual directories for your Web service, nor does it register or configure any dependent assemblies outside of the .NET Framework.

You can type XCOPY /? at a command prompt to get help on the XCOPY command-line syntax and available options.

Publishing Web Services

Publishing a Web service enables potential consumers to locate and interrogate service descriptions that instruct the consumer on how to interact with the Web service. The process of locating and interrogating Web service descriptions is referred to as the discovery process.

The following are the two methods for enabling discovery of a Web service:

§DISCO

§UDDI

You may choose to use one or both of these methods based on the consumer audience you are trying to reach.

If your consumer population is fairly small (or well known), you could simply point them to the target Web server and deploy the DISCO file on this server. In this case, the consumers will invoke the discovery process against the URL of the target server and locate your Web service description. In this situation, you only need to deploy your DISCO documents to the proper server and inform the consumers of the URL to the server.

On the other hand, if your consumer population is relatively large or unknown (in which case it is impractical to provide them with a pointer to the target Web server where the service is located), you will need to provide a mechanism for the consumers to find where your DISCO and/or Web service descriptions are located, just as Web users utilize search engines to find Web pages. In this situation, you will need to publish your Web service through UDDI.

As mentioned in Chapter 22, "Introduction to Web Services," the DISCO document and the UDDI business registry provide the mechanisms to solve these issues. Let's explore how to use these technologies to enable potential consumers to locate the essential information they need in order to use your Web service.

Publishing with DISCO

As you may recall from our previous discussions regarding Web service discovery, consumers of Web services enact a discovery process to locate Web services. The discovery process searches for XML-encoded discovery documents that contain pointers to other resources that describe the Web service.

Encoding discovery documents in XML enables tools such as Visual Studio to programmatically discover the availability of Web services (if you know the URL to the server). This is how the Web Reference metaphor works in Visual Studio when you provide it with a specific discovery URL. For those of you not using Visual Studio, you can use the disco.exe tool that comes with the .NET Framework SDK to discover Web services.

Web service discovery via the Web Reference feature in Visual Studio or the disco.exe tool in the .NET Framework SDK is useful when a consumer knows the URL to the server hosting the Web service or the application virtual directory.