共用方式為

建議用於 C# 文件註解的 XML 標記

C# 文件註解使用 XML 元素來定義輸出文件的結構。 此功能的其中一個結果是您可以在文件註解中新增任何有效的 XML。 C# 編譯器會將這些元素複製至輸出 XML 檔案。 雖然您可以在註解中使用任何有效的 XML (包括任何有效的 HTML 元素)，但基於許多原因，建議您記載程式碼。

接下來是一些建議、一般使用案例，以及在 C# 程式碼中使用 XML 文件標記時應該知道的事項。 雖然您可以將任何標記放入您的文件註解，但本文描述最常見語言建構的建議標記。 在所有情況下，您應該遵守這些建議：

  • 為保持一致性，應該記載所有公開可見的類型和其成員。
  • 也可以使用 XML 註解記錄私用成員。 不過，這會公開您程式庫的內部 (可能是機密) 運作。
  • 類型與其成員至少應該具有 <summary> 標籤。
  • 應該使用結尾為句號的完整句子來撰寫文件文字。
  • 部分類別完全接受支援，且文件資訊會串連為每個型別的單一項目。 如果部分成員的兩個宣告都有文件註解，則實作宣告的註解會寫入輸出 XML。

XML 文件的開頭是 ///。 當您建立新的專案時，範本會為您在開頭放入幾行 ///。 這些註解在處理時有一些限制：

  • 文件必須是語式正確的 XML。 如果 XML 格式不正確，則編譯器會產生警告。 文件檔案包含的註解指出發生錯誤。
  • 其中一些建議的標記具有特殊意義：
    • <param> 標記用來描述參數。 如果使用，編譯器會驗證參數存在，而且所有參數在文件中都有描述。 如果驗證失敗，則編譯器會發出警告。
    • cref 屬性可以附加至任何標記，以參考程式碼元素。 編譯器會驗證此程式碼項目存在。 如果驗證失敗，則編譯器會發出警告。 編譯器在尋找 using 屬性中所述的類型時，會遵守任何 cref 指示詞。
    • Visual Studio 中的 IntelliSense 使用 <summary> 標記來顯示類型或成員的其他資訊。

      注意

      XML 檔案不會提供類型和成員的完整資訊 (例如，它不會包含任何類型資訊)。 若要取得類型或成員的完整資訊，請搭配使用文件檔案與實際類型或成員上的反映。

  • 開發人員可以自由建立自己的標記集合。 編譯器將這些標籤複製到輸出檔案。

某些建議標記可以用於任何語言元素。 其他則具有更具體的使用方式。 最後，某些標記用來格式化文件中的文字。 本文描述依使用方式組織的建議標記。

編譯器會驗證下列清單中後面接著單一 * 的元素的語法。 Visual Studio 為編譯器所驗證的標記提供 IntelliSense，以及下列清單中後面接著 ** 的所有標記。 除了此處所列的標記之外，編譯器和 Visual Studio 還會驗證 <b>、<i>、<u>、<br/> 和 <a> 標記。 編譯器也會驗證 <tt>，而這是已遭取代的 HTML。

注意

之類的 <br/> HTML 標籤對於在檔批註中格式化很有用。 標記 <br/> 會建立換行符，而其他 HTML 標記則提供文字格式設定。 這些標記適用於 IntelliSense 工具提示和產生的文件。

注意

文件註解不能套用至命名空間。

如果您想要讓角括弧出現在文件註解的文字中，則請使用 < 和 > 的 HTML 編碼，其分別為 &lt; 和 &gt;。 此編碼顯示於下列範例中。

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

一般標記

<summary>

<summary>description</summary>

<summary> 標記應該用來描述類型或類型成員。 用於 <remarks> 在類型描述中加入補充資訊。 使用 cref 屬性，讓 DocFX 和 Sandcastle 這類文件工具針對程式碼元素建立文件頁面的內部超連結。 <summary> 標籤的文字會顯示在 IntelliSense 和 [物件瀏覽器] 視窗中。

<remarks>

<remarks>
description
</remarks>

標籤 <remarks> 用於新增關於某個類型或類型成員的資訊，補充以 <summary>。 這項資訊會顯示在 [物件瀏覽器] 視窗中。 此標籤可能包含更冗長的說明。 您可能會發現，使用 Markdown 的 CDATA 部分會讓它的撰寫更便利。 docfx 這類工具會處理 CDATA 區段中的 Markdown 文字。

文件成員

<returns>

<returns>description</returns>

<returns> 標記應該用於方法宣告的註解中，以描述傳回值。

<param>

