Sandcastle September 2007 CTP Installation

Sandcastle is a great product for automatically generating documentation from .NET source code XML comments. Unfortunately, and somewhat ironically given that it's a product aimed at improving the quality of developer documentation, the documentation and instructions for using and installing this free offering are somewhat confusing and unclear.

As a result it seems many developers are ignoring it ("Life's too short"), a situation not helped by the fact that although Microsoft are using Sandcastle internally to produce MSDN-like documentation, it's been in CTP (Community Technology Preview) status rather than RTM (Release to Manufacturing ie ready for prime time) status
for what seems an eternity now (certainly more than a year!) It also lacks a nice user-friendly GUI (graphical user interface) out of the box, although thankfully several 'open source' options are available.

Having used Sandcastle I really rate it, and it's useful not just for automating developer documentation but also assisting with code reviews. So here's the missing guide on how to install it, and most importantly the pre-reqs it needs and the order they should be installed in, so that you can quickly get up-and-running with writing code that generates appropriate documentation automatically

1. Download and install the HTML Help 1.4 SDK. Annoyingly when you actually run the downloaded install program it identifies itself as version 1.3 but you can just ignore this Microsoft glitch.


2. Download and install the Visual Studio 2005 SDK v4.0 (February 2007). This is needed to install HTML Help version 2.0. It also installs an early version of Sandcastle that we will replace. Some blogs talk about the need to uninstall this early version of Sandcastle before proceeding using the Add/Remove Programs feature of the Windows Control Panel, but I could find no such entry to be removed and had no problems installing the newer version of Sandcastle after this step had been completed.


3. Download and install the Sandcastle September 2007 CTP itself. Remember that this only has a command line interface so isn't ideal for those of us that hate hacking our way around with the DOS command prompt.


4. Download and install Sandcastle Help File Builder. Two downloads from this link are needed - the main installation itself and the Presentation File fixes which have to be applied on top of Sandcastle itself (instructions are given in the associated readme file that is downloaded with the files. Things get messy very quickly and you may choose to bypass this step but if you follow the instructions you will have help files that are better formatted than those you get by default because of poor coding in Sandcastle itself).


5. Before running Sandcastle Help File Builder select Build Reflection Data from the Start menu using Start.Programs.Sandcastle Help File Builder. This is required before first use because the September CTP of Sandcastle does not contain any reflection data for the .NET framework. This step can take 30 minutes or more to run!

And (finally!) that's it. You need to allow at least half an hour for the Visual Studio 2005 SDK to install itself (and that MUST be done BEFORE you attempt installation of Sandcastle itself) and another half hour for the reflection data build script to run, but otherwise it's a pretty speedy process.

Once you've installed everything you need to actually make sure you add the appropriate XML tags to your code. These are fully documented in the MSDN library entry for XML Comment Tags. The interface to actually generate the HTML help files from these comments is pretty straightforward, but the following quick walk through will hopefully get you started:

1. Make sure your Visual Studio project has been enabled for Sandcastle. Select the project in Solution Explorer, right click to choose Properties and then select the Build tab on the resulting display. Make sure the XML Documentation File checkbox is ticked and that the name of the resulting XML file is specified in the section labelled Output.


2. Start Sandcastle Help File Builder and choose New Project from Visual Studio Project. Select the solution file you wish to document and the assemblies which will form the output for the project will appear in the Assemblies to Document window. Alternatively you can select New Project within Sandcastle Help File Builder and then just add the individual assemblies you want to document.


3. Individual namespaces can be selected or de-selected by clicking the Namespaces button on the main Sandcastle Help File Builder screen and then checking or unchecking the appropriate namespace.


4. References to external dlls used by the project or assemblies must be added using the Build button of the property marked Dependencies. If you are using Enterprise Library you will need to add the appropriate dlls using the File Dependency button and browsing to the appropriate dlls. Note that the displayed Dependency dialogue has a GAC button which can be used to select any dlls that are resident in the GAC (Global Assembly Cache).


5. Set other project properties as appropriate. For example, make sure you set the correct Framework Version, HtmlHelp1x if you want a .chm file, set the Help Title and HtmlHelpName appropriately and also the Language and the CSharp property to CSharp to exclude usage samples in languages other than C#

I'll be putting together a Step-by-step PDF document showing the whole installation process with screenshots some time over the next few days, but in the meantime I hope the above helps get you started with Sandcastle. It really IS worth spending the time on installing it.

Yesterday's Useful Links

CSS: BluePrintCSS 101 - Article on an interesting looking framework for CSS development.

C# 3.0: Deep Dive on Extension Methods - title says it all really: covers one of the new features in C# 3.0 in some depth (discovered via the C# Developer Centre, which I really should keep more of an eye on!)

LINQ/IIS7: Using LINQ with Microsoft.Web.Administration - simple code to easily work with IIS 7 using Microsoft LINQ.

.NET Utilities: UberUtils part 3: Strings - nice looking library of string utilities. Be sure to also follow the links on that blog to Parts 1 and 2 which both cover Cryptography.

Process: One year of SCRUM - Lessons Learnt - first in what looks like it will be an interesting series on lessons learnt after using SCRUM methodology for the best part of a year.

Silverlight: Silverlight Addict - yet another new Silverlight-oriented web site. Is there really that much work going on in this area (I reckon 1.1 - which is where things start to get interesting - is the best part of a year away, but I guess 1.0 is a great way to start getting into WPF) or is Silverlight just yet another 'flavour of the month' with the Web 2.0 luvvies?

Silverlight: How to Check if Silverlight is installed - hard to find info just in case you ARE writing Silverlight apps.

VISTA: Windows Vista Experience Guidelines - now that Vista really is being used in the mainstream a timely reminder that there are some guidelines out there that we developers should be following in the new (oh look! blue screens of death are back!) world of Vista.