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

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

C# 語言參考資料記錄了 C# 語言最新版本。同時也包含即將推出語言版本公開預覽功能的初步文件。

文件中標示了語言最近三個版本或目前公開預覽版中首次引入的任何功能。

提示

欲查詢某功能何時首次在 C# 中引入，請參閱 C# 語言版本歷史的條目。

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

為了一致性，請記錄所有公開可見的類型及其公開成員。
你也可以透過 XML 註解來記錄私人成員。然而，這種做法會揭露你圖書館內部（可能保密的）運作。
類型與其成員至少應該具有 <summary> 標籤。
用完整句子、句點結尾來撰寫文件文本。
部分類別完全接受支援，且文件資訊會串連為每個型別的單一項目。如果部分成員的兩個宣告都有文件註解，則實作宣告的註解會寫入輸出 XML。

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

文件必須是語式正確的 XML。如果 XML 格式不正確，則編譯器會產生警告。文件檔案包含的註解指出發生錯誤。
其中一些建議的標記具有特殊意義：
- 標籤 <param> 描述參數。如果你使用這個標籤，編譯器會驗證參數的存在，且所有參數都在文件中描述。如果驗證失敗，則編譯器會發出警告。
- 將屬性附加 cref 到任意標籤上以參考程式碼元素。編譯器會驗證此程式碼項目存在。如果驗證失敗，則編譯器會發出警告。編譯器在尋找 using 屬性中所述的類型時，會遵守任何 cref 指示詞。
- Visual Studio 內部的 IntelliSense 使用 <summary> 標籤來顯示關於某個類型或成員的額外資訊。
 
 注意
 
 XML 檔案並未提供關於類型與成員的完整資訊（例如，它不包含任何類型資訊）。若要取得類型或成員的完整資訊，請搭配使用文件檔案與實際類型或成員上的反映。
開發人員可以自由建立自己的標記集合。編譯器將這些標籤複製到輸出檔案。

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

編譯器會驗證下列清單中後面接著單一 * 的元素的語法。 Visual Studio 提供 IntelliSense 處理編譯器驗證的標籤，以及以下列表中所有後面跟 ** 的標籤。除了上述標籤外，編譯器與Visual Studio還會驗證 、、、  以及 <a> 標籤。編譯器也會驗證 <tt>，而這是已遭取代的 HTML。

注意

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

用於多個元素的一般標記 - 這些標記是任何 API 的基本集。
- <summary>：此元素的值會在 IntelliSense 中顯示於 Visual Studio。
- <remarks> **
用於成員的標記 - 記載方法和屬性時，會使用這些標記。
- <returns>：此元素的值會在 IntelliSense 中顯示於 Visual Studio。
- <param> *：此元素的值會在 IntelliSense 中以 Visual Studio 顯示。
- <paramref>
- <exception> *
- <value>：此元素的值會在 IntelliSense 中顯示於 Visual Studio。
格式化文件輸出 - 這些標記提供工具的格式化指示，而這些工具會產生文件。
- <para>
- <list>
- <c>
- <code>
- <example> **
- 
- 
- 
-  
- <a>
重複使用文件文字 - 這些標記所提供的工具可讓您更輕鬆地重複使用 XML 註解。
- <inheritdoc> **
- <include> *
產生連結和參考 - 這些標記會產生其他文件的連結。
- <see> *
- <seealso> *
- cref
- href
泛型型別與方法標籤 - 僅在通用型別與方法上使用此標籤。
- <typeparam> *：Visual Studio 中的 IntelliSense 顯示此元素的值。
- <typeparamref>

注意

你無法將文件註解套用到命名空間。

如果您想要讓角括弧出現在文件註解的文字中，則請使用 < 和 > 的 HTML 編碼，其分別為 < 和 >。以下範例展示了此編碼方式。

/// <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、物件瀏覽器以及程式碼註解網頁報告中。

`<paramref>`

<paramref name="name"/>

