Click here to Skip to main content
15,860,943 members
Articles / Web Development / ASP.NET
Article

Externalizing Web Service Documentation

Rate me:
Please Sign up or sign in to vote.
4.63/5 (11 votes)
6 Oct 20044 min read 67.5K   1.3K   24   9
Enable .NET to display Web Service documentation stored in an XML file.

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
<?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.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
United Kingdom United Kingdom
Development Manager at Esendex the SMS service provider.

Comments and Discussions

 
QuestionExternailizing documentation for WCF Services Pin
rduffy14-Aug-07 9:05
rduffy14-Aug-07 9:05 
AnswerRe: Externailizing documentation for WCF Services Pin
BrandonWaskiewicz14-Sep-07 3:49
BrandonWaskiewicz14-Sep-07 3:49 
GeneralRe: Externailizing documentation for WCF Services Pin
Marc Scheuner12-Mar-09 4:04
professionalMarc Scheuner12-Mar-09 4:04 
GeneralModification Pin
fintanv18-Sep-06 3:58
fintanv18-Sep-06 3:58 
GeneralRe: Modification Pin
fintanv18-Sep-06 8:58
fintanv18-Sep-06 8:58 
QuestionHTML is escaped Pin
please please not another alias18-May-06 6:54
please please not another alias18-May-06 6:54 
Great article - thank you. If you could give me pointers as to what I'm doing wrong. All the generated documentation is HTML escaped, displaying HTML tag content with no formating.

Mark Macaulay
markm@tightwire.com
AnswerRe: HTML is escaped Pin
please please not another alias18-May-06 7:20
please please not another alias18-May-06 7:20 
JokeWe used your work! Pin
Willem Fourie3-Apr-06 4:12
Willem Fourie3-Apr-06 4:12 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.