用微軟Sandcastle建立.NET文件

從一開始，.NET Framework就允許C#開發者在他們的程式碼中使用XML形式的註釋。這一特性被增加到VB.NET 2.0中。該編譯器能夠使用這些註釋生成基本的技術文件。使用XML註釋最終得到一個難以理解的大型XML檔案。

開發者想要並希望用其它工具代替XML，建立更易於理解的文件。開源專案NDoc通過改進和簡化上述過程，並提供各種幫助檔案格式，滿足了這一需求。遺憾的是，由於創立者很少或幾乎沒有得到開發社群的支援，最終該專案被終止。

NDoc宣佈終止後，微軟推出它的第一版文件工具——Sandcastle。這是一個管理類庫的文件編譯器。它還可通過反射處理彙編原始碼，並在程式碼中使用XML註釋生成MSDN形式的文件，這種文件比難以解讀的XML更易於理解。微軟稱它在內部使用它建立.NET Framework文件。

Sandcastle與.NET Framework 2.0（可線上找到它與1.1版本的用法說明）和.NET Compact Framework組合使用。Sandcastle支援本地化，並提供一個基本的命令列編譯器介面和一個Visual Studio外掛。

如何獲取Sandcastle

微軟2007年3月的社群技術預覽提供最新版的Sandcastle。你可以在Windows Server 2003或Windows XP Service Pack 2上安裝和執行該工具。它需要系統上安裝有.NET Framework 2.0和HTML Help Workshop。安裝必要的軟體後，你就可以接著安裝Sandcastle工具。

深入瞭解

Sandcastle中共有三個元件：MrefBuilder、Build Assembler和XslTransform。這些工具使用編譯彙編程式碼時生成的輸出結果，包括DLL檔案以及XML註釋檔案。

MrefBuilder反射一個專案的彙編程式碼並生成一個輸出檔案。MrefBuilder是一個隨Sandcastle安裝的命令列工具。它生成的輸出檔案通過XslTransform命令列工具轉換成一個叫做reflection.xml的檔案。reflection.xml檔案包含所有文件資料，但不提供顯示細節。

MrefBuilder完成工作後，立即由Build Assembler接手處理。Build Assembler可由命令列工具BuildAssembler啟動。它利用由MrefBuilder生成的資料(reflection.xml)和任何程式碼註釋（儲存在獨立的XML檔案中），生成按邏輯分組的HTML檔案。HTML Help Compiler再利用這些HTML檔案生成最終結果。

該工具並未限制你一次處理一個彙編。如果你需要處理幾個彙編程式碼，你必須深入瞭解Sandcastle配置檔案。它是一個包含建立幫助檔案主題所需步驟的XML檔案。

輸出結果

Sandcastle生成的輸出結果具有以下特點：

• 類似於MSDN佈局的介面。
• 自動生成索引項、內容專案表、主題塊和頁面佈局，提高一致性和熟悉程度。
• 自動生成語法宣稱部分。
• 自動生成繼承表。
• 程式碼彩色化。
• 提供多種風格和語言選擇，終端使用者可從中選擇自己最喜歡的形式。

輸出結果以HTML和CSS形式顯示，微軟承諾將來提供更多選擇。

可選介面

許多開發者討厭命令列介面——他們更喜歡靈巧的GUI介面，如流行的Visual Studio IDE。同時，你還可以使用第三方工具，利用一個友好的GUI介面推動Sandcastle過程。以下是三個有效的工具：

• Sandcastle Help File Builder：它提供一個類似於NDoc的介面，允許你輸入現有的NDoc專案，自動完成建立過程。
• SandcastleGUI：這是一個免費的Sandcastle GUI前端介面。
• Sandcastle CHM編譯BAT指令碼和配置實用工具：這是一個配置實用工具和批處理指令碼，由它通過Sandcastle可建立MSDN形式的類文件CHM檔案。

幫助他人

如果開發者處理應用程式程式碼，他們需要了解應用程式的工作原理，以及如何使用應用程式介面。微軟Sandcastle提供為你的專案生成MSDN形式文件所需的必要工具。檢查這個Sandcastle wiki瞭解該工具。

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/12639172/viewspace-364710/，如需轉載，請註明出處，否則將追究法律責任。