Edit

CA1200: Avoid using cref tags with a prefix

  • Article
Property Value
Rule ID CA1200
Title Avoid using cref tags with a prefix
Category Documentation
Fix is breaking or non-breaking Non-breaking
Enabled by default in .NET 8 No

Cause

The cref tag in an XML documentation comment uses a prefix.

Rule description

The cref attribute in an XML documentation tag means "code reference". It specifies that the inner text of the tag is a code element, such as a type, method, or property. Avoid using cref tags with prefixes, because it prevents the compiler from verifying references. It also prevents the Visual Studio integrated development environment (IDE) from finding and updating these symbol references during refactorings. It is recommended that you use the full syntax without prefixes to reference symbol names in cref tags.

How to fix violations

To fix a violation of this rule, remove the prefix from the cref tag. For example, the following two code snippets show a violation of the rule and how to fix it:

// 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() { }
}

When to suppress warnings

It's safe to suppress this warning if the code reference must use a prefix because the referenced type is not findable by the compiler. For example, if a code reference references a special attribute in the full framework, but the file compiles against the portable framework, you can suppress this warning.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

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

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

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

For more information, see How to suppress code analysis warnings.

See also