Opciones de configuración para el análisis de código

  • Artículo

Las reglas de análisis de código tienen varias opciones de configuración. Algunas de estas opciones se especifican como pares clave-valor en un archivo de configuración del analizador mediante la sintaxis <option key> = <option value>. Otras opciones, que configuran el análisis de código en su conjunto, están disponibles como propiedades de MSBuild en el archivo del proyecto.

La opción más común que va a configurar es la gravedad de una regla. Puede configurar el nivel de gravedad de cualquier regla, incluidas las reglas de calidad del código y las reglas de estilo del código. Por ejemplo, para habilitar una regla como advertencia, agregue el siguiente par clave-valor a un archivo de configuración del analizador:

dotnet_diagnostic.<rule ID>.severity = warning

También puede configurar opciones adicionales para personalizar el comportamiento de la regla:

  • Las reglas de calidad de código tienen opciones de comportamiento, como los nombres de método a los que se debe aplicar una regla.
  • Las reglas de estilo de código tienen opciones de preferencia de estilo, como por ejemplo dónde son deseables nuevas líneas.
  • Las reglas de analizadores de terceros pueden definir sus propias opciones de configuración, con formatos de valor y nombres de clave personalizados.

Opciones generales

Estas opciones se aplican al análisis de código en conjunto. No se pueden aplicar solo a una regla específica.

Para obtener opciones adicionales, consulte Propiedades de análisis de código.

Modo de análisis

Aunque el SDK de .NET incluye todas las reglas de análisis de código, solo algunas de ellas están habilitadas de manera predeterminada. El modo de análisis determina qué conjunto de reglas, si corresponde, se van a habilitar. Puede elegir un modo de análisis más agresivo donde la mayoría o todas las reglas están habilitadas. O bien, puede elegir un modo de análisis más conservador en el que la mayoría o todas las reglas están deshabilitadas y, a continuación, puede optar por reglas específicas según sea necesario. Establezca el modo de análisis agregando la propiedad <AnalysisMode> MSBuild al archivo de proyecto.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

A partir de .NET 6, también puede habilitar de forma masiva una categoría de reglas mediante la propiedad <AnalysisMode<Categoría>> MSBuild.

Nota:

Si configura el análisis de código mediante propiedades de MSBuild como AnalysisMode, todas las opciones de configuración masivas de que establezca en el archivo de configuración se ignoran. Por ejemplo, si ha habilitado de forma masiva todas la reglas o una categoría de reglas en un archivo .editorconfig, se omite esa configuración.

Habilitar análisis de código

De forma predeterminada, el análisis de código está habilitado para los proyectos que tienen como destino .NET 5 y versiones posteriores. Si tiene el SDK de .NET 5+, pero el proyecto tiene como destino otra implementación de .NET, puede establecer la propiedad EnableNETAnalyzers del archivo del proyecto en true para habilitar manualmente el análisis de código.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Exclusión del código generado

Las advertencias del analizador de código de .NET no son útiles en los archivos de código generado, como los archivos generados por el diseñador, que los usuarios no pueden editar para corregir las infracciones. En la mayoría de los casos, los analizadores de código omiten los archivos de código generado y no informan de las infracciones de estos archivos.

De forma predeterminada, los archivos con determinadas extensiones de archivo o con encabezados de archivo generados automáticamente se tratan como archivos de código generado. Por ejemplo, un nombre de archivo que termina con .designer.cs o .generated.cs se considera código generado. Esta opción de configuración permite especificar patrones de nomenclatura adicionales que se tratarán como código generado. Se configuran archivos y carpetas adicionales agregando una entrada generated_code = true | false al archivo de configuración. Por ejemplo, para tratar todos los archivos cuyo nombre termina con .MyGenerated.cs como código generado, agregue la entrada siguiente:

[*.MyGenerated.cs]
generated_code = true

Opciones específicas de las reglas

Las opciones específicas de la regla se pueden aplicar a una sola regla, a un conjunto de reglas o a todas las reglas. Las opciones específicas de las reglas incluyen:

Nivel de gravedad

