為 C# 代碼生成 API 文檔(自譯)


原文地址:http://broadcast.oreilly.com/2010/09/build-html-documentation-for-y.html#comments

Sandcastle 功能概述

      如果您使用過的程序集中,帶有詳細的 API 說明文檔,並且文檔的格式和 MSDN 上的一樣,您將發現這樣 API 說明文檔的是多么的方便。生成類似的 HTML 格式文檔的方法有很多,不過,我發現其中最簡單的方法是使用 Sandcastle 工具來生成這樣的 API 文檔。Sandcastle 是微軟開發的一款開源的文檔生成器,它可以讀取您的程序集(DLL 和 EXE 文件)和 XML 注釋文件,而且能自動生成相應的 HTML 格式的文檔。Sandcastle 既是一款非常靈活的工具,同時它也是一款非常復雜的工具。不過幸運的是,還有另外一款與之類似的輔助工具, Sandcastle Help File Builder,這個工具讓您在幾分鍾之內就可以很容易地獲取和運行 Sandcastle。

      本教程將帶您創建簡單的 HTML 格式的類描述文檔,下面是我們接下來要做的:

  1. 步驟一: 安裝 Sandcastle 和 Sandcastle Help File Builder
  2. 步驟二: 創建一個名稱為 Guy.cs 的 C# 代碼文件
  3. 步驟三: 把 C# 代碼編譯成 Guy.dll 程序集
  4. 步驟四: 安裝 Sandcastle Help File Builder 項目
  5. 步驟五: 運行 Sandcastle

      備注,我們還需完成一些額外的事情:

步驟一: 安裝 Sandcastle 和 Sandcastle Help File Builder

      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版本):

  • 使用下載鏈接 Sandcastle CodePlex 頁面 來下載和運行最新的穩定版的安裝程序
  • 對 Sandcastle Help File Builder 做相同的操作
  • 確保您注意到了 Sandcastle 和 Sandcastle Help File Builder 的安裝目錄。這里將它們被安裝在以下路徑 D:\Program Files 或者 D:\Program Files(x86)— Sandcastle 被安裝在名稱為 Sandcastle 文件夾下,SHFB 被安裝在 EWSoftware\Sandcastle Help File Builder 文件路徑下。

      注意,安裝 Sandcastle 和 Sandcastle Help File Builder 后,您還可以把它們安裝目錄下面的內容全部復制到另外一個目錄下,從而把它們的安裝路徑改成你想要的路徑,在新目錄下,它們依然可以被啟動並使用。如果您工作的機器被鎖住,您不能用它來安裝程序 — 為了安全,辦公室里的很多電腦都會被鎖住 — 這個功能將很有用。當您在一個構建服務器上運行一個連續的生成命令,來生成 HTML 文檔,但是您又沒有管理員權限時,它也可以派上用場。

步驟二: 創建一個名稱為 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。 在頁面的頂端,您會得到一個警告信息:                 

Screenshot - HTML help in IE - ActiveX warning.png

      點擊它並從菜單中選擇“允許阻止的內容...”,這樣做后,您將會看到新生成的 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 文件:

  1. 啟動 Visual Studio 並 創建一個新的名稱為 GuyTest 的類庫 (GuyTest.csproj)
  2. 刪除 Visual Studio 自動為您添加的 Class1.cs文件
  3. 在資源管理器中右擊 GuyTest 並添加一個已存在的項目到您的工程中。導航到 Guy.cs 文件並添加它
  4. 在資源管理器中展開“屬性”文件夾並刪除 AssemblyInfo.cs 文件
  5. 添加另外一個存在的項目到您的工程 — 這次導航到 AssemblyInfo.cs,把它拖動到項目的“屬性”文件夾下,然后包含到項目中

      還有另外一件事您需要做。 在解決方案資源管理器中,右擊 GuyTest  並在菜單欄中選擇屬性 打開項目屬性頁。點擊“生成”標簽,並 選中“ XML 文檔文件”這個的復選框。 指定其文件名為 Guy.xml。             

Screenshot - Visual Studio - XML Documentation.png

      點擊工具欄上的全部保存按鈕來保存您的項目。現在這個項目生成的 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


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM