Transport Protocols and Bindings

Web Service Documentation

The ASP.NET runtime includes a set of services that provide documentation for your Web service. The ASP.NET runtime uses reflection to generate two types of documentation: human-readable documentation, and documentation used by client applications to interact with the Web service.

You can reach HTML-based documentation by entering the URL of the Web service into a Web browser. Both the WebService and WebMethod attributes expose a Description property. The following example is a modified version of the Securities Web service I created earlier:

using System; using System.Web.Services; namespace BrokerageFirm {     [WebService(Description="This Web service provides services      related to securities.")]     public class Securities : WebService     {         [WebMethod(Description="Used to obtain a real-time quote          for a given security.")]         public double InstantQuote(string symbol)         {             double price = 0;             switch(symbol)             {                 case "MSFT":                     price = 197.75;                     break;                 case "SUNW":                     price = 2.50;                     break;                 case "ORCL":                     price = 2.25;                     break;             }             return price;         }     } }

The HTML-based documentation that is automatically generated for the Securities Web service is shown here:

The Web page lists the method exposed by the Web service, InstantQuote. The Web page also provides a recommendation to set the default namespace of the Web service and provides code examples for C# and Visual Basic .NET. I cover how to set the default namespace later in the chapter.

If you click on a particular method, you see documentation for that particular method, as shown here:

The documentation for the InstantQuote method shows the parameter that is expected to be passed. The text set by the WebMethod attribute's Description property is also displayed. The Web page also provides an example template for how the parameters should be encoded within SOAP, HTTP GET, and HTTP POST messages.

If the parameters are simple, as in the case of the InstantQuote method, the generated documentation for the method also includes a test harness for posting data via HTTP GET to the Web service. This simple test harness can come in handy for testing the logic within the Web service. It also serves as the default client when you debug your Web service in Visual Studio .NET.

The documentation automatically generated by ASP.NET serves as a good starting point. However, you should consider expanding it to include more descriptive information about the Web service. You should also consider showing a few examples, including the contents of the request and response messages—especially for Web services that will be publicly exposed via the Internet.

You can configure ASP.NET to display your custom documentation when a user navigates to the .asmx file by setting the wsdlHelpGenerator element within the configuration file. The HTML documentation for the Securities Web service displayed in the preceding graphic is generated by DefaultWsdlHelpGenerator.aspx, which is located in the C:\WINNT\Microsoft.NET\Framework\version\CONFIG directory. The entry within the machine.config file for the default HTML documentation is as follows:

<configuration>   <!-- Portions of the configuration file removed for clarity -->   <system.web>     <webServices>       <wsdlHelpGenerator href="DefaultWsdlHelpGenerator.aspx" />     </webServices>   </system.web> </configuration>

Despite the wsdl prefix, the wsdlHelpGenerator element is used to set the file that will display the HTML-based documentation, not the WSDL documentation. The href attribute specifies the name of the file that will be used to display the documentation. If the filename is fully qualified, it should contain the file path to the document, not the document's URL.

The ASP.NET runtime also generates documentation about a Web service in a format that can be programmatically consumed by clients. The ASP.NET runtime automatically generates a WSDL document that describes the Web service. You can access this by passing the value wsdl to the .asmx file within the query string. The following is a portion of the WSDL generated for the Securities Web service:

The WSDL document describes the Web service and can be used by the ASP.NET platform to create proxies for calling Web methods. I discuss how to create and use Web service proxies in the section titled “Using the WSDL Utility to Generate Proxy Code” later in this chapter. I discussed WSDL in more detail back in Chapter 5.

The autogeneration of both the HTML and the WSDL documentation is enabled by default within the machine.config file. You can disable autogeneration of documentation for the entire machine by modifying the machine.config file, or you can disable it for an individual Web directory by modifying the web.config file. The following example disables the documentation support:

<configuration>   <!-- Portions of the configuration file removed for clarity -->   <system.web>     <webServices>         <protocols>           <remove name="Documentation"/>          </protocols>     </webServices>   </system.web> </configuration>

Unfortunately, there is no way to disable the HTML and WSDL documentation separately.