Compartir vía

Archivos de configuración para las reglas de análisis de código

  • Artículo

Las reglas de análisis de código tienen varias opciones de configuración. Estas opciones deberán especificarse como pares clave-valor en uno de los siguientes archivos de configuración del analizador:

  • Archivo EditorConfig: opciones de configuración basadas en archivos o carpetas.
  • Archivo AnalyzerConfig global: opciones de configuración del proyecto. Resulta útil si algunos archivos del proyecto se encuentran fuera de la carpeta de este.

Sugerencia

También puede establecer las propiedades de configuración del análisis de código en el archivo de proyecto. Estas propiedades configuran el análisis de código en el nivel masivo, desde activar o desactivar completamente el análisis de código hasta la configuración de reglas de nivel de categoría. Para obtener más información, consulte EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> y AnalysisMode.

EditorConfig

Los archivos EditorConfig se usan para proporcionar opciones que se aplican a archivos o carpetas de origen específicos. Las opciones se colocan bajo encabezados de sección para poder identificar los archivos y carpetas aplicables. Agregue una entrada para cada regla que quiera configurar y colóquela en la sección de la extensión de archivo correspondiente; por ejemplo, [*.cs].

[*.cs]
<option_name> = <option_value>

En el ejemplo anterior, [*.cs] es un encabezado de sección editorconfig que sirve para seleccionar todos los archivos de C# con la extensión de archivo .cs de la carpeta actual, incluidas las subcarpetas. La entrada siguiente (<option_name> = <option_value>) es una opción del analizador que se aplicará a todos los archivos de C#.

Puede aplicar las convenciones del archivo EditorConfig a una carpeta, un proyecto o un repositorio completo colocando el archivo en el directorio correspondiente. Estas opciones se aplican al ejecutar el análisis en el momento de la compilación y durante la edición de código en Visual Studio.

Nota

Las opciones EditorConfig solo se aplican en los archivos de origen de un proyecto o directorio. Los archivos que se incluyen en un proyecto como AdditionalFiles no se consideran archivos de origen y las opciones de EditorConfig no se aplican a estos archivos. Para aplicar una opción de regla a archivos que no son de origen, especifique la opción en un archivo de configuración global.

Si tiene un archivo .editorconfig para las opciones de configuración del editor, como el tamaño de la sangría o la activación o desactivación de la supresión del espacio en blanco final, puede colocar las opciones de configuración del análisis de código en el mismo archivo.

Sugerencia

Visual Studio proporciona una plantilla de elemento de .editorconfig que facilita el agregar uno de estos archivos al proyecto. Para más información, vea Agregar un archivo EditorConfig a un proyecto.

Ejemplo

A continuación, se muestra un archivo EditorConfig de ejemplo para configurar las opciones y la gravedad de la regla:

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

AnalyzerConfig global

También puede configurar las opciones del analizador con archivos AnalyzerConfig globales. Estos archivos se usan para proporcionar opciones que se aplican a todos los archivos de origen de un proyecto, independientemente de sus nombres o rutas de acceso de archivo.

A diferencia de los archivos EditorConfig, los de configuración global no se pueden usar para definir los valores de estilo del editor de los IDE, como el tamaño de la sangría o la activación o desactivación de la supresión del espacio en blanco final. En su lugar, están diseñados exclusivamente para especificar las opciones de configuración del analizador de nivel de proyecto.

Format

A diferencia de los archivos EditorConfig, que deben tener encabezados de sección (como [*.cs]) para identificar los archivos y carpetas aplicables, los archivos AnalyzerConfig globales no tienen encabezados de sección. En su lugar, requieren una entrada de nivel superior con el formato is_global = true para que se puedan diferenciar de los archivos EditorConfig normales. Esto indica que todas las opciones del archivo se aplican a todo el proyecto. Por ejemplo:

is_global = true
<option_name> = <option_value>

Nomenclatura

A diferencia de EditorConfig archivos, que deben denominarse .editorconfig, los archivos de configuración global no necesitan tener un nombre o una extensión específicos. Sin embargo, si asigna un nombre a estos archivos como .globalconfig, se aplican implícitamente a todos los proyectos de C# y Visual Basic dentro de la carpeta actual, incluidas las subcarpetas. De lo contrario, deberá agregar explícitamente el elemento GlobalAnalyzerConfigFiles al archivo de proyecto de MSBuild:

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

Tenga en cuenta las recomendaciones de nombres siguientes:

  • Los usuarios finales deberían llamar a sus archivos de configuración global .globalconfig.
  • Los creadores de paquetes NuGet deberían llamar a sus archivo de configuración global <%Package_Name%>.globalconfig.
  • Los archivos de configuración generados con herramientas de MSBuild deberían llamarse <%Target_Name%>_Generated.globalconfig o de forma similar.

Nota:

La entrada de nivel superior is_global = true no es necesario cuando el archivo se denomina .globalconfig, pero se recomienda para mayor claridad.

Inclusión condicional

Puede usar un archivo de configuración global para deshabilitar o habilitar determinadas reglas de análisis de código en distintos entornos. Por ejemplo, es posible que desee deshabilitar algunas reglas de análisis de código para proyectos de prueba unitaria. Para ello, puede establecer la gravedad de las reglas aplicables en none el archivo de configuración, por ejemplo:

# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none

Después, puede personalizar la compilación para incluir solo el archivo de configuración en proyectos de prueba en función de las condiciones específicas de la compilación. Por ejemplo:

<ItemGroup Condition="'$(IsShipping)' == 'false'">
  <!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
  <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>

Distribución en paquetes NuGet

Los archivos Global AnalyzerConfig se pueden distribuir con paquetes NuGet. Para ello, agregue un archivo .props al paquete NuGet. En el archivo .props, agregue un elemento GlobalAnalyzerConfigFilesbajo el nodoProject:

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

Ejemplo

A continuación, se muestra un archivo AnalyzerConfig global de ejemplo para configurar las opciones y la gravedad de la regla en el proyecto:

# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true

# NOTE: No section headers for configuration entries

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

Prioridad

Tanto los archivos EditorConfig como los AnalyzerConfig globales especifican un par clave-valor para cada opción. Se producirán conflictos si hay varias entradas con la misma clave, pero con distintos valores. Las reglas de precedencia siguientes se usan para resolver conflictos.

Ubicaciones de entrada en conflicto Regla de precedencia
En el mismo archivo de configuración Prevalecerá la entrada que aparezca más abajo en el archivo. Esto se aplica a las entradas en conflicto de un único archivo EditorConfig y también de un único archivo AnalyzerConfig global.
En dos archivos EditorConfig Prevalecerá la entrada del archivo EditorConfig que se encuentre en una ubicación más profunda del sistema de archivos y que, por tanto, tenga una ruta de archivo más larga.
En dos archivos AnalyzerConfig globales .NET 5: se informará de una advertencia del compilador y se ignorarán ambas entradas.
.NET 6 y versiones posteriores: prevalecerá la entrada del archivo con un valor más alto paraglobal_level. Si global_level no está definido explícitamente y el archivo se llama .globalconfig, el valor global_level tendrá 100 como valor predeterminado; en el caso del resto de archivos AnalyzerConfig globales, global_level tendrá 0 como valor predeterminado. Si los valores global_level de los archivos de configuración con entradas en conflicto son iguales, se informará de una advertencia del compilador y se ignorarán ambas entradas.
En un archivo EditorConfig y un archivo AnalyzerConfig global Prevalecerá la entrada en el archivo EditorConfig.

Opciones de gravedad

En el caso de las opciones de configuración de la gravedad, se aplican las siguientes reglas de precedencia adicionales:

Consulte también