<param name="name">description</param>
  • name：方法參數的名稱。 以引號 (") 括住名稱。 參數的名稱必須符合 API 簽章。 如果不涵蓋一或多個參數，編譯器會發出警告。 如果 name 的值不符合方法宣告中的正式參數，則編譯器也會發出警告。

<param> 標記應該用於方法宣告的註解中，以描述該方法的其中一個參數。 若要記載多個參數，請使用多個 <param> 標記。 <param> 標記的文字會顯示在 IntelliSense、物件瀏覽器和程式碼註解 Web 報告中。

<paramref>

<paramref name="name"/>
  • name：要參照的參數名稱。 以引號 (") 括住名稱。

<paramref> 標記提供一種方法來表示在程式碼註解中的字組，例如 <summary> 或 <remarks> 區塊中的字組指的是參數。 若要以某種不同方式 (例如，粗體或斜體字型) 格式化這個字組，您可以處理 XML 檔案。

<exception>

<exception cref="member">description</exception>
  • cref = "member"：可從目前編譯環境所取得例外狀況的參考。 編譯器會檢查指定的例外狀況是否存在，並將 member 轉譯為輸出 XML 中的標準項目名稱。 member 必須出現在引號內 (")。

<exception> 標記可讓您指定可以擲回的例外狀況。 這個標記可以套用至方法、屬性、事件和索引子的定義。

<value>

<value>property-description</value>

<value> 標記可讓您描述屬性所代表的值。 當你在 Visual Studio .NET 開發環境中透過程式碼精靈新增屬性時，它會為 <summary> 該新屬性加上一個標籤。 您可以手動新增 <value> 標記，以描述屬性所代表的值。

格式化文件輸出

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

這個 <para> 標籤用於標籤內，例如 <summary>、 <remarks>、 或 <returns>，並能讓你為文字添加結構。 <para> 標記會建立雙空格段落。 如果您想要單一空格段落，則請使用 <br/> 標記。

以下範例顯示<para>和<br/>之間的差異：

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

<listheader> 區塊用來定義資料表或定義清單的標題資料列。

定義資料表時：

  • 您只需要提供標題中 term 的項目。
  • 清單中的每個項目都是使用 <item> 區塊所指定。 對每個 item 而言，您只需為 description 提供項目。

建立定義清單時：

  • 您必須提供標題中 term 的項目。
  • 清單中的每個項目都是使用 <item> 區塊所指定。 每個 item 都必須同時包含 term 和 description。

清單或資料表可以有所需的多個 <item> 區塊。

<c>

<c>text</c>

<c> 標記可讓您指出應該將描述內的文字標記為程式碼。 用 <code> 來表示多行代碼。

<code>

<code>
    var index = 5;
    index++;
</code>

<code> 標記用來指出多行程式碼。 用 <c> 來表示描述中單行文字應標記為代碼。

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

<example> 標記可讓您指定如何使用方法或其他程式庫成員的範例。 一個常見的例子是使用標籤 <code> 。

<b>

<b>text</b>

標記 <b> 是用來在檔批註內將文字設為粗體。 編譯程式和Visual Studio會驗證此HTML格式標記，格式化的文字會出現在IntelliSense和產生的檔中。

<i>

<i>text</i>

標記 <i> 是用來在檔批註內進行文字斜體。 編譯程式和Visual Studio會驗證此HTML格式標記，格式化的文字會出現在IntelliSense和產生的檔中。

<u>

<u>text</u>

標記 <u> 用來在檔批註內加上文字底線。 編譯程式和Visual Studio會驗證此HTML格式標記，格式化的文字會出現在IntelliSense和產生的檔中。

<br/>

Line one<br/>Line two

標記 <br/> 是用來在檔批註中插入換行符。 當您想要單一空格段落，而不是 <para> 建立雙空格段落的標記時，請使用這個標記。

<a>

<a href="https://example.com">Link text</a>

標記 <a> 可用來在檔批註內建立超連結。 屬性 href 會指定要連結的 URL。 編譯程式和Visual Studio會驗證此HTML格式標記。

注意

編譯程式也會驗證 <tt> 標記，這是已被取代的 HTML。 請改用標記 <c> 進行內嵌程式代碼格式設定。

重複使用文件文字

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

繼承基底類別、介面和類似方法的 XML 註解。 使用 inheritdoc 可消除不想要的重複 XML 註解複製和貼上，並自動讓 XML 註解保持同步。 將 <inheritdoc> 標籤加入型別後，所有成員都會繼承註解。

  • cref：指定要向其繼承文件的成員。 目前的成員的已定義標籤不會遭到已繼承的標籤所覆寫。
  • path：會使節點集顯示的 XPath 運算式查詢。 您可以使用此屬性來篩選標記，以包括或排除繼承的文件。

注意

Visual Studio 會針對覆寫或實作已記載成員的未記載成員，提供 XML 檔的自動繼承。 這項功能會在 IntelliSense 和 Quick Info 中顯示繼承的文件，而不需要 <inheritdoc> 標記。 不過，此自動繼承僅適用於 Visual Studio IDE，而且不會影響編譯程式所產生的 XML 檔檔。

針對您散發的連結庫中的公用 API，您應該明確使用 <inheritdoc> 標記或提供完整的檔，以確保產生的 XML 檔檔包含連結庫取用者的所有必要資訊。

在基底類別或介面中新增 XML 註解，並讓 inheritdoc 將註解複製至實作類別。 將 XML 註解新增至同步方法，並讓 inheritdoc 將註解複製至相同方法的非同步版本。 如果您想要從特定成員複製註解，則請使用 cref 屬性來指定成員。

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename：包含文件的 XML 檔案名稱。 檔案名稱可以採用的原始程式碼檔的相對路徑。 請將 filename 括在單引號 (' ') 內。
  • tagpath：filename 中導致 name 標記的標記路徑。 請將路徑括在單引號 (' ') 內。
  • name：標籤中位在註解前面的名稱規範；name 有 id。
  • id：位在註解前面的標記識別碼。 以引號 (") 括住識別碼。

<include> 標記可讓您參考另一個檔案中描述原始程式碼中類型和成員的註解。 包括外部檔案是將文件註解直接放在原始程式碼檔案中的替代方案。 將文件放入個別檔案，即可將原始檔控制套用至與原始程式碼不同的文件。 一個人可以簽出原始程式碼檔，而且其他人可以簽出文件檔。<include> 標記使用 XML XPath 語法。 如需自訂 <include> 用法的方式，請參閱 XPath 文件。

例如，下列原始程式碼會使用 <include> 標籤來包含備註。 檔案路徑是相對於來源的。

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Include 檔案的 XML 來源會顯示在下列範例中。 其結構與 C# 編譯器所產生的 XML 檔案相同。 XML 檔案可以包含多個方法或類型的文字，只要 XPath 運算式可以識別它們即可。

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

此方法的 XML 輸出會顯示在下列範例中：

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

提示

.NET 執行階段小組會在其文件中廣泛使用 <include> 標籤。 您可以藉由搜尋 dotnet/runtime 存放庫來查看許多範例。

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member"：可從目前編譯環境呼叫的成員或欄位參考。 編譯器會檢查指定的程式碼項目是否存在，並將 member 傳遞給輸出 XML 中的項目名稱。 將成員置於引號 (") 內。 您可以使用個別的結尾標記，以針對 "cref" 提供不同的連結文字。
  • href="link"：給定 URL 的可按一下連結。 例如，<see href="https://github.com">GitHub</see> 會產生可按一下連結，其中包含連結至 GitHub 的文字 https://github.com。 請使用 href 而非 cref 來連結至外部網頁，因為 cref 是為程式碼參考而設計的，並不會為外部 URL 建立可點選的連結。
  • langword="keyword"：語言關鍵字，例如 true 或其中一個其他有效關鍵字。

<see> 標記可讓您在文字內指定連結。 用來 <seealso> 表示文字應置於「參見」區塊。 使用 cref 屬性，以針對程式碼元素建立文件頁面的內部超連結。 您可以包括類型參數，以指定泛型類型或方法的參考，例如 cref="IDictionary{T, U}"。 此外，href 是有效屬性，作用是超連結。

以下範例顯示當參考外部 URL 時，cref 和 href 之間的差異：

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member"：可從目前編譯環境呼叫的成員或欄位參考。 編譯器會檢查指定的程式碼項目是否存在，並將 member 傳遞給輸出 XML 中的項目名稱。 member 必須出現在引號內 (")。
  • href="link"：給定 URL 的可按一下連結。 例如，<seealso href="https://github.com">GitHub</seealso> 會產生可按一下連結，其中包含連結至 GitHub 的文字 https://github.com。

<seealso> 標記可讓您指定要顯示在＜請參閱＞一節中的文字。 請使用 <see> 文字中指定連結。 您無法以巢狀方式將 seealso 標籤放在 summary 標籤內。

cref 屬性

cref 屬性在 XML 文件標記中表示「程式碼參考」。它會指定標記的內部文字是程式碼項目，例如類型、方法或屬性。 DocFX 和 Sandcastle 這類文件工具使用 cref 屬性自動產生記錄類型或成員的頁面超連結。

href 屬性

href 屬性表示網頁的參考。 您可以使用它直接參考 API 或程式庫的線上文件。 當您需要在文件註解中連結至外部 URL 時，請使用 href 而不是 cref，以確保在 IntelliSense 圖樣提示和產生的文件中連結可被點選。

泛型類型和方法

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult：類型參數的名稱。 以引號 (") 括住名稱。

<typeparam> 標記應該用於泛型型別或方法宣告的註解中，以描述型別參數。 新增泛型型別或方法之每個型別參數的標記。 <typeparam> 標籤的文字會顯示在 IntelliSense。

<typeparamref>

<typeparamref name="TKey"/>
  • TKey：類型參數的名稱。 以引號 (") 括住名稱。

使用這個標記，讓文件檔案的取用者以某種明顯方式格式化單字，例如斜體。

使用者定義標記

本文所述的所有標籤都代表 C# 編譯器所辨識的標籤。 不過，使用者可以定義自己的標記。 像 Sandcastle 這類工具支援額外標籤如 <event> 和 <note>，甚至支援 命名空間的紀錄。 自訂或內部文件產生工具也可以與標準標記搭配使用，而且可以支援從 HTML 到 PDF 的多個輸出格式。

  • Last updated on