You need to have Visual Studio 2008 SDK 1.0 installed to be able to open the source code for these commands.

A short list of features that are provided by this project are:

• Collapse Projects
• Copy Class
• Paste Class
• Copy References
• Paste References
• Copy As Project Reference
• Edit Project File
• Open Containing Folder
• Open Command Prompt
• Unload Projects
• Reload Projects
• Remove and Sort Usings
• Extract Constant
• Clear Recent File List
• Clear Recent Project List
• Transform Templates
• Close All

You can download the package that contains the source code of PowerCommands from the announcement post.

In the Part I of this series we covered how to get up and running with Sandcastle and generate a CHM documentation file using the build.prof MSBuild project. By default, the MSBuild project that ships with Sandcastle generates the documentation with the vs2005 template. You can control the output style by adding one of the following options to the command line:

/property:PresentationStyle=vs2005
/property:PresentationStyle=hana
/property:PresentationStyle=prototype


Below you can view and compare screen shots of a VS2005, Hana, and Prototype formatted help files (click to see full-size images).

The templates themselves consist of a set of files (configuration and XSL transforms), and can be found under the \Presentation directory. Each template is in a separate directory, and has the following sub-folders:

• Configuration: contains Sandcastle config files (you probably won’t need to changes these);
• Content: XML files containing resource strings;
• Icons: images that are used in the resulting compiled HTML documentation;
• Scripts: javascript files that are used in the resulting compiled HTML documentation;
• Styles: CSS files containing formatting for the resulting compiled HTML documentation;
• Transforms: XSLT that convert the XML document file to HTML documentation.

Unless you are planning to develop your own template, which is definitely not for the faint-hearted and certainly outside of the scope of this blog post, you’ll want to contain yourself to editing the configuration and resource files. The following is an example of an edit that you might want to look at.

One of the things you might have noticed with the documentation that is produced using the VS2005 template is the really nice looking feedback form at the bottom of each page. This is shown below:

In order to get this to work properly, you need to set the target email address that will receive the feedback. Change directory to \Presentation\vs2005\Content and open the feedBack_content.xml file in your favourite text editor (mine is Notepad++). The second set of XML elements are what we are interested in. In particular, you can set the target email address by modifying the line as follows:

<item id="feedback_alias">myemail@example.com</item>

Once the help file is recompiled, clicking on the”Send Feedback” button will open a new email with the correct email address pre-populated.

There’s obviously plenty more to know about the Sandcastle template system. The aim of this post was simply to provide an overview and understanding of the templates.

Part III will cover how to generate documentation in the Microsoft Help 2 (HxS) format, which is the format that the Visual Studio help system uses.

Before we start, if you are not familiar with the XML commenting system then you should skim this primer. Also, we won’t be discussing any of the XML comment tags – for background on the supported tags either check out this excellent resource, or wait for the Professional Visual Studio 2008 book

Sandcastle uses two mechanisms to gather the data it requires to produce the documentation. Firstly, it uses reflection to discover all the public types, methods, and properties in a source assembly. Secondly, it optionally integrates any XML documentation comments. So basically this means that you can generate basic documentation with no XML comments, and really great documentation with a bit of inline XML commenting.

Firstly, download and install the latest Sandcastle package (at the time of writing this was the October 2007 CTP) . You can find a link to download the latest Sandcastle installer package on the Sandcastle Wiki.

By default, Sandcastle installs to c:\Program Files\Sandcastle. When it is run, Sandcastle creates a large number of working files and the final output file under this directory. Unfortunately all files and folders under Program Files require administrator permissions to write to, which can be problematic particularly if you are running on Windows Vista with UAC enabled. Therefore it is recommended that you install it to a location where your user account has write permissions.

Out of the box, Sandcastle is used from the command-line only. There are a number of third-parties who have put together GUI interfaces for Sandcastle.

To begin, open a Visual Studio 2008 Command Prompt and change directory to <Sandcastle_Install_Directory>\Examples\sandcastle\.

In this directory you will find an example class file, test.cs, and an MSBuild project file, build.proj. The example class file contains methods and properties that are commented with all of the standard XML comment tags. You can compile the class file and generate the XML documentation file by entering the command:

csc /t:library test.cs /doc:example.xml

Once that has completed, we are now ready to generate the documentation help file. The simplest way to do this is to execute the example MSBuild project file that ships with Sandcastle. This project file has been hard-coded to generate the documentation using test.dll and example.xml. Run the MSBuild project by entering the command:

msbuild build.proj

The MSBuild project will call a several Sandcastle tools to build the documentation file including MRefBuilder, BuildAssembler, and XslTransform.

You may be surprised at how long the documentation takes to generate. This is partly because the MRefBuilder tool uses reflection to inspect the assembly and all dependant assemblies to obtain information about all of the types, properties, and methods in the assembly and all dependant assemblies. In addition, anytime it comes across a base .NET Framework type, it will attempt to resolve it to the MSDN online documentation in order to generate the correct hyperlinks in the documentation help file.

The first time you run the MSBuild project, it will generate reflection data for all of the .NET Framework classes, so you can expect it to take even longer to complete.

By default, the build.proj MSBuild project generates the documentation in compiled help (CHM) format as shown below.

This post covered the basics of Sandcastle and how to get up and running with it and generate a CHM documentation file.

Part II provides an overview of the Sandcastle template system, which is what controls the look-and-feel of the final documentation.

Part III will cover how to generate documentation in the Microsoft Help 2 (HxS) format, which is the format that the Visual Studio help system uses.