Бөлісу құралы:

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

Свойство Значение
Идентификатор правила CA2252
Заголовок Перед использованием функций предварительной версии выполните подписку на них.
Категория Использование
Исправление является критическим или не критическим неразрывный
Включен по умолчанию в .NET 10 Ошибка
Применимые языки C# и Visual Basic

Причина

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

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

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

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

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

Редактор кода с предупреждением 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 в локальной среде.

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

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

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

См. также

  • Last updated on