Automatically documenting web site projects created in VB with Sandcastle

• Download source code - 1.48 KB

Introduction

I had a requirement to write some documentation a web site which I had created. The web site also contained a .asmx page containing some Web Services.

I have successfully used Microsoft Sandcastle, first at command-line (never again), and later with Sandcastle Help File Builder (awesome piece of kit) to generate a professional looking .chm file to document a console application I wrote, and decided I wanted to use the same tools to document my web site.

Important - This is now superseded

Please note that the article is now mostly superseded by the following: http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=22689.

I would advise the reader to refer to the above URL to document their website projects with Sandcastle. However, the article text is still in place for those interested in how I did this prior to this project's release.

Background

This article looks at how to create documentation for a web site project which is not the same as a web application project written in Visual Basic.

There is some scattered information on the web about this topic, but I had to look in many places (including my own imagination) to come up with a complete solution. It is because of this that I thought writing an article about what I did might help others who also want to achieve the same sort of goals.

Sorry to the C# programmers amongst you, but unfortunately, a command-line option which is passed to the VB compiler to make this lot work is not available for the C# compiler. More on this later.

I found an actual reason to use VB over C# at last...

Update: I found there may be some custom code providers which extend the C# compiler to address this problem, at http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx?ReleaseId=13440[^]. I have not attempted to use them.

Pre-requisites

In order to get the final CHM file, you need a few things installed. Please have these installed before you proceed.

0. You must know how to create XML documentation in your code. If you don't, please read http://msdn.microsoft.com/en-us/library/xzysab5k(VS.80).aspx and the "See Also" at the bottom of the page before continuing. This whole article relies on XML comments!

1. A working knowledge of Sandcastle. It would benefit you greatly to have this before reading the rest of my article. Head over to http://www.codeplex.com/Sandcastle[^] and familiarize yourself with the project.
2. The Sandcastle binaries installed. Grab them from the same location.
3. A working knowledge of the Sandcastle Help File Builder, with some success in creating a CHM file based on a console application. Head over to http://www.codeplex.com/SHFB to have a read about it. I strongly recommend that you take some time to generate a basic CHM file on a simple console application that you write. This will help you a lot to understand the rest of this article.
4. The Sandcastle Help File Builder installed. Grab it from the above URL.
5. In case you didn't read point 3 above, I would like you to read it :) Please have a go at documenting a console application with success before you proceed.

Problems With Documenting Web Sites

There are several obstacles one must overcome when trying to document a web site project. A web application project (which is shipped with Visual Studio 2005 SP1 and mimics the way things used to be in VS2003) which is a different project type, I have read, is slightly easier.

Any discussions about web application projects are outside the scope of this article, but I would point you to http://msdn.microsoft.com/en-us/library/aa730880(VS.80).aspx for more information and background reading.

The problems sum up to:

• Sandcastle requires you to reference a DLL. When publishing a web site project, you get many DLL files, randomly named. This would be OK, you could add them all to a Sandcastle project, but the next time you publish the web site project, the DLLs will have changed name - so you have to delete/re-add all the files, every build.
• Sandcastle requires an XML file which has been created containing all your XML comments. On first look, there is no way to make Visual Studio create this for web site projects.

Enter Web Deployment Projects - Problem Solving: Part 1

To solve the first problem, we use "Web Deployment Projects". This is an add-in released by Microsoft, and is used as an alternative to publishing the website. In addition to some other useful features, it allows a web site project to be compiled into a single DLL, whose name can be specified. This solves the first problem.

It is now necessary for you to install the web deployment projects add-in to Visual Studio, and to add to your solution a Web Deployment Project for the the web site you wish to document.

Once you've installed the add-in (get it from http://msdn.microsoft.com/en-us/asp.net/aa336619.aspx), right-click on your web site project in Solution Explorer and choose "Add web deployment project".

With your web deployment project added, right-click it in Solution Explorer and go to "Property Pages". Take a look at "Output Assemblies". You need to make sure that "Merge all outputs to a single assembly" is selected. Give the assembly any name of your choice that makes sense to the web project you have built. Remember the name here you enter.

Tick the "Treat as library component" checkbox. You're now done here, so you can safely close the property pages. Now build the web deployment project and then have a look in the location you specified when you added the WDP. You should see a compiled website, similar to publishing it, but there should only be one DLL file here, not many. The DLL should be named according to the name you entered in the property pages.

Enter VB Compiler Optisons - Problem Solving: Part 2

Remember that I summed up two problems for Sandcastle. The first we have solved with WDP above. The other problem was that Sandcastle requires an XML file which has been created containing the XML comments. Here is why this article only works for VB applications and not C#.

Both compilers can be called with a /doc option which specifies a location for XML documentation comments. The trouble with web site projects is that many assemblies are compiled, which WDP then combines all into a single assembly. However, the process of creating many assemblies means that the XML documentation file gets overwritten by the compiler many times in a typical website build, and you do not get a complete set of documentation.

VB has an option called "/doc+" which creates a new documentation file for each assembly - which allows us to proceed. However, the C# compiler has no such option. All I can think for C# users is that you could create some sort of FileSystemWatcher application to monitor all the changes to the file... However that's outside the scope of this project. If you're a VB user, read on. This is a showstopper for C# as far as this article is concerned, I am afraid.

The next thing we need to do is to tell the VB compiler to create this documentation. To do this, create a system.codedom section in the web.config file of your main web application. Just above the final </configuration> line, add the following code:

<system.codedom>
<compilers>
<compiler language="vb" extension=".vb"
    type="Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,
    Culture=neutral, PublicKeyToken=b77a5c561934e089" 
    compilerOptions="/optionstrict+ /doc+" />
</compilers>
</system.codedom>

Please note that this enables Option Strict too! This is a good practice for your VB applications, but you may notice a lot of compiler errors when you've added this, especially if you're trying to save strings to integer variables and so forth. If you think it would be better to not use Option Strict just now, use:

<system.codedom>
<compilers>
<compiler language="vb" extension=".vb"
    type="Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,
    Culture=neutral, PublicKeyToken=b77a5c561934e089" compilerOptions="/doc+" />
</compilers>
</system.codedom>

What happens now is that the VB compiler will create XML documentation files for the assemblies. We're a step closer....

Enter CombineXmlDocComments - Problem Solving: Part 3

The files containing the XML comments after a build are, by default, saved into C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files. From this location, find the folder representing your application, dig around a bit, and you'll find the XML comments files.

You'll remember that I said earlier that Sandcastle Help File Builder wants one XML file to correspond to one DLL file. The problem as it stands is that we have many XML files, relating to each original assembly compiled, before the WDP did its magic and combined the DLLs.

The Solution? Write Some Code...

What I have written is a console-based application which will, for a given path, find the latest XML files, concatenate them into a single XML file, and save this new, "master comments" file into a given location. The ideal location would be the same folder as the .dll file produced by the WDP, right? That way, we can just point the Sandcastle Help File Builder to the DLL, it will find the XML in the same folder, and it will produce a nice documentation.

The code I wrote to do this is downloadable from the link at the top of the article. I think the comments speak for themselves, so I'm not going to go into great detail explaining what it does.

The application is designed to be run from the command line, in the following format:

CombineXmlDocComments param1 param2 param3

where:

• param1

The path to the root of your application within the Temporary ASP.NET Files folder. The application automatically finds the XML files within the tree, so this should be something like: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication, and not: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication\a2b88f6f\1efe7d38.

The "a2b88f6f\1efe7d38" bit is pretty random, and the console application is capable, and designed, to work this out itself.

• param2

The output file location. This should be the same location as the WDP was set to point to, but at a "/debug/bin" level down.

For example, if you set your WDP to publish files to: c:\Webs\MyWebsite_Deploy, then you would set param2 to: c:\Webs\MyWebsite_Deploy\Debug\bin.

• param3

This is the name you want the XML file to assume; pass only the name, not the extension. This should match identaically what you entered for "Assembly name" in the WDP. For example, "MyWebsite".

Almost There...

So we're almost there. We can now build our web application into a single assembly, generate the XML files for it, and combine those XML files into a master XML file by running the console app from the command line.

You may now try to build the help file with Sandcastle - you should get some meaningful output.

You may notice that you don't get comments you entered in the .aspx.vb files. This is because, by default, they are not in a namespace. The solution is to put all the Partial Class declarations inside the .aspx.vb files within their own namespace, such as MyApplication.Web.Forms. Then, when you run Sandcastle (after rebuilding the web project and WDP; then running the console application to combine and move the XML documentation), be sure to look at "Namespaces" and make sure to include "MyApplication.Web.Forms", and you should get the documentation you need... :-)

(Note: If you start to get build errors after putting the partial classes within the namespace, then open the .aspx page and look for the "Inherits" on the fist line, and include the namespace. So, Inherits="WebForm1" becomes Inherits="MyApplication.Web.Forms.WebForm1").

Et viola - You should now be able to fully document your web site projects! Recapping the process:

0. Learn how to XML-comment your code.

1. Install Sandcastle
2. Install Sandcastle Help File Builder
3. Have some success in documenting a simple console application so you get some background on Sandcastle Help File Builder
4. Install Web Deployment Projects
5. Add a WDP to your solution and configure it
6. Amend Web.config to make the compiler create the documentation using /doc+
7. Put your web forms (*.aspx.vb) files into a namespace
8. Build your commented web application to a single DLL using WDP
9. Run the console application to combine the XML comment files generated by the compiler and save them to the same location as the DLL
10. Use SHFB to generate the help files, making sure to include the namespace used in point 6

Tidying It All Up

Finally, we can make use of a lesser known and vastly under-documented feature of the WDP post build tasks. We can add a post build task to automatically execute the console application for us, and also to automate the SHFB to build the .chm file for us. This means that documenting your website code becomes as simple as literally clicking "Rebuild Solution" in your Solution Explorer.

To do this, in your Solution Explorer, right-click WDP and choose "Open project file". You will see some comments at the bottom about post-build tasks. At the bottom of the file, obviously not within comments, add this (replace the file paths as appropriate):

<Target Name="AfterMerge">
<!-- Combine the compiler generated XML files into a single XML file, and copy this
    over to the folder with the DLLs. -->
<Exec Command='C:\temp\CombineXmlDocComments.exe
 "C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\MyWebApplication"
 "C:\Visual Studio Working Copy\MyWebApplication_deploy\Debug\bin" MyWebApplication'/>

<!-- Run the Sandcastle Help File Builder. -->
<Exec Command=
 '"C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe"
  "C:\Documents and Settings\itsdbsloan\Desktop\
   Sandcastle Projects\MyWebsiteApplication.shfb"' />
</Target>

And we're finished! All you need to do now is to "Rebuild Solution" and you'll get a CHM file created automatically.

It's a bit of a pain for the first project, but documenting the second project should be a lot simpler:

1. Add WDP and configure
2. Add the namespaces to the .aspx.vb files
3. Open the property pages of WDP and add some post build tasks with different paths

See Also

The Sandcastle Styles project: Sandcastle Styles.