使用.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的作用就是根据这些文件生成最终文档.

五.快速上手SandCastle

本篇文章只从我所掌握的知识上,讲解如何快速简单的使用SandCastle.方法可能有些繁琐.要想如鱼得水的使用它现在看来必须要使用第三方开发的SandCastle辅助工具.在本系列以后的文章中我会抽出时间进行研究.

(1)准备软件

首先需要我们准备如下软件:

SandCastle, 下载地址:
http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx
说明:
上面的连接会链接到CodePlex上的SandCastle项目的最新Release版本.其中页面上会有如下图两种下载方式:

请下载SandCastle.msi文件,这里包含我们即将使用的一些比如GUI工具等.而下面的源代码zip中则不包含,从大小也能看出来.知道如何使用SVN和TFS的用户也可以从源代码服务器上获取最新的开发中的SandCastle版本,我获取了其SVN上的版本,获取后也包括全部内容和工具.

HTML Help Workshop,下载地址:
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

(2)准备项目文件

准备好程序的dll文件和注释的xml文件.比如本文实例的两个文件:XmlCommentClassDemo.dll 和 XmlCommentClassDemo.XML

注意如果我们的项目关联多个dll,则需要将相关的项目的dll和注释xml文件都准备好.否则的话在帮助文件中将不能点击相关的类.(如果添加了一个类所在的项目dll和xml文件,则此类在chm文件中可以被点击,点击后跳转到此类的说明页面.)

(3)使用GUI生成帮助文件元数据

安装完SandCastle后,会在其generic目录中找到GUI工具:SandcastleGui.exe,运行界面如图:

如上图所示,在Name处输入"XmlCommentDemo"后,点击Build,首先会提示保存一个sproj文件.

默认会在创建文件夹: C:\Program Files\Sandcastle\\Examples\XmlCommentDemo

经过SandCastle我们已经生成了chm文件的元数据文件,路径保存在:

C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中.

(4)使用HTML Help Workshop生成CHM文件

在C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中有这三个文件:

XmlCommentDemo.hhc

XmlCommentDemo.hhk

XmlCommentDemo.hhp

运行HTML Help Workshop,可以打开XmlCommentDemo.hhp文件.单开文件后,单击"File"->"Compile...",弹出如下图的界面:

单击"Compile",则会在.hhp的目录下生成.chm文件,如下图所示:

XmlCommentDemo.chm就是最终文档.

五.总结

经过本篇文章的介绍将使用.NET注释的XML格式文件和程序的DLL文件,生成类似MSDN的文档.对于注释在帮助文档中的作用,请查看本系列的第一篇文章.

由于研究有限我目前也只能粗略的使用SandCastle,后续文章中将陆续深入的学习SandCastle的使用.希望大家能够一起讨论,一起研究,一起进步.

六.相关资源

微软SandCastle博客: http://blogs.msdn.com/sandcastle/default.aspx

SandCastle项目:http://www.codeplex.com/Sandcastle