Sandcastle 学习教程 （1） 基础入门

概要

目前可找到SandCastle学习资源十分有限。而据我所知能够生成帮助文档的工具目前只有SandCastle（NDoc早就已经停止更新了，参见“相关文档”中的第二篇。）

有关XML注释，我曾经写过两篇文章，里面也简单介绍了如何使用SandCastle：

使用.NET中的XML注释(一) -- XML注释标签讲解
使用.NET中的XML注释(二) -- 创建帮助文档入门篇
 

本系列教程希望能够深入的研究SandCastle，比如SandCastle的各个组件，高级的使用技巧，如何与持续构造（FinalBuilder）继承等。

本篇文档翻译自SandCastle的两篇官方文档。目前官方文档只能找到下面翻译的内容。

一.SandCastle介绍

Sandcastle是托管类库的文档编译器，用来生成微软风格的API接口说明和程序结构说明的帮助文档。通过反射关联的.NET Framework 程序集，使用源代码中的 XML文档注释（在C#中的“///”或者VB中的“’”）生成API接口说明文档。通过反射dll文件创建程序结构说明，其他的比如提醒和参数等信息都是通过源代码中的XML注释导出的。

生成的文档如下图所示：

二. SandCastle特性

SandCastle是由微软提供的用于生成.Net帮助文档的工具，可以生成API接口说明和程序结构说明。

支持.NET Framework 2.0
使用VersionBuilder工具支持不同版本的项目
使用CHMBuilder 工具用来生成HTML 1.x版本的chm文件。
符合 Visual Studio 2008 的帮助主题
使用Windows的PowerShell脚本生成文档接口说明
支持5星MSDN风格的投票反馈
 

三. 系统要求

操作系统

Windows Server 2003;
Windows Vista;
Windows XP Service Pack 2

软件环境

.NET Framework 2.0， 可以在.NET Framework网站下载。
HTML Help Workshop，支持HTML 1.x 文件，可以通过 HTML Help 下载站点下载，或者通过Visual Studio SDK 安装。

推荐环境

MS Help 2.0 Compiler，支持HTML 2.0 文件，是VS2005或更新的版本安装时的一部分，可以支持生成HTML 2.0（.Hxs）文件。
Visual Studio 2005，可以与帮助文档集成。

四. 安装SandCastle

确定机器上已经安装了HTML Help Workshop，创建Help 2.0(HxS)文件还需要Help 2.0 Compiler。Visual Studio 2008 SDK已经包括了这两部分。
卸载早期的SandCastle版本（不是随着Visual Studio 2008 SDK安装的）。
从CodePlex下载 SandCastle Installer， 并运行安装程序。
注意：

如果想要安装Visual Studio 2008 SDK，请在安装SandCastle之前安装。这是因为Visual Studio 2008 SDK 安装时更新了PATH和DXROOT两个系统注册的变量。如果在SandCastle安装后这两个变量被更新，将导致SandCastle无法工作。如果已经安装了SandCastle，有下面两个方法：

安装Visual Studio 2008 SDK后，卸载SandCastle，重新安装SandCastle。
重新设置PATH和DXROOT两个环境变量
如果是非x86（32位机器）机器，请参考下文。

在AMD64机器上设置SandCastle

在开始菜单上，在“我的电脑”上单击鼠标右键，选择“属性”。
在左侧的区域中，单击“高级系统设置”。
在“高级”标签中单击“环境变量”按钮。
在“环境变量”中找到“PATH”，单击“编辑”。
将下面的变量添加到属性值中：
%ProgramFiles(x86)%\HTML Help Workshop;%ProgramFiles(x86)%\Common Files\Microsoft Shared\Help 2.0 Compiler