name：要參照的參數名稱。以引號 (") 括住名稱。

這個 <paramref> 標籤提供了一種方式，表示程式碼註解中的某個字，例如 a <summary> 或 <remarks> block，指涉參數。你可以處理 XML 檔案，以不同方式格式化這個單字，例如使用粗體或斜體字體。

`<exception>`

<exception cref="member">description</exception>

cref = “member”：指的是目前編譯環境中可用的例外。編譯器會檢查指定的例外狀況是否存在，並將 member 轉譯為輸出 XML 中的標準項目名稱。 member 必須出現在引號內 (")。

這個 <exception> 標籤讓你能指定成員可以拋出哪些例外。將此標籤套用到方法、屬性、事件和索引器的定義上。

`<value>`

<value>property-description</value>

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

`<safety>`

<safety>description</safety>

使用標籤<safety>來記錄呼叫需求不安全成員必須遵守的合約，該合約是根據更新後的記憶體安全模型、C# 15 與 .NET 11 的預覽功能。當更新規則啟用時，標記成員 unsafe 會將審核安全義務推給呼叫者，而區塊會 <safety> 說明呼叫者必須保證的條件。更新後的規則可在編 updated-memory-safety-rules 譯器功能預覽中啟用;請參見啟用更新後的記憶體安全規則。你也可以在欄位<safety>上放置unsafe區塊，記錄該包圍型別所維持的不變量。

C# 編譯器不會辨識或處理這個 <safety> 標籤。像任何自訂標籤一樣，編譯器會逐字複製到輸出的 XML 檔案中。記憶體安全分析器可能會標記缺少 <safety> 區塊的 requires-unsafe 成員，但編譯器本身不會強制執行該區塊的存在或內容。欲了解更多資訊，請參閱安全文件。

格式化文件輸出

`<para>`

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

在標籤內使用 <para> 標籤，例如 <summary>、 <remarks>、或 <returns>，來為文字增添結構。 <para> 標記會建立雙空格段落。如果您想要單一空格段落，則請使用   標記。

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

/// <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>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</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>text</b>

使用  標籤讓文件評論中的文字變得粗體。編譯器和 Visual Studio 會驗證這個 HTML 格式標籤。格式化文字會出現在 IntelliSense 中並產生文件。

``

<i>text</i>

使用  標籤將文件註解中的文字變成斜體。編譯器和 Visual Studio 會驗證這個 HTML 格式標籤。格式化文字會出現在 IntelliSense 中並產生文件。

``

<u>text</u>

在文件評論中用  標籤劃線。編譯器和 Visual Studio 會驗證這個 HTML 格式標籤。格式化文字會出現在 IntelliSense 中並產生文件。

` `

Line one<br/>Line two

使用標籤   在文件註解中插入換行。當您想要單一空格段落，而不是 <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' />
<include file='filename' path='tagpath[@attribName]' />
<include file='filename' path='tagpath[@attribName="attribValue"]' />
<include file='filename' path='tagpath[@attribName1="attribValue1"][@attribName2="attribValue2"][@attribName3]' />

建議：

<include file='filename' path='tagpath[@name="id"]' />

filename：包含文件的 XML 檔案名稱。用相對於原始碼檔案的路徑來限定檔名。請將 filename 括在單引號 (' ') 內。
path：該 filename 頁面中標籤的路徑會導向 XML 註解。路徑可以包含一個或多個屬性，例如 name，但並非必須。屬性可以有像 id，但也不是必須的。將路徑（包括可能的屬性）以單引號（' '）包圍。
attribName， attribName1：可選屬性的名稱。
attribValue， attribValue1：屬性的可選值。如果你沒有指定值，搜尋註解 filename時可以接受任何值。將屬性值以引號（「）包起來」。

透過使用這個 <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 這是設計給程式碼參考，不會產生可點擊的外部網址連結。
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 2026-09-10

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

一般標記

<summary>

<remarks>

文件成員

<returns>

<param>

<paramref>

<exception>

<value>

<safety>

格式化文件輸出

<para>

<list>

<c>

<code>

<example>

<b>

<i>

<u>

<br/>

<a>