This article describes the ASP.NET Documentation Tool, a utility that automates the documentation of ASP.NET web applications written in VB.NET or C#.

Programming languages such as Java and Perl contain their own code documentation utilities. When producing work for a client, these utilities take a lot of the hard work out of the mundane (but critically important) work involved with documenting the project. The ASP.NET Documentation Tool is based on the popular ASP Documentation Tool™ and is designed to take the strain out of producing technical documentation for ASP.NET web applications written in C# and VB.NET.

Although Microsoft have added support for the automatic documentation of ASP.NET projects to Visual Studio.NET, currently only C# offers this functionality. Furthermore, although the documentation produced by C#.NET is quite attactive from a design perspective (view sample), it relies on having to make liberal use of the XML Comments. An alternative is to make your own documentation from the XML Comments file, but this usually involves messing around with XSL stylesheets (see the ASPToday article C# Commenting Makes Documentation a Snap).

Configuring and Running the ASP.NET Documentation Tool

The ASP.NET Documentation Tool contains a graphical user interface that can be used to manage the documentation of projects and their associated databases.

The utility can also be run from the Windows command prompt. The ASP.NET Documentation Tool has a single command line option which specifies the filename of the configuration file. So to create documentation for the Sample ASP.NET project supplied, the following is typed at the command prompt (or run from a .bat file):

ASPNETDocumentationTool.exe --c="Config.ini"

The configuration file [view sample] is a plain text file containing the configuration options as such it can be modified using any text editor or word processor.

The ASP.NET Documentation Tool can of course be scheduled to automatically update project documentation by making use of the Windows AT command or the Task Scheduler.

The ASP.NET Documentation Tool creates a log file in plain text format [view sample].

Integration With Visual Studio.NET

The Visual Studio.NET development environment allows the addition of external tools to the menu bar. This allows the ASP.NET Documentation Tool to be run from within Visual Studio.NET, and therefore makes it straightforward to update the project documentation without leaving the development environment.

To integrate the ASP.NET Documentation Tool with Visual Studio.NET, use the following process:

• Set up a .bat file to run the ASP.NET Documentation Tool and pointing to the required .ini file. For convenience, the .bat file and the ASPNetDocumentationTool.pl Perl script should be in the same folder. For example, to run the ASP.NET Documentation Tool for the SampleWeb.NET project, create a .bat file with the following line:

  • ASPNETDocumentationTool.exe --c="Config.ini"

• In the Visual Studio.NET development environment choose the External Tools option from the Tools menu.
• Add a new External Tool using the following settings:
  • Give the External Tool a Title, e.g. ASP.NET Documentation Tool (SampleWeb.NET).
  • Type or paste the full path to the .bat file in the Command field.
  • The Arguments field should be left blank.
  • The Initial directory field should contain the path information previously entered in the Command field.
  • Ticking the Use Output window will cause the output from the ASP.NET Documentation Tool to be displayed in the Visual Studio.NET Output window rather than in a separate command prompt window.

Once the new external tool has been added it is visible from the Visual Studio.NET Tools menu. Once the tool has been started, it is possible to stop it running by choosing the menu option a second time.

The ASP.NET Documentation Tool contains the following features:

• ASP.NET file parser extracts content from files written in either VB.NET or C#. Supported file types are:
  • ASP.NET files (.aspx, .asax).
  • User Controls (.ascx).
  • Code Behind Files containing the code associated with ASP.NET files and User Controls.
  • Custom components (.vb and .cs).
  • SOAP/XML Web Service files (.asmx).
  • Web.config files.

• Configuration of the ASP.NET Documentation Tool is through the editing of a plain text configuration file [sample].

• Can be scheduled to automatically update project documentation by making use of the Windows AT command or the Task Scheduler.

• Can be integrated with Visual Studio.NET through the Tools menu bar.

• Detailed product documentation in Microsoft's HTML Help format [view documentation].

• Log file creation shows a summary of the ASP.NET Documentation Tool's actions.

• Compatible with most of the Microsoft XML Comments code documentation scheme for C# as used by Visual Studio.NET.

• Report shows the following for both VB.NET and C#:
  • Namespaces: What namespaces are in the project, and which classes are in each namespace.
  • Classes: What classes are in the project, which namespace they belong to and what functions and subroutines are defined within each class.
  • Functions: Where they are defined, and which arguments they use.
  • Subroutines: Where they are defined, and which arguments they use.
  • Where Application and Session variables are used.
  • Web Methods available using SOAP/XML Web Services.
  • Which User Controls are used in the project.
  • Which Web Controls are used in the project.
  • Which Validation Controls are used in the project.
  • What web.config files are used on the project.
  • Where email addresses are located in the project.

• SQL Server 7.0, 2000 and 2005 (including Express Edition) databases associated with the ASP.NET project can also be documented, with the following features:
  • Shows a list of tables within the database.
  • Shows a list of views within the database.
  • Shows a list of column names, type and length associated with each table.
  • Shows a list of stored procedures, including the full text of each stored procedure and its input parameters.
  • Shows a list of triggers within the database, and shows which table they are associated with.
  • If you require it, the SQL Documentation Tool can be used to generate even more detailed database developer documentation for SQL Server databases - generous discounts are available if you purchase the SQL Documentation Tool at the same time as the ASP.NET Documentation Tool.

• Most Microsoft Access databases can also be documented, with the following features:
  • Shows a list of tables within the database.
  • Shows a list of table columns within the database.
  • Shows a list of views within the database.
  • Shows a list of stored procedures within the database.

• There are a number of output options:
  • Standard HTML: This can be viewed in any web browser [sample], including Internet Explorer and Netscape.
  • Microsoft's HTML Help format: This format [sample] has the advantages of:
    • The project documentation is contained within a single, compressed .chm file.
    • The project documentation is searchable.
    • There is an index of project items.
    • The project documentation can be further modified using Microsoft's freely available HTML Help Workshop application.
    • If the project makes use of Namespaces and Classes, an additional "Class browser" HTML Help file is created in Microsoft's HTML Help format [sample].
  • Plain Text: This is a text file containing a summary of the project. As such it can be used as the basis of custom documentation written in a word processor [sample].

• The HTML format reports contain full copies of all files which have the following features:
  • Optional color coding and syntax highlighting of source code, making it easier to read.
  • Optional line numbering of source code.
  • There is the option to either colour code or hyperlink all of the following in the source code:
    • User Control usage.
    • Web Control usage.
    • Validation Control usage.
    • Application and Session variable usage.

• Suggested uses of the ASP.NET Documentation Tool:
  • Use it on newly acquired projects to assist in obtaining an overview of that project.
  • In this competitive market, why not produce project documentation for your clients? This shows you treat project documentation seriously.
  • When making large scale changes to a project, use it to find out where a function or a subroutine is called from.
  • Don't let your new hires loose on a project without them having the ASP.NET Documentation Tool's report to help them on their way!
  • The color coded, syntax highlighted source code created by the ASP.NET Documentation Tool can be copied and pasted into other documents, making code much easier to read.
  • The documentation can be used to complement the comment pages produced by Visual C#.NET.

Download the .NET Documentation Tool Evaluation Version (2980K ZIP file).