Personalización de las reglas del analizador de Roslyn

Cada regla del analizador de Roslyn o diagnóstico tiene un estado de gravedad y supresión predeterminados que puede personalizar para el proyecto. En este artículo se describen la configuración de la gravedad del analizador y la supresión de infracciones del analizador.

Niveles de gravedad

Puede configurar la gravedad de las reglas del analizador en un archivo EditorConfig y desde el menú de bombilla.

En la tabla siguiente se muestran las distintas opciones de gravedad que puede configurar para un diagnóstico:

Gravedad (Explorador de soluciones)	Gravedad (archivo EditorConfig)	Comportamiento en tiempo de compilación	comportamiento Editor
Error	error	Las infracciones aparecen en la pestaña Error de la ventana Lista de errores y en la salida de compilación de la línea de comandos y provocan un error en las compilaciones.	El código infractor se subraya con una línea roja ondulada y está marcado por un pequeño cuadro rojo en la barra de desplazamiento.
Advertencia	warning	Las infracciones aparecen en la pestaña Advertencia de la ventana Lista de errores y en la salida de compilación de la línea de comandos, pero no hacen que se produzcan errores en las compilaciones.	El código infractor se marca con una línea ondulada verde y un pequeño cuadro verde en la barra de desplazamiento.
Sugerencia	suggestion	Las infracciones aparecen en la pestaña Mensaje de la ventana Lista de errores , pero no en la salida de compilación de la línea de comandos.	El código afectado está subrayado con una línea ondulada gris y señalado por un pequeño cuadro gris en la barra de desplazamiento.
Silencioso	silent	Invisible para el usuario.	Invisible para el usuario, pero el diagnóstico se notifica al motor de diagnóstico del IDE.
Ninguno	none	Se ha suprimido por completo.	Se ha suprimido por completo.
Predeterminado	default	Corresponde a la gravedad predeterminada de la regla. Para determinar el valor predeterminado de una regla, vea su ventana Propiedades.	Corresponde a la gravedad predeterminada de la regla.

Visualización de infracciones de reglas

Si un analizador encuentra infracciones de reglas de analizador, las notifica en la ventana Lista de errores y en el editor de código.

En la captura de pantalla siguiente se muestran las infracciones de reglas notificadas en la ventana Lista de errores. Las infracciones del analizador notificadas en la lista de errores coinciden con la configuración de nivel de gravedad de la regla:

Las infracciones de las reglas del analizador también aparecen en el editor de código como líneas onduladas bajo el código problemático. Por ejemplo, en la captura de pantalla siguiente se muestran tres infracciones: un error (línea de subrayado ondulado rojo), una advertencia (línea de subrayado ondulado verde) y una sugerencia (tres puntos grises):

Muchos diagnósticos tienen una o varias correcciones de código asociadas que puede aplicar para corregir la infracción de la regla. Las correcciones de código se muestran en el menú icono de bombilla junto con otros tipos de acciones rápidas. Para obtener más información sobre las correcciones de código, consulte Acciones rápidas comunes.

Configuración de los niveles de gravedad

Puede establecer la gravedad de la regla mediante cualquiera de los métodos siguientes:

• EditorConfig
• Menú del ícono de bombilla
• Explorador de soluciones

Silencio vs. Ninguna severidad

Silent las reglas de gravedad habilitadas de forma predeterminada difieren de las reglas de gravedad deshabilitadas o None:

• Si se registra una solución de código para una Silent regla de severidad, Visual Studio ofrece la solución de código como una acción de refactorización indicada por una bombilla incluso si el diagnóstico oculto no es visible para el usuario. Si la regla de gravedad está deshabilitada como None, no se ofrece la corrección del código.
• Las entradas que establecen la gravedad de varias reglas de analizador a la vez en un archivo EditorConfig pueden configurar Silent de forma masiva las reglas de gravedad. None Las reglas de gravedad no se pueden configurar de esta manera. En su lugar, deben configurarse mediante entradas que establezcan la gravedad en un archivo EditorConfig para cada identificador de regla.

Establecer la gravedad de la regla en un archivo EditorConfig

Los archivos EditorConfig están disponibles en Visual Studio 2019, versión 16.3 y posteriores.

Establecer la gravedad de una regla en un archivo EditorConfig tiene prioridad sobre cualquier conjunto de gravedad establecido en un conjunto de reglas o en el Explorador de soluciones. Puede configurar la gravedad manualmente en un archivo EditorConfig o automáticamente a través de la bombilla que aparece junto a una infracción.

Configurar manualmente la gravedad de la regla en un archivo EditorConfig

Para configurar la gravedad de la regla, siga estos pasos:

1. Agregue un archivo EditorConfig al proyecto, si aún no tiene uno.

2. Agregue una entrada para cada regla que quiera configurar en la extensión de archivo correspondiente.

   Por ejemplo, la entrada para establecer la gravedad de CA1822 a error para los archivos de C# es la siguiente:

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Puede establecer la gravedad de la regla para cada identificador de regla de diagnóstico en un archivo EditorConfig con la sintaxis siguiente:

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

4. En el caso de los analizadores de estilo de código IDE, también puede configurarlos en un archivo EditorConfig mediante una sintaxis diferente.

   Por ejemplo: dotnet_style_qualification_for_field = false:suggestion. Sin embargo, si establece una gravedad mediante la sintaxis dotnet_diagnostic, esta tiene prioridad. Para obtener más información, consulte Convenciones de lenguaje para EditorConfig.

Establecer la gravedad de varias reglas del analizador a la vez en un archivo EditorConfig

La capacidad de establecer varias reglas de analizador a la vez en un archivo EditorConfig está disponible en Visual Studio 2019 versión 16.5 y versiones posteriores.

Puede establecer la gravedad de una categoría específica de reglas de analizador o para todas las reglas del analizador con una sola entrada en un archivo EditorConfig:

• Establezca la gravedad de la regla para una categoría de reglas del analizador:

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

• Establezca la gravedad de la regla para todas las reglas del analizador:

  dotnet_analyzer_diagnostic.severity = <severity>

Las entradas que configuran varias reglas de analizador a la vez solo se aplican a las reglas que están habilitadas de forma predeterminada. Las reglas del analizador marcadas como deshabilitadas de forma predeterminada en el paquete del analizador deben habilitarse a través de entradas explícitas dotnet_diagnostic.<rule ID>.severity = <severity> .

Si tiene varias entradas que son aplicables a un identificador de regla específico, el orden de prioridad de la entrada aplicable es el siguiente:

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

Considere el siguiente ejemplo de EditorConfig, donde CA1822 es una regla de rendimiento:

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

En este ejemplo, las tres entradas se aplican a la regla de rendimiento CA1822. Sin embargo, con las reglas de precedencia especificadas, la primera entrada de gravedad basada en identificador de regla tiene prioridad sobre las siguientes entradas. En este ejemplo, CA1822 tiene una gravedad efectiva de error. Las reglas de rendimiento restantes tienen una gravedad de warning. Las reglas del analizador que no son reglas de rendimiento tienen una gravedad de suggestion.

Establecer la gravedad de la regla desde el menú de bombilla

Visual Studio proporciona una manera cómoda de configurar la gravedad de una regla desde el menú de bombilla Acciones rápidas . Siga estos pasos:

1. Después de que se produzca una infracción, mantenga el puntero sobre la línea de subrayado ondulado de infracción en el editor y elija Mostrar posibles correcciones para abrir el menú de bombilla. O bien, coloque el cursor en la línea y presione Ctrl+. (punto).

2. En el menú de bombilla, mantenga el puntero sobre un nivel de gravedad para obtener una vista previa del cambio y, a continuación, configure la gravedad según las opciones siguientes:

   • Configure <la gravedad del identificador> de regla. Establezca la gravedad de la regla específica.

   • Configure la gravedad de todos los <analizadores de estilo>. Establezca la gravedad de todas las reglas de la categoría de regla específica.

   • Configure la gravedad de todos los analizadores. Establezca la gravedad de todas las categorías de reglas del analizador.

     En el siguiente ejemplo, seleccione Suprimir o configurar problemas>Configurar la gravedad del <ID de regla>.

     

3. Elija una de las opciones de gravedad.

   

   Visual Studio agrega una entrada al archivo EditorConfig para configurar la regla en el nivel de gravedad solicitado, como se muestra en el cuadro de vista previa.

   Si aún no tiene un archivo EditorConfig en el proyecto, Visual Studio crea uno automáticamente.

Establecimiento de la gravedad de la regla desde el Explorador de soluciones

Para establecer la gravedad de la regla desde el Explorador de soluciones, siga estos pasos:

1. En el Explorador de soluciones, expanda Referencias>Analizadores (o Dependencias>Analizadores para proyectos de .NET Core).

2. Expanda el ensamblado que contiene la regla para la que desea establecer la gravedad.

3. Haga clic con el botón derecho en la regla y seleccione Establecer gravedad. En el menú contextual, elija una de las opciones de gravedad.

   Visual Studio agrega una entrada al archivo EditorConfig para configurar la regla en el nivel solicitado. Si el proyecto usa un archivo de conjunto de reglas en lugar de un archivo EditorConfig, la entrada de gravedad se agrega al archivo del conjunto de reglas.

   Si aún no tiene un archivo EditorConfig o un archivo de conjunto de reglas en el proyecto, Visual Studio crea un nuevo archivo EditorConfig automáticamente.

