CA1200: избегайте использования тегов cref с префиксом

  • Статья
Свойство Значение
Идентификатор правила CA1200
Заголовок Избегайте использования тегов cref с префиксом
Категория Документация
Исправление является критическим или не критическим Не критическое
Включен по умолчанию в .NET 8 No

Причина

Тег cref в комментарии XML-документации использует префикс.

Описание правила

Атрибут cref в теге XML-документации означает "code reference" (кодовая ссылка). Он указывает, что текст внутри тега представляет собой элемент кода, например тип, метод или свойство. Старайтесь не использовать теги cref с префиксами, так как это не позволяет компилятору проверять ссылки. Это также мешает поиску и обновлению этих символьных ссылок во время рефакторинга в интегрированной среде разработки (IDE) Visual Studio. Рекомендуется использовать полный синтаксис без префиксов для ссылки на имена символов в тегах 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

Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.

См. также