CA2252: согласие на использование предварительных версий функций перед ее использованием

Статья
04/08/2023

Свойство	Значение
Идентификатор правила	CA2252
Заголовок	Перед использованием функций предварительной версии
Категория	Использование
Исправление является критическим или не критическим	Не критическое
Включен по умолчанию в .NET 9	Как ошибка

Причина

Клиент использует API предварительных версий в сборках, для которых не указано согласие на такое использование локально, на уровне модуля или сборки.

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

При использовании API или сборки с атрибутом RequiresPreviewFeaturesAttribute это правило проверяет, предоставлено ли для сайта согласие на использование предварительных версий функций. Согласие на использование предварительных версий функций считается предоставленным для сайта, если выполняется любое из следующих условий:

сайт находится в области действия заметки RequiresPreviewFeaturesAttribute;
сайт является частью сборки или модуля, для которых уже есть согласие на использование предварительных версий функций.

На следующем рисунке вы видите пример диагностического сообщения CA2252.

Здесь Lib — это тип предварительной версии, созданный в методе Main. При этом сам Main не помечен как метод предварительной версии, поэтому для двух вызовов конструкторов внутри Main создаются диагностические сообщения.

Устранение нарушений

Устранить это нарушение можно двумя способами.

Поместите сайт вызова в область действия заметки, добавив в родительский элемент заметку RequiresPreviewFeaturesAttribute. В предыдущем примере нужно пометить APreviewMethod атрибутом RequiresPreviewFeatures, и тогда анализатор проигнорирует использование типа предварительной версии внутри APreviewMethod. Естественно, аналогичную операцию нужно выполнить и для всех объектов, которые вызывают APreviewMethod.
Вы также можете предоставить согласие на использование предварительных версий функций на уровне сборки или модуля. Это действие сообщает анализатору, что использование типов предварительной версии для этой сборки является ожидаемым, и в этом случае правило не будет создавать ошибки. Это предпочтительный способ для использования зависимостей предварительной версии. Чтобы включить предварительные версии функций для целой сборки, установите для нее свойство EnablePreviewFeatures в файле .csproj следующим образом:

  <PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
  </PropertyGroup>

Когда лучше отключить предупреждения

Запретить предупреждения из этого правила рекомендуется только для расширенных вариантов использования, когда диагностика в API необходимо явно отключить. Если вы используете этот механизм, вы обязаны правильным образом пометить все API предварительной версии. Для примера давайте рассмотрим случай, когда существующий тип реализует новый интерфейс предварительной версии. Поскольку вы не можете пометить весь тип как тип предварительной версии (для обеспечения обратной совместимости), следует локально отключить диагностику для определения этого типа. Кроме того, все реализации интерфейса предварительной версии следует пометить атрибутом предварительной версии. Теперь вы сможете использовать существующий тип, как обычно, но для вызовов новых методов интерфейса будет создаваться диагностическое сообщение. System.Private.CoreLib.csproj использует этот метод для предоставления универсальных математических функций с числовыми типами, как например Int32, Double и Decimal.

На изображениях ниже показано, как отключить анализатор CA2252 в локальной среде.

Примечание.

В этом правиле могут отображаться предупреждения о ложноположительных срабатываниях, если применяются все указанные ниже действия.

Вы используете Visual Studio 2022 версии 17.5 или более поздней версии с более старой версией пакета SDK для .NET, то есть .NET 6 или более ранней версии.
Вы используете анализаторы из пакета SDK для .NET 6 или более старой версии пакетов анализатора, например Microsoft.CodeAnalysis.FxCopAnalyzers.

В этом случае это безопасно для подавления ложноположительных предупреждений. Ложные срабатывания обусловлены критическим изменением компилятора C#. Рассмотрите возможность использования более нового анализатора, содержащего исправление для предупреждений ложноположительных срабатываний. Обновление до Microsoft.CodeAnalysis.NetAnalyzers версии 7.0.0-preview1.22464.1 или более поздней версии или использование анализаторов из пакета SDK для .NET 7.

Отключение предупреждений

Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.

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

Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.

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

Чтобы отключить эту всю категорию правил, задайте уровень серьезности для категории none в файле конфигурации.

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Usage.severity = none

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

См. также

Описание функций EnablePreviewFeatures и GenerateRequiresPreviewFeaturesAttribute см. в статье Справочник по MSBuild для проектов пакета SDK для .NET
Документ по разработке предварительных версий функций

Поделиться через