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

一.摘要

在本系列的第一篇文章介绍了.NET中XML注释的用途, 本篇文章将讲解如何使用XML注释生成与MSDN一样的帮助文件.主要介绍NDoc的继承者:SandCastle.

二.背景

要生成帮助文件,很多人会想到NDoc.其实在VS2003中不使用NDoc也一样具有"生成Web文档"的功能.然而很不幸,在升级为VS2005和VS2008后, Visual Studio中的此功能已经取消. 更遗憾的是NDoc这个项目由于资金等问题，作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发，NDoc停留在1.3的历史版本，无法完全支持.NET 2.0，将渐渐淡出人们的视野。

去年我还在使用VS2003.所以生成帮助文档使用了其自带的"生成Web文档"功能, 会自动根据注释生成HTML格式的帮助文档.今天我们公司已经全面升级到了VS2008以及Framework3.5,所以经过一番折腾发现居然找不到以前的这个功能了, 而且NDoc也不支持Framework2.0.

经历了一番周折,我发现了SandCastle这个由微软开发的软件.在此还要感谢微软论坛的版主"周雪峰"为我指点迷津告诉我此软件的存在.

在发布VS2005之前，MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。但是当时编译一次文档就需要十多个小时，使得工具的可用性不强。后来随着版本的不断优化,现在生成一个帮助文档大约只需要3分钟(分钟级别,具体时间要看生成文档的大小).

三.SandCastle简介

在上一篇文章中的帮助文件截图都是使用SandCastle生成的,比如下面的截图:

SandCastle是一个微软发布的工具，它通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。这个工具的源代码可以在CodePlex中以微软公开许可协议（Microsoft Public License）下获得。SandCastle 主要特性有：

兼容署名或未署名的注释
支持范型以及.NET 2.0框架
支持所有的.NET语言
支持.NET Compact Framework 项目
简单编译接口和Visual Studio插件

四.SandCastle工作原理

从CodePlex上下载SandCastle的源代码,打开后会找到如下项目:

有关这几个项目的关系可以用下图表示:

上图中各部分的作用:

SandCastle中主要有三个组件：MrefBuilder、Build Assembler和XslTransform。
HTML Help 1.x compiler(hhc.exe) 或者 Microsoft Help 2.0 compiler(hxcomp.exe) 用来生成 .chm 或者 .hxs 文件
Help Viewer 用于查看帮助文件.

MrefBuilder和XslTransform

MrefBuilder使用CCI从程序集中生成输出文件

XslTransform使用上面输出的文件生成 Reflection.xml 文档和Manifest文件.其中Reflection.xml包含所有无表现元素的数据.

BuildAssembler

Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。

HTML Help Compiler(1.x , 2.0 ) 再利用这些HTML文件生成最终结果。

除了上面介绍的核心的三个组件,还有一些用于生成最终文件的工具.比如 HTML Help Complier 这个角色是使用HTML Help Workshop工具完成的.HTML Help Workshop并不在SandCastle项目中,需要单独下载.要生成最终的.chm格式的文档,必须安装HTML Help Workshop.

我们注意到源代码中有一个ChmBuilder, 它的作用是生成可以供HTML Help Workshop使用的.hhc一类的文件,这些文件都是.chm格式文件的元数据.HTML Help Workshop的作用就是根据这些文件生成最终文档.