插入 XML 註解以產生文件

本文說明 Visual Studio 如何透過自動產生標準的 XML 文件註解結構，幫助你記錄像是類別和方法等程式碼元素。 在編譯時，你可以產生包含文件註解的 XML 檔案。

你可以將編譯器產生的 XML 檔案與 .NET 組合語言一同發佈，讓 Visual Studio 及其他 IDE 能使用 IntelliSense 快速顯示型別與成員資訊。 你也可以用 DocFX 和 Sandcastle 等工具執行 XML 檔案，產生 API 參考網站。

備註

自動插入 XML 文件註解結構的 Insert Comment 指令可在 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>插入留言。
   • 從右鍵選單中，選擇>「插入註解（Snippet）」。

   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++）
• 程式碼產生