原文地址:http://broadcast.oreilly.com/2010/09/build-html-documentation-for-y.html#commentshtml
Sandcastle 功能概述
瀏覽器
若是您使用過的程序集中,帶有詳細的 API 說明文檔,而且文檔的格式和 MSDN 上的同樣,您將發現這樣 API 說明文檔的是多麼的方便。生成相似的 HTML 格式文檔的方法有不少,不過,我發現其中最簡單的方法是使用 Sandcastle 工具來生成這樣的 API 文檔。Sandcastle 是微軟開發的一款開源的文檔生成器,它能夠讀取您的程序集(DLL 和 EXE 文件)和 XML 註釋文件,並且能自動生成相應的 HTML 格式的文檔。Sandcastle 既是一款很是靈活的工具,同時它也是一款很是複雜的工具。不過幸運的是,還有另一款與之相似的輔助工具, Sandcastle Help File Builder,這個工具讓您在幾分鐘以內就能夠很容易地獲取和運行 Sandcastle。安全
本教程將帶您建立簡單的 HTML 格式的類描述文檔,下面是咱們接下來要作的:服務器
備註,咱們還需完成一些額外的事情:app
[丟失 <summary> 節點]
的問題步驟一: 安裝 Sandcastle 和 Sandcastle Help File Builderide
Sandcastle 是一款很是強大、靈活的工具。因爲它是基於控制檯命令行的,所以沒有相應的圖形界面終端可供使用。這樣您就很難隨意啓動並使用它就。和其餘大部分軟件同樣,Sandcastle 也知足 80/20 規則 : 80% 的用戶僅僅使用其中 20% 的功能。幸運的是,如今有一個名稱爲 Sandcastle Help File Builder 的工具,它讓您很是方便地使用 20% 的功能。有了 Sandcastle 和 Sandcastle Help File Builder (有時把它簡稱爲縮寫形式 SHFB),您幾分鐘內就能夠啓動並生成輔助文件和 HTML 文檔了。工具
首先下載和安裝 Sandcastle and Sandcastle Help File Builder(這裏我用的是 2015.1.12.0版本):ui
下,
SHFB 被安裝在 EWSoftware\Sandcastle Help File Builder 文件路徑下。
注意,安裝 Sandcastle 和 Sandcastle Help File Builder 後,您還能夠把它們安裝目錄下面的內容所有複製到另一個目錄下,從而把它們的安裝路徑改爲你想要的路徑,在新目錄下,它們依然能夠被啓動並使用。若是您工做的機器被鎖住,您不能用它來安裝程序 — 爲了安全,辦公室裏的不少電腦都會被鎖住 — 這個功能將頗有用。當您在一個構建服務器上運行一個連續的生成命令,來生成 HTML 文檔,可是您又沒有管理員權限時,它也能夠派上用場。this
步驟二: 建立一個名稱爲 Guy.cs 的 C# 代碼文件編碼
Sandcastle 按兩步來生成文檔。 第一步,利用反射來檢查程序集中的公共類中的成員,第二步,讀取 XML 註釋文檔並生成的相關記錄。
當 Sandcastle 從程序集中建立文檔時,它須要程序集中至少有一個命名空間和而且命名空間中至少包含一個公共的類。不然,它將拋出一個錯誤(咱們將在幾分鐘內看到)。所以,咱們須要作的第一件事是準備好您的代碼,並添加 XML 註釋。
(若是您以前沒有使用過 XML 註釋,您能夠在個人 C# XML 註釋教程 中快速的瀏覽它們。一樣,若是您對 .NET 程序集和 C# 命名空間比較迷惑,瀏覽一下個人 C# 與 .NET 程序集和命名空間教程 。)
在本教程的第一部分, 咱們將在控制檯命令提示行中完成全部後臺任務。因此如今,您應該使用 Notepad 來編碼咱們建立的源文件。在命令行中執行全部後臺命令和在 Visual Studio 執行時的效果同樣。我比較擔憂控制檯命令行,由於這裏使用的是手動構建工具,全部咱們須要知道如何建立文件。並且在構建過程當中,還須要在控制檯命令窗口中使用一些控制檯命令,然而許多 .NET 開發人員使用控制檯命令提示符的時間並不長。若是您沒有使用過,也不用擔憂,您只需看看網上的這個章節 從命令提示符中編譯和運行 C# 代碼。
我已經準備了一個帶有 XML 註釋的類。它在個人 個人簡單工具類 Guy。前往並 從該連接中複製 Guy.cs 的代碼 ,把它粘貼到 Notepad,,最後將其保存文名稱爲 Guy.cs 的文件。
下面是 Guy 類的代碼:
/// <summary> /// 一個夥計,擁有名稱,年齡和裝滿現金的錢包 /// </summary> class Guy { /// <summary> /// 爲 Name 屬性建立的支持只讀的字段 /// </summary> private readonly string name; /// <summary> /// 夥計的名稱 /// </summary> public string Name { get { return name; } } /// <summary> /// 爲 age 屬性建立的支持只讀的字段 /// </summary> private readonly int age; /// <summary> /// 夥計的年齡 /// </summary> public int Age { get { return age; } } /// <summary> /// 夥計擁有的現金 /// </summary> public int Cash { get; private set; } /// <summary> /// 構造方法,用來設置名稱,年齡和現金 /// </summary> /// <param name="name">夥計的名稱</param> /// <param name="age">夥計的年齡</param> /// <param name="cash">夥計最初擁有的現金</param> public Guy(string name, int age, int cash) { this.name = name; this.age = age; Cash = cash; } public override string ToString() { return String.Format("{0} 今年 {1} 歲,並且擁有 {2} 元現金", Name, Age, Cash); } /// <summary> /// 從夥計的錢包中捐錢 /// </summary> /// <param name="amount">打算捐的現金數目</param> /// <returns>實際捐出的現金的數目,若是錢包中的錢不夠就返回 0</returns> public int GiveCash(int amount) { if (amount <= Cash && amount > 0) { Cash -= amount; return amount; } else { return 0; } } /// <summary> /// 向錢包中存入一些現金 /// </summary> /// <param name="amount">打算存入的現金的數目</param> /// <returns>實際存入的現金的數目,若是沒有存入現金就返回 0</returns> public int ReceiveCash(int amount) { if (amount > 0) { if (amount > 0) { Cash += amount; return amount; } Console.WriteLine("{0} 說:{1} 不是我將拿走的數目", Name, amount); } return 0; } }
注意 Guy 類是如何利用 String 類和 Console 類的?它們都是 System 命名空間下的一部分,所以爲了不編譯出錯,須要 在 Guy.cs 文件的頂部添加這一行:
using System;
您的代碼如今能夠準備去編譯了。(您可能已經發現了一個小小的錯誤,這個錯誤將使 Sandcastle 出現問題 — 咱們將在幾分鐘內修復它)
步驟三: 把 C# 代碼編譯成 Guy.dll 程序集
如今咱們開始使用 C# 編譯器的控制檯命令 CSC 命令來編譯代碼。下面介紹怎麼來執行它:
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\csc.exe
若是你獲得一個 "系統找不到指定的路徑 " 的錯誤, 在命令行中用 v3.5 替換 v4.0.30319
. 本教程中的一切程序都是在 .NET 3.5 下運行的。 v4.0.30319 表示 .Net Framework 4.0 的版本號。本教程中全部的工做均可以在 .NET 3.5 中成功運行,因此若是你已經安裝了它,你能夠把 v4.0.30319 替換成 v3.5後再運行。 或者,若是你已經安裝了 Visual Studio ,你能夠啓動 Visual Studio 的控制檯命令,csc.exe 命名就在對應的目錄下。(Express 版本的 Visual Studio沒有此功能)
打開命令行提示符並把目錄指向你保存 Guy.cs 文件的地方,運行下面的命令:
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library /doc:Guy.xml Guy.cs
控制檯將顯示的如下界面 (個人 Guy.cs 文件保存在 F:\temp\Guy):
當你運行 csc.exe,它會新建兩個文件: Guy.dll (包含 Guy 類的程序集)和 Guy.xml (包含從 XML 註釋中生成的文檔)。
步驟四: 設置 Sandcastle Help File Builder 項目
爲了運行 Sandcastle Help File Builder,你只須要設置幾個變量而後運行 SandcasteBuilder 的圖形界面。最簡單的方法就是複製下面三個命令到控制檯命令行:
set DXROOT = F:\Program Files (x86)\Sandcastle set SHFBROOT = F:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder set LANGUAGE = "%SHFBROOT%\SandcastleBuilderGUI.exe"
(您能夠按如下方式在控制檯窗口中使用粘貼功能:點擊窗口左上角的菜單圖標,並選擇編輯 >> 粘貼)
打開 Sandcastle Help File Builder 的操做界面,在菜單中選擇文件 >> 新建項目,並命名爲 Guy.shfbproj (這是 SHFB 項目通用的擴展名)。下面是新建 SHFB 時的操做界面:
接下來,你須要告訴 SHFB 從哪裏去找 DLL and XML 文件,來給 Sandcastle 使用並生成相關文檔。先在項目資料管理器中,右擊「文檔」,選擇 "添加文檔源...", 導航到 Guy.dll 文件並選中它,SHFB 會自動一併添加 XML 文件 — 須要把 Guy.dll 和 Guy.xml 都添加到文檔源中:
若是您正在使用的 dll 文件中包含對其餘 dll 文件的引用,您能夠經過資源管理器中的引用節點來添加對它們的引用。就像在 Visual Studio 中添加引用同樣來添加對它們的引用。
接下來,您將選擇輸出格式。默認地,Sandcastle 會生成一個 HTML 輔助文檔 CHM。 在 Build 選項卡下找到 Help File Formats 下拉框,去除 HtmlHelp1 的選中,而後勾選 Website:
您也可使用 HtmlHelp1 選項來生成一個 HTML 幫助(*.chm後綴)文件。可是在您使用以前,您須要安裝 Html Help 1.x SDK。查閱 HTML Help MSDN page 能夠獲取更多的信息和下載連接。
點擊工具欄上的 「保存全部」 按鈕來保存 Guy.shfbproj 項目。如今,您的 Sandcastle Help File Builder 項目就準備好了。
步驟五: 運行 Sandcastle
下面將運行 Sandcastle。在其菜單中選擇 >> 生成文檔 來運行 Sandcastle。在生成輸出標籤中,您會看到 Sandcastle 的運行狀態:
噢,您好像獲得了一個錯誤!
SHFB: Error BE0033: No APIs found to document. See error topic in help file for details.
記住我以前怎麼說的,您的程序集必須至少包含一個命名空間和一個公共類。而程序集 Guy.dll 都沒有包含。
幸運的是,這很容易修改。在 Notepad 中打開 Guy.cs 並作以下改動 。您將使用 namespace
關鍵字來把類 Guy 存放到名稱爲 GuyTest 的命名空間中,同時您將使用
public關鍵字來使類 Guy 變成公共訪問類 — 保證您在類定義末尾處添加了一個關閉的花括號!下面是定義好的類和命名空間(新添加的文本用 粗體 表示)
using System; namespace GuyTest { /// <summary> /// 一個夥計,擁有名稱,年齡和一個裝滿現金的錢包 /// </summary> public class Guy { ... existing Guy class ... } }
既然 Guy 類已是公共的並在 GuyTest 命名空間中,您就能夠編譯程序集了。再次運行 CSC 命令來從新生成 Guy.dll 程序集。 此次應該重寫 Guy.dll 程序集和 Guy.xml 文件。
此次 CSC 命名會給出一個缺失 XML 註釋的警告,但也會運行:
F:\temp\Guy>%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library /doc:Guy.xml Guy.cs Microsoft(R) Visual C# 編譯器版本 4.6.1055.0 用於 Microsoft(R) .NET Framework 4.5 版權全部 (C) Microsoft Corporation。保留全部權利。 Guy.cs(61,25): warning CS1591: 缺乏對公共可見類型或成員「Guy.ToString()」的 XML 註釋
咱們將在幾分鐘內修復這個問題。可是首先 使用文檔 >> 生成項目並再次運行 Sandcastle。 此次生成將會很是成功:
祝賀您 — 如今您已經成功生成了 HTML API 文檔!在IE瀏覽器中打開幫助文檔 Help\index.html。
在頁面的頂端,您會獲得一個警告信息:
點擊它並從菜單中選擇「容許阻止的內容...」,這樣作後,您將會看到新生成的 HTML 幫助文檔!
5.1 修復 Sandcastle [丟失 <summary> 節點]的問題
您可能已經注意到生成的 HTML 幫助頁面中,有一個這樣的標題: A Sandcastle Documented Class Library 。能夠修改這個標題,返回到項目屬性頁並修改幫助標題屬性。 確保最後您保存了 SHFB project file 文件。
接下來,您還記得執行 CSC 命令時,顯示的缺失 XML 註釋的警告嗎?
Guy.cs(47,29): warning CS1591: Missing XML comment for publicly visible type or member 'GuyTest.Guy.ToString()'
在 IE 瀏覽器中找到 HTML 幫助,並導航到 GuyTest 命名空間 >> Guy 類 >> Guy 方法 >> ToString 方法。您將看到這個:
這是 Sandcastle 生成的提示信息,由於它找不到相關的註釋。您能夠經過爲 ToString() 方法添加一個 XML 註釋來修復這個問題。爲上面的 ToString() 方法,添加這樣的註釋:
/// <summary> /// ToString()方法返回 guy 對象的名稱,年齡和現金 /// </summary>
/// <returns>夥計的基本信息</returns> public override string ToString() { return String.Format("{0} is {1} years old and has {2} bucks", Name, Age, Cash); }
5.2 添加一個 AssemblyInfo.cs 文件來設置程序集屬性
最後,點擊 Guy 類的任意一個成員,您將看到下面這行說明:
Assembly: Guy (in Guy.dll) Version: 0.0.0.0
您能夠建立一個 AssemblyInfo 文件來改變版本號。它和 Visual Studio 生成的典型的屬性文件同樣。下面是 Guy 類的一個屬性文件的例子 — 我用 Visual Studio 先新建一個新項目而後來建立它,可是您只能 把它粘貼到 Notepad 並保存爲 AssemblyInfo.cs 文件:
AssemblyInfo.cs:
using System.Reflection; using System.Runtime.InteropServices; // 有關程序集的常規信息經過如下 // 特性集控制。更改這些特性值可修改 // 與程序集關聯的信息。 [assembly: AssemblyTitle("ConsoleApplication")] [assembly: AssemblyDescription("")] [assembly: AssemblyConfiguration("")] [assembly: AssemblyCompany("Microsoft")] [assembly: AssemblyProduct("ConsoleApplication")] [assembly: AssemblyCopyright("Copyright © Microsoft 2016")] [assembly: AssemblyTrademark("")] [assembly: AssemblyCulture("")] // 將 ComVisible 設置爲 false 使此程序集中的類型 // 對 COM 組件不可見。 若是須要從 COM 訪問此程序集中的類型, // 則將該類型上的 ComVisible 特性設置爲 true。 [assembly: ComVisible(false)] // 若是此項目向 COM 公開,則下列 GUID 用於類型庫的 ID [assembly: Guid("45cc3d18-1e80-4154-9c84-bfa454656022")] // 程序集的版本信息由下面四個值組成: // // 主版本 // 次版本 // 生成號 // 修訂號 // // 能夠指定全部這些值,也可使用「生成號」和「修訂號」的默認值, // 方法是按以下所示使用「*」: // [assembly: AssemblyVersion("1.0.*")] [assembly: AssemblyVersion("1.0.0.0")] [assembly: AssemblyFileVersion("1.0.0.0")]
如今您能夠 使用 CSC 命令從新編譯程序,此次添加 AssemblyInfo.cs 到命令行的末尾。 下面是控制檯命令行代碼:
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\csc.exe /target:library /doc:Guy.xml Guy.cs AssemblyInfo.cs
在您的文件資源管理器中右擊 Guy.dll 並選擇 Properties,點擊「詳細信息」標籤,您將看到新的版本號,標題,公司和版權。
回到生成的 HTML 幫助頁面,在左邊的文件樹節點裏點擊(「GuyTest Namespace」)節點。注意:它又產生了一個類似的錯誤:
[缺失 "
N:GuyTest" 文檔]
XML 註釋在命名空間中無效,請不要相信我以前說過的話 — 嘗試在命名空間上添加一個 <summary> 註釋並從新編譯您的代碼。不然您將獲得下面的警告:
警告 CS1587: XML 註釋沒有被放置在一個正確的語言元素下
您的 DLL 和 XML 文件將像以往同樣被生成,可是 XML 文件將不會對命名空間的進行註釋。
幸運的是,這鐘事情在 Sandcastle 中很容易處理。回到項目「屬性」頁並在註釋部分點擊 "Summaries" 選項。點擊「Edit Namespace Summaries」按鈕,將彈出命名空間註釋窗口。在窗口中的 "Checked namespaces" 選項盒中,點擊 GuyTest 命名空間來選中它,並確保它被選中,同時也選中它的上面是"(global)"選項。而後確保右邊的"Selected namespace appears in"窗口中的 Guy 被選中。而後在下面的大的文本框中輸入一個註釋。
關閉命名空間概要窗體。如今命名空間概要屬性將讀取:1 顯示概要,0 從項目中排除。
點擊工具欄上的所有保存按鈕並從新生成文檔。當您在 IE 瀏覽器中從新加載它時,您將看到命名空間和 ToString() 方法的概要。
5.3 運用 MSBuild 從控制檯命令行來運行 Sandcastle 的項目文件
當您的 SHFB(*.shfbproj) 項目文件能夠正常運行後,您還能夠在控制檯命令行中使用 MSBuild 命名來生成它。 這是用於 Visual Studio 的代碼生成器。和用來編譯 C# 的 CSC 命令 同樣,它和 .NET Framework 一塊兒被安裝。同時您須要運行下面的命令來生成 Guy 類的說明文檔:
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe Guy.shfbproj
等等 — 您獲得下面的錯誤了嗎?
錯誤 MSB4019: 未找到導入的項目 "C:\SandcastleHelpFileBuilder.targets"。請確保申明的路徑正確,而且該文件在磁盤上存在。
若是您獲得了這個錯誤,確保 DXROOT, SHFBROOT, 和 LANGUAGE 變量都被設置好了。若是您不設置 SHFBROOT 變量,您將獲得這樣的信息。一樣若是您不設置 DXROOT 變量 SHFB 將找不到 Sandcastle。所以,若是這些環境變量沒有被設置時,您可能須要去 再次執行這三個設置控制檯的命名 (在運行 SHFB 以前您已經執行過的相同的命令)。
下面是我運行後的界面:
用 MSBuild 命令生成的文檔和上面用 CSC 命令生成的文檔徹底同樣。若是您須要把文檔整合到一個持續生成的環境中,MSBuild 命令將很是有用。
是否獲得一個警告 (SHFB : 警告 BHT0001
)? 若是您獲得了,這個問題已在一些 SHFB 版本中被發現。您可使用 MSBuild 3.5 命令來阻止這個警告 而不是 4.0.x。在大多數狀況下,SHFB 和 Sandcastle 仍然能夠很好地生成文檔,即時產出了這個警告。獲取更多信息,請查看 SHFB Codeplex 站點上的這個線程。
5.4 在 Visual Studio 項目中運用 Sandcastle Help File Builder項目
Sandcastle Help File 生成器也可使用 C# 項目文件(*.csproj)做爲一個文檔源。下面將介紹如何獲取您的 Guy.cs 文件和 AssemblyInfo.cs 文件,並把它們添加到 Visual Studio 的一個類庫中,而後從這個項目中,利用 Sandcastle Help File Builder 來生成文檔。
首先,建立一個新的 Visual Studio 項目並添加 Guy.cs 和 AssemblyInfo.cs 文件:
還有另一件事您須要作。 在解決方案資源管理器中,右擊 GuyTest 並在菜單欄中選擇屬性 打開項目屬性頁。點擊「生成」標籤,並 選中「 XML 文檔文件」這個的複選框。 指定其文件名爲 Guy.xml。
點擊工具欄上的所有保存按鈕來保存您的項目。如今這個項目生成的 Guy.dll 和 Guy.xml 文件和您以前用 CSC 命名生成的文件同樣。不只如此,若是您須要,您還能夠在控制檯命令窗口使用 MSBuild 命令來編譯它 — 只須要傳遞一個 GuyTest.csproj 參數。
如今回到 Sandcastle Help File 生成器,在文檔源目錄下右擊 Guy.dll ,並選擇從菜單中移除。 而後對 Guy.xml 作同樣的操做。
最後, 添加 GuyTest.csproj 到文檔源目錄下, 它在 Visual Studio 爲您建立的文件夾下。點擊工具欄上的所有保存按鈕來保存 GuyTest.shfbproj。
如今您能夠從新運行 Sandcastle,或者使用 Sandcastle Help File Builder 或者 MSBuild。此次,它將生成相同的文檔,可是它是利用 .csproj 文件而不是您使用 CSC 命令生成的 DLL and XML 文件。
首先,您須要生成 DLL。您能夠在 Visual Studio 進行生成 — 或者,若是您須要,您也能夠不用 Visual Studio 來生成,而是用 MSBuild 命令進行生成。下面是我使用 MSBuild 命令來生成 DLL 時的代碼。這裏須要傳遞 GuyTest.csproj 文件的完整路徑給 MSBuild 命令。注意:請確保您指定的路徑是正確的!同時若是有任何空格,請用引號 "" 把它們包括起來。
F:\temp\Guy>%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe "F:\Projects\ConsoleApplication\GuyTest\GuyTest.csproj"
生成的文件以下:
接着我使用 MSBuild 從新編譯 GuyTest.shfbproj 。生成的 HTML 文檔和上面的同樣,不過,此次我使用的文件源是 C# 的類庫項目文件。
做者介紹:
Andrew Stellman 是《 Head First C# 》一書的做者,在 O'Reilly 出版社還出版過其餘書籍。瞭解更多關於 Andrew 的信息請打開 Building Better Software。