Visualización de analizadores y diagnósticos desde el Explorador de soluciones

Puede realizar gran parte de la personalización del diagnóstico del analizador desde el Explorador de soluciones. Si instala un analizador como un paquete NuGet, aparece un nodo Analizadores en el nodo Referencias (o Nodo Dependencias para proyectos de .NET Core) en el Explorador de soluciones. Siga estos pasos para ver los analizadores y diagnósticos:

1. En el Explorador de soluciones, expanda el proyecto, expanda Referencias o Dependencias y, a continuación, expanda Analizadores. Expanda uno de los ensamblados del analizador para ver los diagnósticos en él.

   El icono situado junto a cada diagnóstico indica su nivel de gravedad:

   • x en un círculo indica una gravedad de Error
   • ! en un triángulo indica un nivel de gravedad de Advertencia
   • i en un círculo sólido indica una gravedad de Sugerencia
   • i en un círculo de puntos indica una gravedad de Silent
   • Una flecha dirigida hacia abajo en un círculo sólido indica una gravedad nula

   

2. Para ver las propiedades de un diagnóstico, incluida su descripción y gravedad predeterminada, haga clic con el botón derecho en el diagnóstico y, a continuación, seleccione Propiedades. O bien, seleccione el diagnóstico y presione Alt+Entrar.

   Aparece la ventana de Propiedades .

   

3. Para ver las propiedades de las reglas de estilo de código (prefijo IDE) en la ventana Propiedades, como la gravedad predeterminada, establezca la propiedad EnforceCodeStyleInBuild en true.

4. Para obtener documentación en línea para un diagnóstico, haga clic con el botón derecho en el diagnóstico y seleccione Ver ayuda.

Convertir un archivo de conjunto de reglas existente en un archivo EditorConfig

A partir de la versión 16.5 y posteriores de Visual Studio 2019, se han dejado de usar los archivos de conjunto de reglas en favor de los archivos EditorConfig para la configuración del analizador para código administrado. Los archivos EditorConfig son más flexibles y le permiten configurar las gravedades de las reglas del analizador y las opciones del analizador, incluidas las opciones de estilo de código del IDE de Visual Studio. Dado que las herramientas de Visual Studio para la configuración de gravedad de las reglas del analizador ahora están optimizadas para trabajar con archivos EditorConfig en lugar de archivos del conjunto de reglas, se recomienda convertir los proyectos existentes que todavía usan archivos de conjunto de reglas.

Al convertir el archivo de conjunto de reglas existente en un archivo EditorConfig, guárdelo en la raíz del repositorio o en la carpeta de la solución. Al hacerlo, se garantiza que la configuración de gravedad de este archivo se aplique automáticamente a todo el repositorio o solución, respectivamente.

Puede convertir un archivo de conjunto de reglas existente en un archivo EditorConfig mediante el editor del conjunto de reglas o la línea de comandos.

Nota:

Los proyectos de .NET Core y .NET 5+ no admiten los comandos de menú para los conjuntos de reglas en el Explorador de soluciones, por ejemplo, Abrir conjunto de reglas activas. Para especificar un conjunto de reglas no predeterminado para un proyecto de .NET Core o .NET 5+, agregue manualmente la propiedad CodeAnalysisRuleSet al archivo del proyecto. Todavía puede configurar las reglas dentro del conjunto de reglas en el editor del conjunto de reglas.

Para usar el editor del conjunto de reglas, siga estos pasos. Si el proyecto ya usa un archivo de conjunto de reglas específico para su CodeAnalysisRuleSet valor de propiedad, puede convertirlo en un archivo EditorConfig equivalente desde el editor del conjunto de reglas:

1. Haga doble clic en el archivo del conjunto de reglas en el Explorador de soluciones.

   El archivo del conjunto de reglas se abre en el editor del conjunto de reglas con una barra de información en la parte superior.

   

2. Seleccione el vínculo de la barra de información para migrar el archivo del editor del conjunto de reglas.

3. En el cuadro de diálogo Guardar como , seleccione el directorio donde desea generar el archivo EditorConfig y, a continuación, seleccione Guardar.

   El EditorConfig generado se abre en el editor. Además, la propiedad CodeAnalysisRuleSet MSBuild se actualiza en el archivo del proyecto para que ya no haga referencia al archivo del conjunto de reglas original.

   El archivo de conjunto de reglas original se puede quitar del proyecto.

   Nota:

   En un proyecto de .NET Framework, el archivo de conjunto de reglas predeterminado no se puede migrar ni quitar del proyecto.

