12.5 用Sandcastle编译文档
Sandcastle是Microsoft公司作为文档编译器发布的一组工具。这些工具可以用Microsoft编译的HTML帮助（.chm）或Microsoft Help 2（.hxs）格式，创建非常专业的外部文档。
Sandcastle的信息主要位于Sandcastle博客http://blogs.msdn.com/sandcastle/。在CodePlex上还有一个项目，它是Microsoft公司开源项目的主站点：http://sandcastle.codeplex.com/。在这个站点上有文档、Sandcastle论坛和下载最新Sandcastle安装包的链接。
Sandcastle默认安装在c:\Program Files\Sandcastle下（如果安装在64位系统上，默认安装位置就是c:\Program Files（x86）\Sandcastle）。在运行时，Sandcastle会在这个目录下创建大量的工作文件和最终的输出文件。但Program Files下的所有文件和文件夹都需要管理员权限才能写入，如果运行Windows Vista时启用了UAC，那么这个问题会更严重。因此，建议把它安装在用户账户有写入权限的位置。
另外，Sandcastle只能在命令行上使用。有许多第三方供应商为Sandcastle设计了GUI界面，这些界面链接到Wiki上。
首先打开Visual Studio 2015 Command Prompt，把目录改为<Sandcastle Install Directory> \Examples\sandcastle\。
Visual Studio 2015 Developer Command Prompt相当于一般的命令提示行，只是它还设置了各个环境变量，如Visual Studio 2015命令行工具常需要的目录搜索路径。
在这个目录中有一个示例类文件test.cs和一个MSBuild项目文件build.proj。该示例类文件包含用标准XML注释标记（参见本章前面的内容）解释的方法和属性，以及其他一些Sandcastle专用的XML注释标记。输入下面的命令，就可以编译这个类文件，生成XML文档文件：
csc /t:library test.cs /doc:example.xml
在Windows 7中，Sandcastle安装目录位于Program Files中，默认不能改变此文件夹路径。这意味着当运行此命令时，就会遇到安全问题。为解决此问题，可以提供Examples子目录（及其下方的所有子目录）的写入权限，或者可以管理员身份运行Developer Command Prompt for Visual Studio 2015。
之后，就准备生成文档帮助文件。最简单的方法是执行Sandcastle附带的示例MSBuild项目文件。这个项目文件使用test.dll和example.xml硬编码，以生成文档。输入下面的命令，就可以运行MSBuild项目：
msbuild build.proj
MSBuild项目会调用几个Sandcastle工具来构建文档文件，包括MRefBuilder、BuildAssembler和XslTransform。
不要每次构建发布版本时都手动运行Sandcastle，最好把它作为一个构建后事件执行，确保它总是运行。第6章介绍了如何创建构建事件。
生成文档需要的时间很长，其部分原因是MRefBuilder工具使用反射技术查看程序集及其所有从属程序集，以获得其中的所有类型、属性和方法信息。另外，只要遇到基本.NET Framework类型，该工具就尝试把它解析为MSDN联机文档，以生成文档帮助文件中的正确超链接。
第一次运行MSBuild项目时，会为所有.NET Framework类生成反射数据，所以运行时间比较长。
MSBuild项目build.proj默认在<Sandcastle Install Directory>\Examples\sandcastle\chm\目录下生成vs2005外观和操作方式的文档，如图12-5所示。在命令行上添加如下选项，就可以选择另一种输出风格。
/property:PresentationStyle=vs2005
/property:PresentationStyle=hana
/property:PresentationStyle=prototype
图12-5
下面是示例类文件test.cs中的部分源代码，与它相关联的帮助文档页面如图12-5所示。
/// <summary>
/// Swap data of type <typeparamref name="T"/>
/// </summary>
/// <param name="lhs">left <typeparamref name="T"/> to swap</param>
/// <param name="rhs">right <typeparamref name="T"/> to swap</param>
/// <typeparam name="T">The element type to swap</typeparam>
public void Swap<T>(ref T lhs, ref T rhs)
{
T temp;
temp = lhs;
lhs = rhs;
rhs = temp;
}
MSBuild项目build.proj的默认目标是Chm，它会为test.dll程序集构建一个CHM已编译的HTML帮助文件。还可以在命令行上指定如下目标：
/target:Clean - removes all generated files
/target:HxS - builds HxS file for Visual Studio in addition to CHM
Microsoft Help 2（.HxS）是Visual Studio帮助系统使用的格式。必须安装Microsoft Help 2.x SDK，才能生成.HxS文件。在Visual Studio 2015 SDK中可以使用它。