CA1200：請避免使用具有前置詞的 cref 標記

文章
11/14/2023

屬性	值
規則識別碼	CA1200
標題	請避免使用具有前置詞的 cref 標記
類別	文件
修正程式是中斷或非中斷	不中斷
預設在 .NET 8 中啟用	No

原因

XML 檔批註中的 cref 標記會使用前置詞。

檔案描述

在 XML 文件標籤中的 cref 屬性表示「程式碼參考」。它會指定標記的內部文字是程式碼項目，例如類型、方法或屬性。避免搭配前置詞使用 cref 標籤，因為其會讓編譯器無法驗證參考。其也會讓 Visual Studio 整合式開發環境 (IDE) 無法在重構期間尋找及更新這些符號參考。建議您使用不含前置詞的完整語法來參考 cref 標記中的符號名稱。

如何修正違規

若要修正此規則的違規，請從 cref 標記中移除前置詞。例如，下列兩個程式碼片段會顯示違反規則，以及如何修正它：

// Violates CA1200
/// <summary>
/// Type <see cref="T:C" /> contains method <see cref="F:C.F" />
/// </summary>
class C
{
    public void F() { }
}

// Does not violate CA1200
/// <summary>
/// Type <see cref="C" /> contains method <see cref="F" />
/// </summary>
class C
{
    public void F() { }
}

隱藏警告的時機

如果程式碼參考必須使用前置詞，則隱藏此警告是安全的，因為編譯器找不到參考的類型。例如，如果程式碼參考參考完整架構中的特殊屬性，但檔案會針對可攜式架構編譯，您可以隱藏此警告。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

#pragma warning disable CA1200
// The code that's violating the rule is on this line.
#pragma warning restore CA1200

若要停用檔案、資料夾或專案的規則，請在組態檔中將其嚴重性設定為。 none

[*.{cs,vb}]
dotnet_diagnostic.CA1200.severity = none

如需詳細資訊，請參閱如何隱藏程式碼分析警告。

另請參閱

使用 XML 批註記錄程式碼

分享方式：