使用 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 StringDim oRegEx As RegexDim oMatchs As MatchCollectionDim oMatch As MatchDim 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 oMatchsoList.Add(oMatch.Value)NextReturn oListEnd FunctionEnd 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 檔案如下所示