CA1200:不要使用带前缀的 cref 标记

项目
09/06/2023

属性	值
规则 ID	CA1200
标题	不要使用带前缀的 cref 标记
类别	文档
修复是中断修复还是非中断修复	非中断
在 .NET 9 中默认启用	否

原因

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 注释来记录代码

通过