This article describes some of the practical uses of the ASP
Documentation Tool™.
The ASP Documentation Tool™ is a utility for creating technical documentation for web applications
written in ASP 2.0 and 3.0 using either the VBScript or JScript scripting languages.Three
different types of report
The ASP Documentation Tool ™ creates three types of report about an ASP web application:
- The standard HTML report can be viewed in any web browser that supports
frames
[sample].
The Microsoft HTML Help format is the format used by most Windows
applications for their help files [sample].
The plain text report can be viewed in any text editor or word
processing application [sample].
How to
determine which ActiveX objects are used on a site
ASP web applications commonly make use of ActiveX objects to perform tasks such as
connecting to databases or sending email. When moving websites between web servers, it is
critical to know which objects are used on the site, as it may be necessary to install
these objects on the new web server or to rewrite the code. For example, ASP code that
sends email can use any one of a number of third party objects.
The ASP Documentation Tool ™ looks for the instantiation of ActiveX objects through the use of the
CreateObject and Server.CreateObject functions. The report produced by the ASP
Documentation Tool™
contains a list of the objects used, and shows where each object is used in the web
application:
Figure 1. The ASP Documentation Tool shows which ActiveX objects are used in a web
application
The ASP Documentation Tool™ is able to show the source code of public Functions and Properties of any
custom ActiveX objects written in Visual Basic 6.0. This is shown in Figure 1 above (the
custom ActiveX object is called Samplewebcomobject).
Modifying ASP function
or subroutine parameters
A common task in development is modifying the parameters associated with a particular
function or subroutine. Typically this would be to add additional parameters to the
function and subroutine. This involves two processes:
- Modifying the function or subroutine's parameters.
- Changing all the calls to the function or subroutine to reflect the changes made to the
parameters.
The ASP Documentation Tool™ contains a list of all the VBScript functions and subroutines, and JScript
functions. Clicking on a function or subroutine name will show where the function or
subroutine is to be found within the site. There is a also a list of where in the site the
function or subroutine is used. This makes it a straightforward task to change the
function or subroutine's parameters, as well as all of the calls made to the function or
subroutine.
Figure 2. The ASP Documentation Tool shows where functions and subroutines are
found, and where they are used
Tidying up the code of a web application
The ASP Documentation Tool™ can be useful when tidying up the ASP code of a web application. For
example, it is able to assist with the following:
- Rationalisation of duplicate functions and subroutines. The ASP Documentation
Tool
™ lists all of
the VBScript functions and subroutines and JScript functions used in the web application.
It is, therefore, straightforward to remove duplicate instances of these functions and
subroutines. Duplicated functions and subroutines could probably be moved to a global
include file.
Removal of email addresses used for testing purposes. The ASP
Documentation Tool™
displays where email addresses are used on a site, so it can be useful for ensuring that
functionality that sends email will send the messages to the correct recipients.
Determining
where a particular stored procedure is used
The ASP Documentation Tool ™ is also able to document SQL Server 7 and SQL Server 2000/2005 databases.
The resulting documentation for the database is fully integrated with the documentation of
the ASP files within the web application. The documentation includes a list of stored
procedures within the databases documented. Clicking on the name of a stored procedure
will show the details of that procedure. It will also show where in the ASP code that
stored procedure is called from (provided that the name of the stored procedure has
been preceded with the EXEC keyword).
Figure 3. The ASP Documentation Tool™ will also document SQL Server 7.0 and SQL
Server 2000/2005 databases associated with a web application
Alternatively, it is possible to use the integrated search facility within the HTML
Help report to search for the name of the stored procedure. A list of all the occurrences
of the search query will be displayed. HTML Help report produced by the ASP Documentation
Tool™ allows all of
the source code of the web application to be searched. Because HTML Help files are
compiled, searching them is much faster than using the search facility within a
development package such as Visual InterDev.
Our 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 Documentation Tool.
My boss/project manager/client wants technical
documentation in Word format
The ASP Documentation Tool™ is able to create a text report of the ASP web application and associated
SQL Server 7.0, SQL Server 2000, SQL Server 2005, SQL Server Express 2005 or Microsoft
Access databases. This text report can, therefore, be used as the basis for the technical
documentation of a project. The ASP Documentation Tool™'s text report contains lists of:
- ASP Pages
- ASP VBScript functions
- ASP VBScript functions (with arguments)
- ASP VBScript subroutines
- ASP VBScript subroutines (with arguments)
- ASP JScript functions
- ASP JScript functions (with arguments)
- Client-side JavaScript functions
- Client-side JavaScript functions (with arguments)
- ActiveX Objects used
- Functions within custom Visual Basic 6.0 ActiveX objects
- Functions within custom Visual Basic 6.0 ActiveX objects (with arguments)
- Application variables used
- Session variables used
- Request.QueryString variables used
- Request.Form variables used
- Request.ServerVariables variables used
- VBScript Constants
- HTML Forms
- Email Addresses
- SQL Server 7.0, SQL Server 2000 or SQL Server 2005/2005 Express Edition databases:
- Tables
- Table Columns
- Views
- Stored Procedures
- Triggers
- Table Relationships
- Microsoft Access databases:
- Tables
- Table Columns
- Views
- Stored Procedures
An ASP Documentation Tool sample text report is available.
Migrating a site
from Classic ASP 2.0 or 3.0 to ASP.NET
The ASP Documentation Tool ™ can also assist in the migration of web applications from ASP to ASP.NET.
This is a topic that has been covered on the Microsoft website (see Migrating to ASP.NET: Key Considerations). The ASP Documentation Tool™ can assist the migration
process by:
- Listing the ASP pages associated with the web application.
- Showing a list of VBScript functions and subroutines that will need to be converted to a
language such as VB.NET
- Showing a list of JScript functions.
- Showing which pages make use of the ADO objects - these pages could be candidates for
conversion to ADO.NET.
- Shows Application and Session variable usage.
Note that a ASP.NET Documentation Tool
is also available, should you wish to document your ASP.NET web applications. |
