使用 Sandcastle Help File Builder 制作 VS.NET 的 HELP 文件

以前笔者都是使用 NDoc 在制作 VS.NET 的 HELP 文件，它是相当好用且速度快的 HELP 产生器；不过 NDoc 在 1.3.1 版后，NDoc 的作者 Kevin Downs 就不再进行 NDoc Open Soruce 的开发。笔者之前有自行修改 NDoc 的 Source Code 解决中文乱码的问题，不过后来又遇到泛型类别无法正常产生 HELP 文件的问题，所以就改用微软推出的 SandCastle 配合 Sandcastle Help File Builder 来产生 HELP 文件，本文将介绍使用 Sandcastle Help File Builder 制作 VS.NET 的 HELP 文件。

 

一、安装 Sandcastle

首先安装微软的 Sandcastle - Documentation Compiler for Managed Class Libraries，你可以由下列网址下载最新版的 Sandcastle 安装程序，目前提供最新的版本为 Sandcastle May 2008 Release (Version 2.4.10520)。

http://www.codeplex.com/Sandcastle

 

二、安装 Sandcastle Help File Builder

Sandcastle 本身可以使用命令列的方式来制作 HELP 文件，不过这样太麻烦了，所以就需就有了一些具 UI 界面的 Sandcastle 编译工具，例如 SandcastleGUI、DocProject、Sandcastle Help File Builder 等工具，我们选择 Sandcastle Help File Builder 来制作 HELP 文件，它的操作界面与 NDoc 几乎一模一样。你可以由下列网址下载最新版的 Sandcastle 安装程序，目前提供最新的版本为 1.7.0.0。

http://www.codeplex.com/SHFB

 

三、制作 HELP 文件

step1. 加上程序代码批注

首先在程序代码中加上 VS.NET 标准的程序代码批注。

 

 

    ''' <summary>
''' 字串類函式庫。
''' </summary>
Public Class StrFunc
''' <summary>
''' 由字串中尋找關鍵字片段。
''' </summary>
''' <param name="Text">字串。</param>
''' <param name="Keyword">關鍵字。</param>
''' <param name="BLength">包含關鍵字前的字元數。</param>
''' <param name="ALength">包含關鍵字後的字元數。</param>
''' <returns>傳回符合的關鍵字片段的字串集合。</returns>
Public Shared Function FindKeywordParts( _
ByVal Text As String, _
ByVal Keyword As String, _
ByVal BLength As Integer, _
ByVal ALength As Integer _
) As List(Of String)
Dim sPattern As String
Dim oRegEx As Regex
Dim oMatchs As MatchCollection
Dim oMatch As Match
Dim oList As New List(Of String)
'正則式，以關鍵字含前後10個字元為 ".{0,10}}關鍵字.{0,10}"
sPattern = String.Format(".{{0,{1}}}{0}.{{0,{2}}}", Keyword, BLength, ALength)
oRegEx = New Regex(sPattern)
oMatchs = oRegEx.Matches(Text)
For Each oMatch In oMatchs
oList.Add(oMatch.Value)
Next
Return oList
End Function
End Class

 

step2. 编译产生 XML 文件档案

在项目属性中，切换到「编译」页面，勾选「产生 XML 文件档案」。当编译组件时，在组件输出的同一数据夹中，会同时产生与组件名称相同的 XML 文件档案，此档案中会包含程序代码中的注码。

 

 

step3. 使用 Sandcastle Help File Builder 制作 HELP 文件

执行 Sandcastle Help File Builder 程序，按「Add」钮加入要制作 HELP 文件的组件，然后执行菜单「Documentation\Build Project」执行建置 HELP 文件。

 

Sandcastle Help File Builder 常用的属性说明如下：

．HelpFileFormat: Help 文件格式，可复选 Help1x、Help2x、website 格式。
．HelpTitle: Help 文件抬页。
．HtmlHelpName: 输出 Help 文件档名。
．Language: Help 文件语系。(未提供繁体中文，所以可以使用预设的英文即可)
．PresentationStyle: Help 文件样式，可选用 hana、Prototype、vs2005 择一。
．Dependencies: 若编译 Help 文件有参考的组件无法找到，可使用此属性加入相关参考组件。

 

制作完成的 *.chm 文件如下所示

 

 

制作完成的 web 版 Help 文件如下所示