ASP.NET 魔法學院

以前筆者都是使用 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 文件如下所示

ASP.NET 魔法學院