CA2252: Participación en las características en versión preliminar antes de usarlas

  • Artículo
Propiedad Value
Identificador de la regla CA2252
Título Previsualizar funciones antes de utilizarlas
Categoría Uso
La corrección es problemática o no problemática Poco problemático
Habilitado de forma predeterminada en .NET 8 Como error

Causa

Un cliente usa tipos o API de versión preliminar en su ensamblado sin participar explícitamente ya sea localmente o en el nivel de módulo o ensamblado.

Descripción de la regla

Cuando se consume una API o ensamblado decorado con el atributo RequiresPreviewFeaturesAttribute, esta regla comprueba si el sitio de llamada participa en las características en versión preliminar. Un sitio de llamada participa en las características en versión preliminar si se cumple alguna de las siguientes opciones:

  • Está dentro del ámbito de una anotación RequiresPreviewFeaturesAttribute.
  • Forma parte de un ensamblado o módulo que ya ha participado en las características en versión preliminar.

En la imagen siguiente se muestra un ejemplo del diagnóstico CA2252.

Code editor with CA2252 warning.

Aquí, Lib es un tipo de versión preliminar que se construye en el método Main. Main no se anota como método en versión preliminar, por lo que los diagnósticos se generan en las dos llamadas de constructor dentro de Main.

Cómo corregir infracciones

Existen dos formas de corregir las infracciones:

  • Incluya un sitio de llamada en el ámbito de una anotación anotando su elemento primario con RequiresPreviewFeaturesAttribute. En el ejemplo anterior, APreviewMethod se anota con el atributo RequiresPreviewFeatures, por lo que el analizador omite el uso del tipo de versión preliminar dentro de APreviewMethod. De ello se deduce que quienes llamen a APreviewMethod tendrán que realizar un ejercicio similar.

  • También puede participar en las características en versión preliminar a nivel de ensamblado o módulo. Esto indica al analizador que se desea obtener un uso de tipo de versión preliminar y, como consecuencia, esta regla no producirá errores. Esta es la manera preferida de consumir dependencias en versión preliminar. Para habilitar las características en versión preliminar dentro de todo el ensamblado, establezca la propiedad EnablePreviewFeatures en un archivo .csproj:

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

Cuándo suprimir las advertencias

La supresión de advertencias de esta regla solo se recomienda para los casos de uso avanzados en los que los diagnósticos de las API deben deshabilitarse explícitamente. En este caso, debe estar dispuesto a asumir la responsabilidad de marcar las API de versión preliminar correctamente. Por ejemplo, considere un caso en el que un tipo existente implementa una nueva interfaz de versión preliminar. Puesto que todo el tipo no se puede marcar como versión preliminar (por compatibilidad con versiones anteriores), el diagnóstico alrededor de la definición de tipo se puede deshabilitar localmente. Además, debe marcar las implementaciones de la interfaz de versión preliminar como versión preliminar. Ahora, el tipo existente se puede usar como antes, pero las llamadas a los nuevos métodos de interfaz obtienen diagnósticos. System.Private.CoreLib.csproj utiliza esta técnica para exponer características matemáticas genéricas en tipos numéricos como Int32, Double y Decimal.

En las imágenes siguientes se muestra cómo deshabilitar el analizador CA2252 localmente.

CA2252 - Suppress Detect Preview Feature Diagnostic

CA2252 - Mark Interface Implementations Explicitly

Nota:

Es posible que vea advertencias de falsos positivos de esta regla si se aplica todo lo siguiente:

  • Está usando Visual Studio 2022, versión 17.5 o posterior, con una versión anterior del SDK de .NET, es decir, .NET 6 o una anterior.
  • Está usando los analizadores del SDK de .NET 6 o una versión anterior de los paquetes del analizador, como Microsoft.CodeAnalysis.FxCopAnalyzers.

En este caso, es seguro suprimir una advertencia de falso positivo. Los falsos positivos se deben a un cambio importante en el compilador de C#. Considere la posibilidad de usar un analizador más reciente que incluya la corrección de las advertencias de falsos positivos. Actualice a Microsoft.CodeAnalysis.NetAnalyzers, versión 7.0.0-preview1.22464.1 o posterior, o bien use los analizadores del SDK de .NET 7.

Supresión de una advertencia

Si solo quiere suprimir una única infracción, agregue directivas de preprocesador al archivo de origen para deshabilitar y volver a habilitar la regla.

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

Para deshabilitar la regla de un archivo, una carpeta o un proyecto, establezca su gravedad en none del archivo de configuración.

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

Para deshabilitar toda esta categoría de reglas, establezca la gravedad de la categoría en none del archivo de configuración.

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

Para obtener más información, consulte Procedimiento para suprimir advertencias de análisis de código.

Consulte también