在文件產生中插入 XML 註解

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

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

注意

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

啟用文件產生

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

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

或者，您可以將 GenerateDocumentationFile 或 DocumentationFile 屬性新增至 .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 元素和樣式，將游標停留在程式碼上方時，會在「快速諮詢」中呈現。 這些元素包含斜體或粗體樣式、分項或編號清單，以及可點選的 cref 或 href 連結。

例如，在 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 上方時，「快速諮詢」窗格隨即出現，如下所示：

相關內容

• 文件註解
• Visual Basic 中的 XML 文件
• 註解 (C++)
• XML 文件 (Visual C++)
• 程式碼產生