En la tabla siguiente se muestran los diferentes niveles de gravedad de las reglas que se pueden configurar para todas las reglas del analizador, incluidas las reglas de calidad del código y estilo del código.

Valor de configuración de gravedad Comportamiento en tiempo de compilación
error Las infracciones aparecen como errores de compilación que impiden que las compilaciones se lleven a cabo.
warning Las infracciones aparecen como advertencias de compilación, pero no impiden que las compilaciones se lleven a cabo (a menos que tenga una opción establecida para tratar las advertencias como errores).
suggestion Las infracciones aparecen como mensajes de compilación y como sugerencias en el IDE de Visual Studio. (En Visual Studio, las sugerencias aparecen como tres puntos de color gris en los dos primeros caracteres.)
silent Los usuarios no pueden ver las infracciones.

Sin embargo, para las reglas de estilo de código, las características de generación de código de Visual Studio siguen generando código en este estilo. Estas reglas también participan en la limpieza y aparecen en el menú Acciones rápidas y refactorizaciones de Visual Studio.
none La regla se suprime por completo.

Sin embargo, para las reglas de estilo de código, las características de generación de código de Visual Studio siguen generando código en este estilo.
default Se usa la gravedad predeterminada de la regla. Los niveles de gravedad predeterminados para cada versión de .NET se muestran en el repositorio roslyn-analyzers. En esa tabla, "Deshabilitado" corresponde a none, "Oculto" corresponde a silent e "Info" corresponde a suggestion.

Ámbito

  • Regla única

    Para establecer la gravedad de la regla para una sola regla, use la sintaxis siguiente.

    dotnet_diagnostic.<rule ID>.severity = <severity value>

  • Categoría de reglas

    Para establecer la gravedad de la regla para una categoría de reglas, use la sintaxis siguiente. Pero esta configuración de gravedad solo afecta a las reglas de esa categoría que están habilitadas de manera predeterminada.

    dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>

    Las distintas categorías se enumeran y se describen en Categorías de reglas. Además, puede encontrar la categoría de una regla específica en su página de referencia, por ejemplo, CA1000.

  • Todas las reglas

    Para establecer la gravedad de la regla predeterminada de todas las reglas del analizador, use la sintaxis siguiente. Pero esta configuración de gravedad solo afecta a las reglas que están habilitadas de manera predeterminada.

    dotnet_analyzer_diagnostic.severity = <severity value>

Importante

Cuando se configura el nivel de gravedad de varias reglas con una sola entrada, ya sea para una categoría de reglas o para todas las reglas, la gravedad solo se aplica a las reglas que están habilitadas de forma predeterminada. Además, si habilita todas las reglas mediante las propiedades de MSBuild <AnalysisMode> o <AnalysisLevel>, todas las opciones masivas de dotnet_analyzer_diagnostic se omiten. Por este motivo, es mejor habilitar una categoría de reglas estableciendo <AnalysisMode<Categoría>> en All.

Nota:

El prefijo para establecer la gravedad de una sola regla, dotnet_diagnostic, es ligeramente diferente al prefijo para configurar la gravedad mediante categoría o para todas las reglas, dotnet_analyzer_diagnostic.

Prioridad

Si tiene varias entradas de configuración de gravedad que se pueden aplicar al mismo identificador de regla, la prioridad se elige en el orden siguiente:

  • Una entrada para una categoría tiene prioridad sobre una entrada para todas las reglas del analizador.
  • Una entrada para una regla individual por identificador tiene prioridad sobre una entrada para una categoría.

Considere el ejemplo siguiente, donde CA1822 tiene la categoría "Performance":

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

En el ejemplo anterior, las tres entradas de gravedad se aplican a CA1822. Sin embargo, con las reglas de precedencia especificadas, la primera entrada basada en el identificador de regla tiene prioridad sobre las siguientes entradas. En este ejemplo, CA1822 tendrá una gravedad real de error. Todas las demás reglas de la categoría "Performance" tendrán una gravedad de warning.

Para obtener información sobre cómo se decide la precedencia entre archivos, vea la sección Prioridad del artículo Archivos de configuración.