Para usar la línea de comandos, siga estos pasos:

1. Instale el paquete NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Ejecute RulesetToEditorconfigConverter.exe desde el paquete instalado, con rutas de acceso al archivo del conjunto de reglas y el archivo EditorConfig como argumentos de línea de comandos.

   Por ejemplo:

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

En el ejemplo siguiente se muestra un archivo de conjunto de reglas que se va a convertir en un archivo EditorConfig:

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

En el ejemplo siguiente se muestra el archivo EditorConfig resultante después de la conversión:

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Configuración del código generado

Los analizadores se ejecutan en archivos de origen en un proyecto y notifican cualquier infracción que encuentren. Sin embargo, estas infracciones no son útiles para los archivos generados por el sistema. Algunos ejemplos son archivos de código generados, como archivos de código generados por el diseñador, archivos de código fuente temporales generados por el sistema de compilación, etc. Para estos tipos de archivos, los usuarios no pueden editar manualmente los archivos y no se preocupan por corregir ninguna infracción.

Por lo tanto, de forma predeterminada, el controlador del analizador examina solo los archivos con determinados nombres, extensiones de archivo o encabezados de archivo generados automáticamente como archivos de código generados. Por ejemplo, un nombre de archivo que termina con .designer.cs o .generated.cs se considera código generado. Sin embargo, es posible que estas heurística no puedan identificar todos los archivos de código generados personalizados en el código fuente del usuario.

En La versión 16.5 y posteriores de Visual Studio 2019, los usuarios finales pueden configurar archivos y carpetas específicos para que se traten como código generado en un archivo EditorConfig.

Para agregar esta configuración, siga estos pasos:

1. Si aún no tiene un archivo EditorConfig para el proyecto, agregue uno.

2. Agregue la generated_code = true | false entrada para archivos y carpetas específicos. Por ejemplo, para tratar todos los archivos cuyo nombre termina con .MyGenerated.cs como código generado, use esta entrada:

   [*.MyGenerated.cs]
   generated_code = true
   

Suprimir infracciones

Puede suprimir infracciones de reglas mediante varios métodos. Para obtener información, consulte Suprimir infracciones de análisis de código.

Uso de la línea de comandos

Al compilar el proyecto en la línea de comandos, las infracciones de reglas aparecen en la salida de compilación si se cumplen las condiciones siguientes:

• Los analizadores se instalan con el SDK de .NET o como un paquete NuGet, y no como una extensión .vsix .

  En el caso de los analizadores instalados mediante el SDK de .NET, es posible que tenga que habilitar los analizadores. En el caso de los estilos de código, también puede aplicar estilos de código en compilaciones estableciendo una propiedad de MSBuild.

• Se infringen una o varias reglas en el código del proyecto.

• El nivel de gravedad de una regla infringida se establece en cualquiera de las advertencias, en cuyo caso las infracciones no hacen que se produzca un error en la compilación o un error, en cuyo caso las infracciones provocan un error en la compilación.

El nivel de detalle de la salida de compilación no afecta a si se muestran infracciones de reglas. Incluso con un bajo nivel de verbosidad, las infracciones de las reglas aparecen en la salida de la compilación.

Si está acostumbrado a ejecutar análisis heredados desde la línea de comandos, ya sea con FxCopCmd.exe o a través de msbuild con el RunCodeAnalysis indicador, puede hacerlo con analizadores de código en su lugar.

Para ver las infracciones del analizador en la línea de comandos al compilar el proyecto mediante msbuild, ejecute un comando similar al siguiente:

msbuild myproject.csproj /target:rebuild /verbosity:minimal

La siguiente captura de pantalla muestra la salida de la línea de comandos al compilar un proyecto que contiene una infracción de regla del análisis.

Proyectos dependientes

En un proyecto de .NET Core, si agrega una referencia a un proyecto que tiene analizadores nuGet, Visual Studio agrega automáticamente esos analizadores al proyecto dependiente. Para deshabilitar este comportamiento (por ejemplo, si el proyecto dependiente es un proyecto de prueba unitaria), marque el paquete NuGet como privado estableciendo el PrivateAssets atributo en el archivo .csproj o .vbproj del proyecto al que se hace referencia:

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Contenido relacionado

• Introducción a los analizadores de código en Visual Studio
• Envío de un error del analizador de código
• Uso de conjuntos de reglas
• Suprimir infracciones de análisis de código
• Opciones de configuración para el análisis de código