Personalizar las reglas del analizador de Roslyn

Cada diagnóstico o regla del analizador de Roslyn tiene una gravedad y un estado de eliminación predeterminados que se pueden personalizar según el proyecto. Este artículo trata sobre la configuración de los niveles de gravedad del analizador y la supresión de infracciones del analizador.

Niveles de gravedad

A partir de la versión 16.3 de Visual Studio 2019, puede configurar la gravedad de las reglas del analizador en un archivo EditorConfig desde el menú de bombilla y la ventana Lista de errores.

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 del 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, e impiden que las compilaciones se lleven a cabo.	El código infractor se subraya con una línea de subrayado rojo y se marca con un pequeño cuadro rojo en la barra de desplazamiento.
Advertencia	warning	Las infracciones aparecen en la pestaña Advertencia en la ventana Lista de errores y en la salida de compilación de la línea de comandos, pero no impiden que las compilaciones se lleven a cabo.	El código infractor se subraya con una línea de subrayado verde y se marca con 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 se incluyen en la salida de compilación de la línea de comandos.	El código afectado se subraya con una línea de subrayado gris y se marca con un pequeño cuadro gris en la barra de desplazamiento.
Silent	silent	Invisible para el usuario.	Invisible para el usuario, pero el diagnóstico se notifica al motor de diagnóstico del IDE.
None	none	Se suprime por completo.	Se suprime por completo.
Default	default	Corresponde a la gravedad predeterminada de la regla. Para determinar cuál es el valor predeterminado de una regla, consulte la 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 de analizador notificadas en la lista de errores coincide con el ajuste del nivel de gravedad de la regla:

Las infracciones de reglas de analizador también se muestran en el editor de código como líneas de subrayado debajo del código infractor. Por ejemplo, en la imagen siguiente se muestran tres infracciones: un error (línea de subrayado rojo), una advertencia (línea de subrayado verde) y una sugerencia (tres puntos grises):

Muchos diagnósticos tienen una o más correcciones de código asociadas que se pueden aplicar para corregir la infracción de la regla. Las correcciones de código se muestran en el menú del icono de bombilla junto con otros tipos de Acciones rápidas. Para obtener más información sobre las correcciones de código, vea 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ú de bombilla
• Ventana Lista de errores
• Explorador de soluciones

Silencio frente a ninguna gravedad

Las reglas de gravedad Silent que se encuentran habilitadas de forma predeterminada difieren de las reglas de gravedad None o deshabilitadas:

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

Establecer la gravedad de la regla en un archivo .editorconfig

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

Configurar la gravedad de una regla en un archivo .editorconfig tiene precedencia sobre cualquier gravedad que se establezca en un conjunto de reglas o en el Explorador de soluciones. La gravedad en un archivo EditorConfig se puede configurar manualmente o automáticamente con la bombilla que aparece junto a una infracción.

Configuración manual de la gravedad de la regla en un archivo EditorConfig

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

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

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

   Por ejemplo, para establecer la gravedad de CA1822 en error en los archivos de C#, la entrada tendrá el siguiente aspecto:

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

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

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

4. Los analizadores de estilo de código del IDE también se pueden configurar en un archivo EditorConfig con una sintaxis diferente.

   Por ejemplo, dotnet_style_qualification_for_field = false:suggestion. pero si se establece una gravedad mediante la sintaxis dotnet_diagnostic, esta tendrá prioridad. Para más información, vea Convenciones de lenguaje de EditorConfig.

Configuración de la gravedad de varias reglas del analizador a la vez en un archivo EditorConfig

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

Puede configurar la gravedad de una categoría específica de reglas del analizador o de 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 para configurar varias reglas del 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 mediante 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:

• La entrada de gravedad para una regla individual por id. tiene precedencia sobre una entrada de gravedad para una categoría.
• Una entrada de gravedad para una categoría tiene precedencia 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. Pero, según las reglas de precedencia especificadas, la primera entrada de gravedad basada en el id. de regla tiene precedencia sobre las entradas siguientes. En este ejemplo, CA1822 tiene una gravedad real 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.

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

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

1. Cuando se produzca una infracción, mantenga el puntero sobre la línea de subrayado en el editor y seleccione Mostrar posibles correcciones para abrir el menú de bombilla. También puede colocar el cursor en la línea y presionar CTRL+. (punto).

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

   • Configure la gravedad del <id. 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 para todas las categorías de las reglas del analizador.

     En el ejemplo siguiente, elija Suprimir o configurar incidencias>Configurar la gravedad del <id. de regla>.

     

3. Elija una de las opciones de gravedad.

   

   Visual Studio agrega una entrada al archivo .editorconfig para establecer la regla en el nivel de gravedad, tal y como se muestra en el cuadro vista previa.

   Si todavía no tiene un archivo .editorconfig en el proyecto, Visual Studio crea uno automáticamente.

Establecimiento de la gravedad de una regla desde la ventana Lista de errores

Visual Studio también proporciona una forma cómoda de configurar la gravedad de una regla en el menú contextual de la lista de errores. Siga estos pasos:

1. Cuando se produzca una infracción, haga clic con el botón derecho en la entrada de diagnóstico en la lista de errores.

2. En el menú contextual, seleccione Configurar gravedad y, a continuación, elija una de las opciones de gravedad.

   

   Visual Studio agrega una entrada al archivo EditorConfig para configurar la regla en el nivel solicitado.

   Si todavía no tiene un archivo .editorconfig en el proyecto, Visual Studio crea uno automáticamente.

