使用SandCastle和HTML Help 2.0集成XML代码注释到VS2005和VS2008

为什么要使用XML代码注释呢？一开始我也只认为它就是生成帮助文档方便一些，因为我们项目也在使用生成帮助文档甚至是通过代码注释生成详细设计书的工具，所以就放弃了使用XML代码注释。然而对于基础结构（Infrastructure）类库而言，接口的描述和变化的文档化记录、智能标记和F1快速帮助，无疑可以为其它开发人员的开发效率带来提升。同时也节省了接口的文档修改和同步的问题，所以我推荐在基础结构或类库中使用XML注释标记。下面的内容，记述了如何通过工具为带有XML注释的代码生成帮助文档，并将帮助文档集成到Visual Studio帮助系统中的方法。

 

1. 下载并安装工具

- Sandcatle

- Sandcastle Help File Builder

- HTML Help 2.0 编译器

HTML Help 2.0编译器集成在VS SDK中 (VS2005 SDK) (VS2008 SDK)

HTML Help 2.0编译器会安装在目录“%Program Files%\Common Files\Microsoft Shared\Help 2.0 Compiler\”下。
可以通过hxcomp.exe文件搜索并定位此目录。

2. 配置项目生成XML注释文件

打开项目属性，选择“创建”标签并勾选“生成XML文档文件”。然后，重新编译解决方案或工程。

3. 配置Sandcastle Help Builder

创建新项目，添加你的程序集到该项目中。确保XML注释文档也生成在与程序集相同的目录下。添加后如“MyAssembly.dll, MyAssembly.xml”而不是“MyAssembly.dll, Unknown.xml”。如果没有XML注释文件，那么帮助文档将不会被生成。

配置Sandcastle Help Builder如下：

Build > Help File Format: 选择 HtmlHelp2x
Build > Dependencies: 添加所有你程序集依赖的程序集
Build > Framework Version: 选择程序集的.NET Framework版本
Help File > Presentation Style: 选择VS2005模式，样式很漂亮
Paths > HtmlHelp2xCompilerPath: 选择hxcomp.exe文件所在的目录
Paths > SandcastlePath: 选择Sandcastle所在的目录

4. 创建帮助文件

现在你可以创建出你的帮助文档，没有特别的浏览器将无法浏览Help 2版本的帮助文档。
所以在没有帮助文件浏览器的前提下应该创建HTML Help 1.x文档。你可以通过设置来改
变样式、选择警告的开关并且定义哪些成员将被记录到帮助文件中。
最后创建一个HTML help 2.0版本的帮助文件这样可以集成到Visual Studio的帮助系统中。

5. 集成帮助文件到Visual Studio

运行Visual Studio，选择“文件”>“新项目”
选择“其它项目类型” > “扩展” > 帮助集成导航
在第一个页面，选择“安装项目”, 选择你的Visual Studio版本，然后继续。
在第二个页面中添加你的HTML Help 2.0帮助文件(*.hxs)，如果愿意可以试着修改后两步的设置。
编译工程，运行创建的安装程序可以安装你的文件到Visual Studio。

 

希望以上内容对大家有所帮助，有任何疑问可以留言，欢迎大家多提意见和建议。