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
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.
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.
ServiceDescription contains a collection of
Ports, which in turn contains a collection of
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.
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
operationDocumentationCollection to hold the new documentation.
- Create a new method named
LoadDocumentation to load the external documentation.
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.