Establecer la gravedad de una regla desde el Explorador de soluciones

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

1. En el Explorador de soluciones, expanda Referencias>Analizadores (o Dependencias>Analizadores si el proyecto es de .NET Core).

2. Expanda el ensamblado que contiene la regla cuya gravedad quiera establecer.

3. Haga clic con el botón derecho en la regla y seleccione Configurar 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 utiliza un archivo de conjunto de reglas en lugar de un archivo EditorConfig, la entrada de gravedad se agrega al archivo de 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 archivo EditorConfig automáticamente.

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

Gran parte de la personalización de diagnósticos de analizador se puede realizar desde el Explorador de soluciones. Si instala un analizador como un paquete NuGet, aparecerá un nodo Analizadores en el nodo Referencias o Dependencias para los proyectos de .NET Core en el Explorador de soluciones. Siga estos pasos para ver los analizadores y diagnósticos:

1. En Explorador de soluciones, expanda el proyecto y, después, expanda Referencias o Dependencias. A continuación, expanda Analizadores. Expanda uno de los ensamblados del analizador para ver los diagnósticos de dicho ensamblado.

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

   • x en un círculo indica una gravedad de tipo Error
   • ! en un triángulo indica una gravedad de tipo Advertencia
   • i en un círculo de línea ininterrumpida indica una gravedad de tipo Sugerencia
   • i en un círculo de puntos indica una gravedad de tipo Silenciosa
   • La flecha hacia abajo en un círculo de línea ininterrumpida indica una gravedad de tipo Ninguna

   

2. Si hace clic con el botón derecho en un diagnóstico y selecciona la ventana Propiedades, podrá ver las propiedades de dicho diagnóstico, incluida su descripción y su gravedad predeterminada. O bien, seleccione el diagnóstico y presione Alt+Entrar.

   Aparece la ventana 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 ver la documentación en línea de un diagnóstico, haga clic con el botón derecho en el diagnóstico en cuestión y seleccione Ver la Ayuda.

Conversión de un archivo de conjunto de reglas existente en un archivo EditorConfig

A partir de la versión 16.5 de Visual Studio 2019, los archivos de conjunto de reglas están en desuso y se han reemplazado por el archivo EditorConfig para la configuración del analizador para código administrado. Los archivos EditorConfig son más flexibles y permiten configurar los niveles de gravedad 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 Visual Studio Tools para la configuración de gravedad de las reglas del analizador están ahora optimizadas para trabajar con archivos EditorConfig en lugar de archivos del conjunto de reglas, se recomienda convertir los proyectos existentes que todavía utilizan 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 asegura de 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 Standard no admiten los comandos de menú relativos a conjuntos de reglas del Explorador de soluciones (por ejemplo, Abrir conjunto de reglas activo). Para especificar un conjunto de reglas no predeterminado en un proyecto de .NET Core o .NET Standard, agregue la propiedad CodeAnalysisRuleSet manualmente al archivo del proyecto. Las reglas del conjunto de reglas se pueden seguir configurando en el editor de conjuntos de reglas.

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

1. Haga doble clic en el archivo de 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 en la que se puede hacer clic.

   

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 archivo EditorConfig generado se abrirá en el editor. Además, la propiedad CodeAnalysisRuleSet de MSBuild se actualiza en el archivo del proyecto para que ya no haga referencia al archivo de conjunto de reglas original.

Para utilizar 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 de conjunto de reglas y al archivo EditorConfig como argumentos de la 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 todos los archivos de origen de un proyecto y notifican las infracciones que encuentran. Sin embargo, estas infracciones no son útiles para los archivos generados por el sistema. Un ejemplo de esto son los archivos de código generados, como los archivos de código generados por el diseñador, los archivos de código fuente temporales generados por el sistema de compilación, etc. Los usuarios no pueden editar manualmente este tipo de archivos y no les corresponde 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 generado. Por ejemplo, un nombre de archivo que termina con .designer.cs o .generated.cs se considera código generado. Aun así, es posible que esta heurística no pueda identificar todos los archivos de código generado personalizados en el código fuente del usuario.

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

Siga los pasos que se indican a continuación para agregar esta configuración:

1. Si aún no tiene un archivo .editorconfig en el proyecto, agregue uno.

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

   [*.MyGenerated.cs]
   generated_code = true
   

Suprimir infracciones

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

Uso de la línea de comandos

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

• 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. Para los estilos de código, también puede aplicar estilos de código en las compilaciones mediante la configuración de una propiedad de MSBuild.

• Hay una o varias infracciones de regla en el código del proyecto.

• El nivel de gravedad de una regla infringida se establece en advertencia (en cuyo caso las infracciones no provocan un error de compilación) o en error (en cuyo caso sí se genera un error de compilación).

El nivel de detalle de la salida de la compilación no afecta al hecho de que las infracciones de regla se muestren o no. Incluso con un nivel de detalle quiet, las infracciones de regla aparecerán en la salida de la compilación.

Si está acostumbrado a ejecutar análisis antiguos desde la línea de comandos, ya sea con FxCopCmd.exe o a través de MSBuild con la marca RunCodeAnalysis, aquí le indicamos cómo hacerlo con analizadores de código.

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

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

La captura de pantalla siguiente muestra la salida de compilación de línea de comandos de la compilación de un proyecto que contiene una infracción de regla de analizador:

Proyectos dependientes

Si se agrega una referencia a un proyecto de .NET Core que tiene analizadores de 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 configurando el atributo PrivateAssets 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

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