Externalizing Web Service Documentation

• Download source files - 14.4 Kb
• Download demo project - 21.7 Kb

Introduction

Visual Studio .NET provides us with a simple mechanism for adding documentation to Web Services through the use of attributes. The WebService attribute that is applied to your class has a property named Description which can be used to give an overview of its purpose. Likewise, the WebMethod attribute that is applied to your methods also has a Description property.

There are a few limitations to documenting your Web Services in this way. Firstly, it becomes unwieldy when you need to provide any level of detail. For example, adding a table of parameters and values would mean lines of concatenated strings containing hard-to-read escaped HTML. Secondly, this approach doesn't lend itself well to having translators, technical writers, and editors working on the documentation as they need access to the code. Thirdly, the page has a fixed style that might not fit in with your corporate image.

This article tackles the above problems by moving the documentation and stylesheet out of the implementation and into standalone files.

Background

By default, the documentation for all Web Services is generated by a page named DefaultWsdlHelpGenerator.aspx located in the .NET Framework configuration directory (usually named C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\CONFIG).

When DefaultWsdlHelpGenerator.aspx loads, its Page.Context property is populated with a ServiceDescriptionCollection that programmatically describes the current web service.

Each item within the ServiceDescriptionCollection is a ServiceDescription which has Documentation property. This value is automatically set from the value of the Description property within your Web Service class' WebService attribute. DefaultWsdlHelpGenerator.aspx outputs this value as the description for your Web Service.

Each ServiceDescription contains a collection of Ports, which in turn contains a collection of Operations. Each Operation maps to a method in your class that is marked with the WebMethod attribute. The Operation has a Documentation property which is set if the Description property is set on the WebMethod attribute. DefaultWsdlHelpGenerator.aspx outputs these values as descriptions for each operation on your Web Service.

The proposed solution

Microsoft provides us with a way to override the default documentation generation on a per-machine or per-application basis. The key lies in editing web.config as follows, where MyServiceDescriptionGenerator.aspx is the name of the page you want to use for documentation.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.web>
    <webServices>
      <wsdlHelpGenerator href="MyServiceDescriptionGenerator.aspx"/>
    </webServices>
  </system.web>
</configuration>

Modifying web.config to use a different aspx file is simple enough, but things are complicated by the fact that this file is also responsible for generating example code for use with the SOAP and HTTP protocols. As a result, we can't simply replace the file with the HTML required to document web service as we'd no longer have a mechanism to provide examples to our Web Service consumers.

This solution takes a copy of the existing DefaultWsdlHelpGenerator.aspx and makes the changes required to externalize the documentation and style sheet. The changes are intended to be as unobtrusive as possible so newer versions of DefaultWsdlHelpGenerator.aspx can be brought on board more easily.

The changes are summarized as follows:

• Externalize the style sheet.
• Move the code within DefaultWsdlHelpGenerator.aspx into a code behind file.
• Add member variables named serviceDocumentation and operationDocumentationCollection to hold the new documentation.
• Create a new method named LoadDocumentation to load the external documentation.
• Modify Page_Load to call LoadDocumentation and to update the default documentation with the new documentation.

The bulk of the new code lives within LoadDocumentation. This method attempts to locate a file with the same name as the Web Service suffixed with Documentation.xml. The example project uses the Esendex SMS Web Service, which is implemented in the file SendService.asmx and has a corresponding file named SendServiceDocumentation.xml. If the external documentation file is not found, the method returns, and allows processing to continue on to use the default documentation provided by the framework.

Using the code

To use the new documentation generator in your code, do the following:

• Add the files ServiceDescriptionGenerator.aspx and WebServiceDocumentation.css to your project.
• Change your application's web.config to reference the new service description generator, as described above and shown in the sample project.
• Create a new XML file containing your documentation. The file should be named like your WebService.asmx file, but with a suffix of Documentation.aspx, for example: WebServiceDocumentation.aspx.