如何:在文件產生中插入 XML 註解

Visual Studio 可藉由自動產生標準 XML 文件註解結構,來幫助您記錄諸如類別和方法的程式碼項目。 編譯時間中,您可以產生包含文件註解的 XML 檔案。 若要啟用該選項,請在專案屬性的 [組建 輸出] 索引標籤上,選取 [產生包含 API 的檔案 > ] 檔。

提示

如果您想要設定檔檔案的非預設名稱和位置,請將 DocumentationFile 屬性新增至 .csproj. vbproj>.fsproj 檔案。

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

注意

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

為程式碼項目插入 XML 註解

  1. 將文字游標放在您想要記載的元素 (例如方法) 上方。

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

    • 在 C# 中鍵入 ///,或在 Visual Basic 中鍵入 '''

    • 從 [編輯]功能表上,選擇 [IntelliSense] > [插入註解]

    • 從滑鼠右鍵按一下或在程式碼專案上方或上方的內容功能表中,選擇 [代碼 > 插入批註]

    XML 範本會立即在程式碼項目上方產生。 例如,批註方法時,它會產生 <summary> 元素、 <param> 每個參數的專案,以及用 <returns> 來記錄傳回值的元素。

    XML 註解範本 - C#

    XML 註解範本 - Visual Basic

  3. 為每個 XML 項目輸入描述,以完整記錄程式碼項目。

    顯示已完成批註的螢幕擷取畫面。

您可以使用 XML 批註中的樣式,將滑鼠游標移到專案上方時,將會在快速諮詢中轉譯。 這些樣式包括:斜體、粗體、專案符號及可點按的連結。

顯示已完成批註的螢幕擷取畫面,其中包含斜體、粗體、專案符號及可點按連結的樣式標記。

注意

在 C# 鍵入 /// 或在 Visual Basic 鍵入 ''' 之後,會有切換 XML 文件註解的選項。 從功能表列中選擇 [工具 > 選項],以開啟 [選項] 對話方塊。 然後,流覽至 [文字編輯器]、[ > c # ] 或 [基本] > Advanced。 在 [編輯器說明] 區段中,尋找 [產生 XML 文件註解] 選項。

另請參閱