共用方式為


在文件產生中插入 XML 註解

本文描述了 Visual Studio 可如何藉由自動產生標準 XML 文件註解結構的方式來協助您記錄程式碼項目 (如類別和方法)。 編譯時間中,您可以產生包含文件註解的 XML 檔案。

您可以隨著 .NET 組件一起發佈編譯器產生的 XML 檔案,如此 Visual Studio 和其他 IDE 便可以使用 IntelliSense 來顯示類型和成員的快速資訊。 您也可以透過 DocFXSandcastle 這類工具執行 XML 檔案來產生 API 參照網站。

注意

會自動插入 XML 文件註解結構的插入註解命令可在 C#Visual Basic 中使用。 若為 C++,您可以手動插入 XML 文件註解,且仍可在編譯時間產生 XML 文件檔案。

啟用文件產生

若要啟用文件產生,請在專案屬性的組建>輸出索引標籤上,選取產生包含 API 文件的檔案核取方塊。

根據預設,系統會在與組件相同的目錄中產生與您的組件名稱相同、且具有 .xml 副檔名的文件。 如果您想要設定檔案的非預設名稱或位置,請輸入或瀏覽至 XML 文件檔案路徑下的替代位置。

若要啟用文件產生,請在專案屬性的組建>輸出區段中,選取 XML 文件檔案核取方塊。

根據預設,系統會在與組件相同的目錄中產生與您的組件名稱相同、且具有 .xml 副檔名的文件。 如果您想要設定檔案的非預設名稱或位置,請輸入或瀏覽至替代位置。

或者,您可以將 GenerateDocumentationFileDocumentationFile 屬性新增至 .csproj.vbproj.fsproj 檔案。 將 GenerateDocumentationFile 設為 true,以產生具有預設名稱和位置的文件檔案。 使用 DocumentationFile 屬性來指定不同的名稱或位置。

如果您單獨使用 DocumentationFile 或將 GenerateDocumentationFile 屬性設定為 true,則會產生具有指定名稱和位置的文件檔案。 不過,如果您將 GenerateDocumentationFile 設定為 false,即使您設定了 DocumentationFile 屬性,也不會產生任何文件檔案。

啟用註解插入鍵盤快速鍵

您可以設定註解選項來讓您在 C# 中輸入 /// 或在 Visual Basic 中輸入 ''' 之後,自動插入 XML 註解結構。

  1. 在 Visual Studio 選單列上,選擇工具>選項
  2. 選項對話框中,瀏覽至文字編輯器>C# (或 Visual Basic) >進階
  3. 註解區段下,選取或取消選取產生 \\\ 的 XML 文件註解 (或 ''')。

自動插入 XML 註解

  1. 在 Visual Studio 中,將游標放在您想要記載的元素 (例如方法) 上方。

  2. 執行下列其中一項動作:

    • 如果已啟用自動註解插入快速鍵,請在 C# 中輸入 ///,或在 Visual Basic 中輸入 '''
    • 編輯功能表上,選擇 IntelliSense>插入註解
    • 以滑鼠右鍵按一下或在特色選單中,選擇片段>插入註解

    XML 註解結構會立即在程式碼項目上方產生。 例如,為下列 GetUserName 方法註解時,範本會產生 <summary> 元素、參數的 <param> 元素,以及可記錄傳回值的 <returns> 元素。

    /// <summary>
    /// 
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    public string GetUserName(int id)
    {
        return "username";
    }
    
    ''' <summary>
    ''' 
    ''' </summary>
    ''' <param name="id"></param>
    ''' <returns></returns>
    Public Function GetUserName(id As Integer) As String
        Return "username"
    End Function
    
  3. 為每個 XML 元素輸入描述,以完整記錄程式碼。 例如:

     /// <summary>
     /// Gets the username associated with the specified ID.
     /// </summary>
     /// <param name="id">The unique user ID.</param>
     /// <returns>A string containing the username for the specified ID.</returns>
     public string GetUserName(int id)
     {
         return "username";
     }
    

您可以在註解中使用 XML 元素和樣式,將游標停留在程式碼上方時,會在「快速諮詢」中呈現。 這些元素包含斜體或粗體樣式、分項或編號清單,以及可點選的 crefhref 連結。

例如,在 C# 程式檔案中輸入下列程式碼:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

當您將游標停留在 GetUserName 上方時,「快速諮詢」窗格隨即出現,如下所示:

顯示具有可點選連結、編號清單和斜體和粗體格式的樣式標記之已完成註解的螢幕擷取畫面。