At the moment I'm working on a small, but usefull, .NET framework for one of my customers. The purpose of this framework is build around Logging, Configuration, etc. The customer has a team of .Net Developers that will be using this framework with every application they build from now on. The framework is fairly simple, however I wanted to offer the developers good support in terms of documentation.
Below I'll show you the steps to create documentation and integrate this with Visual Studio's Help environment.
Step 1 - Create good Xml Comment for all your framework code.
The initial content of the documentation is written in Xml Comments, that is all the comment you write above classes, methods, properties etc in your code files. This is easy and you can maintain it right beside your code in Visual Studio.
In C# you can position the cursor right above the method declaration and type 3 forward slashes "///". This will expand into an Xml based comment area where you can type a summary of the method's intention.
You can find a good overview here: http://cyrino.members.winisp.net/9112006/XMLDocs.doc
Step 2 - Extract the Xml Comments when building the Project
You can extract the Xml comment every time you build the project output. This is usefull to automate the process in a whole later on. Open the project Properties by double clicking on the properties folder of your project and navigate to the Build tab. Below you'll find the check box to extract the Xml comment after a build.
Step 3 - Create the Documentation files using SandCastle
Sandcastle is the Microsoft variant of NDoc that creates a documentation file from the Xml comment we extracted in step 2. There's a GUI called SandCastle Help File Builder (SHFB) which you can download from Codeplex here: http://www.codeplex.com/SHFB.
After you installed SHFB, you need to create a new project file. A SHFB project defines, what the content of the help will be and what type of output you want.
You can choose between different output types, being:
- HTML Help 1: help files with the chm file extension.
- HTML Help 2: help files with the HxS file extension. Note that you can't open these files directly. They are like content files of the Help 2 system on which Visual Studio is also based
- Web Site: Web based help (html files)
I find it a good option to create HTML help 1 files during the creation of the help content, because you can easily see the result by just opening the chm file. When the authoring part is over, I switch to HTML help 2.
Note: In order to produce HTML Help 2 output, you need the propper compiler (HxComp.exe) which is included in the Visual Studio 2005 SDK which you can download here: http://www.microsoft.com/downloads/details.aspx?FamilyID=51a5c65b-c020-4e08-8ac0-3eb9c06996f4&DisplayLang=en
The default location of the Help compilers is:
HtmlHelp1 (Hhc.exe) : C:\Program Files\HTML Help Workshop
HtmlHelp2 (HxComp) : C:\Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Archive\HelpIntegration
I advice you to take a look at the different options of SHFB. In most cases you're code depends on other assemblies, so you need to add them to the dependencies collection.
Step 4 - Register the Documentation.HxS in the Visual Studio Help
The output of step 3 is one HxS file. The goal here is to register the help content in this file in the visual studio 2005 help.
You need to download a tool for this purpose called FAR here: http://www.helpware.net/FAR/ and follow these steps below:
- Start the H2 collection Wizard and provide a name for a new collection
- Add your Hxs file in step 2 of the wizard "Add Help Titles"
- Click next up to step 6 "Create Reistration script file". Make sure the "create H2Reg Script file" option is selected and choose "ms.vsipcc+;ms.vscc;ms.vscc.2003" as parent namespace.
- Click next and finish.
The wizard generated some additional files (HxA, HxC, HxT) and a H2Reg_cmd.ini file. The latter file is an instruction file for the command line tool H2Reg.exe, which you can download here: http://helpware.net/mshelp2/h2reg.htm. H2Reg will perform the actual registration of the help into the HTML help 2 subsystem (although you can use FAR as well to register the help content).
To test the registration, open up a cmd window and use the following command:
H2Reg.exe -R "cmdfile=H2Reg_cmd.ini"
to unregister use :
H2Reg.exe -U "cmdfile=H2Reg_cmd.ini"
Step 5 - Create an installer
In this last step, we'll add the registration to a setup project in Visual Studio. This way, you can perform the following:
- Install your assemblies under the typical "Program Files" location
- Install help under the typical "Program Files" location. I use HTML Help 1 for this kind of help since it is a compact fast loading chm file.
- Install your assemblies into the GAC
- Register help into Visual Studio documentation.
In order to perform the last step, add a Custom Action to your setup project for both the install and uninstall :
use the command from H2Reg in this custom action:
Note that I added the -Q switch to perform a quiet install.
Make sure you add the following artifacts to the setup project
- The HxA, HxC, HxS, HxT files
- The H2Reg_cmd.ini
- The H2Reg.exe
- The H2Reg.ini
Since Visual Studio SP1, you have the option to choose between 2 approaches when building websites
- ASP.NET Web Site
- ASP.NET Web Application
The ASP.NET Web Application has been added in SP1 (actually you could download it seperately already before SP1)
There are some differences between both, basically the Web Application gives us back a project file like we had in Visual Studio 2003.
Initially Microsoft dropped the project files for ASP.NET in Visual Studio 2005 in favour for a location based approach (file system, IIS, ...). However because of too many complaints of the community, Microsoft undo its mistake and released the WAP (Web Application Project) and so restored the project files for ASP.NET, later on this was packaged into Visual Studio SP1.
My recomendation is to always use Web Application Projects which you can create using:
- File | New | Project menu
- Select the "Web" category in Visual C# or Visual Basic
Master Pages
Now the goal of this article is to point out the differences when working with master pages.
ASP.NET Web Site
In the last years you've probably worked with ASP.NET Web Sites. When you added a new Web Form you had the option to select if you wanted to use a Master Page or not like in the picture below
ASP.NET Web Application
If you now create a ASP.NET Web Application, you'll notice that the option is gone. Instead, there's a new item template called "Web Content Form".
