Create .NET documentation with Microsoft's Sandcastle

by Tony Patton | Apr 10, 2007 3:28:00 PM

Tags: PRODUCTIVITY, .NET, Microsoft development tools, Tony Patton, Microsoft Corp., Build Assembler, Sandcastle, MrefBuilder, XML, tool, .NET Newsletter

5 comment(s)

Takeaway: Microsoft's Sandcastle is a compiler for managed class libraries that provides you with the tools to generate MSDN-style documentation. Take a look under the hood to see if Sandcastle might be useful for your next .NET project.

From its beginning, the .NET Framework allowed C# developers to use XML-style comments in their code. This feature was added to VB.NET with version 2.0. The compiler can use these comments to generate basic technical documentation. The end result of using the XML commenting feature is a large XML file that is less than user friendly.

Developers wanted and needed another tool to take the XML and create something readable. The open source project NDoc answered the call by enhancing and simplifying the process and facilitating various help file formats. Unfortunately, this project recently ended because the creator received little or no assistance from the development community.

Weekly .NET tips in your inbox

TechRepublic's free .NET newsletter, delivered each Wednesday, contains useful tips and coding examples on topics such as Web services, ASP.NET, ADO.NET, and Visual Studio .NET.

Automatically sign up today!

As the demise of NDoc was announced, Microsoft released the first version of its documentation tool called Sandcastle. It is a documentation compiler for managed class libraries. It also processes source assemblies via reflection and uses the XML comments within the code to generate MSDN-style documentation, which is more user friendly than hard-to-decipher XML. Microsoft says it used it internally to build the .NET Framework documentation.

Sandcastle works with the .NET Framework 2.0 (with instructions available online for working with version 1.1) and the .NET Compact Framework. Sandcastle supports localization and offers a basic command-line compiler interface, as well as a Visual Studio add-on.

How to get Sandcastle

The latest version of Sandcastle is available via Microsoft's March 2007 Community Technology Preview. You may install and run it on Windows Server 2003 or Windows XP Service Pack 2. It requires the .NET Framework 2.0, as well as the HTML Help Workshop. Once the prerequisite software is installed, you can install the Sandcastle tool.

Under the hood

There are three main components within Sandcastle: MrefBuilder, Build Assembler, and XslTransform. These tools use output generated when assemblies are compiled. This includes the DLL file, as well as any XML comment files.

MrefBuilder reflects against a project's assemblies and generates an output file. MrefBuilder is a command-line tool installed with Sandcastle. The generated output file is transformed via the xslTransform command-line tool into a file called reflection.xml. The reflection.xml file contains all of the documentation data but no presentation details.

Build Assembler takes over once MrefBuilder is finished. It is available as the BuildAssembler command-line tool. It takes the data generated by MrefBuilder (reflection.xml), along with any code comments (in separate XML files), and produces logically grouped HTML files. These HTML files are used by the HTML Help Compiler to produce the final output.

The tool does not restrict you to working with one assembly at a time. You will need to dig into the Sandcastle configuration file when you need to process multiple assemblies. This is an XML file that contains the steps needed to build the topics for your help file.

The output

The Sandcastle-generated output has the following features:

MSDN-like layout look and feel.
Auto-generated index entries, table of content entries, topic chunking, and page layout promote consistency and familiarity.
Auto-generated syntax declaration sections.
Auto-generated inheritance tables.
Code colorization.
Multiple styles and language selection give the end user the ability to select his or her favorite preferences.

The output is styled and presented with HTML and CSS, with Microsoft promising different styles in the future.

Optional interfaces

Many developers shudder when faced with a command-line interface -- they prefer the slick GUI interface such as the popular Visual Studio IDE. Third-party tools are available that allow you to drive the Sandcastle process via a user-friendly GUI interface. Here are three that are available:

Sandcastle Help File Builder: It provides an interface similar to NDoc and allows you to import existing NDoc projects and automate the build process.
SandcastleGUI: This is a freely available GUI front-end for Sandcastle.
Sandcastle CHM-compile BAT script and configuration utility: This is a configuration utility and batch script for creating MSDN-style class documentation CHM files via Sandcastle.

Help others

Developers need to know how an application works when/if they are working with its code, as well as how to use any application interface. Microsoft Sandcastle provides the tools necessary to generate MSDN-style documentation for your project. Check out this wiki about Sandcastle for details about the tool.

Do you consistently document your code? What tools or techniques do you use when developing documentation? Share your thoughts and experiences with the community by posting to the article discussion.