Información general

Se aplica a:Visual Studio Visual Studio para Mac Visual Studio Code

Cada diagnóstico o regla del analizador de Roslyn tiene una gravedad y un estado de supresión predeterminados que se pueden sobrescribir y 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.

Configuración de los niveles de gravedad

A partir de la versión 16.3 de Visual Studio 2019, puede configurar la gravedad de las reglas del analizador, o diagnósticos, en un archivo EditorConfig (desde el menú de bombilla) y la lista de errores.

En la siguiente tabla se muestran las distintas opciones de gravedad:

Gravedad (Explorador de soluciones)	Gravedad (archivo .editorconfig)	Comportamiento en tiempo de compilación	Comportamiento del editor
Error	error	Las infracciones aparecen como Errores en la 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 un subrayado ondulado de color rojo y se marca con un pequeño cuadro rojo en la barra de desplazamiento.
Advertencia	warning	Las infracciones aparecen como Advertencias en la 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 un subrayado ondulado de color verde y se marca con un pequeño cuadro verde en la barra de desplazamiento.
Información	suggestion	Las infracciones aparecen como Mensajes en la Lista de errores, pero no se incluyen en la salida de compilación de la línea de comandos.	El código infractor se subraya con un subrayado ondulado de color gris y se marca con un pequeño cuadro gris en la barra de desplazamiento.
Hidden	silent	No es visible para el usuario.	No es visible para el usuario, pero el diagnóstico se notifica al motor de diagnóstico del IDE.
Ninguno	none	Se suprime por completo.	Se suprime por completo.
Default	default	Corresponde a la gravedad predeterminada de la regla. Para averiguar cuál es el valor predeterminado de una regla, consulte la ventana Propiedades.	Corresponde a la gravedad predeterminada de la regla.

Las infracciones de reglas que detecta el analizador aparecen en el editor de código (como un subrayado ondulado bajo el código infractor) y en la ventana Lista de errores.

Las infracciones de analizadores informadas en la lista de errores coincide con el valor del nivel de gravedad de la regla. Las infracciones de analizadores también se muestran en el editor de código como subrayados ondulados debajo del código infractor. En la imagen siguiente se muestran tres infracciones: un error (subrayado ondulado rojo), una advertencia (subrayado ondulado verde) y una sugerencia (tres puntos grises):

En la siguiente captura de pantalla se muestran las mismas tres infracciones, pero en la Lista de errores:

Muchas reglas de los analizadores, o 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 información sobre estas correcciones de código, vea Acciones rápidas comunes.

Gravedad "Hidden" frente a gravedad "None"

Las reglas de gravedad Hidden que están habilitadas de forma predeterminada difieren en ciertos aspectos de las reglas de gravedad None o deshabilitadas.

• Si se registra alguna corrección de código para una regla de gravedad Hidden, Visual Studio ofrece la corrección 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 reglas de gravedad Hidden se pueden configurar de forma masiva mediante entradas que establecen la gravedad de varias reglas del analizador a la vez en un archivo EditorConfig. Las reglas de gravedad None no se pueden configurar de esta manera. Deben configurarse mediante entradas que establecen la gravedad de la regla en un archivo EditorConfig para cada identificador de regla.

Establecer la gravedad de la regla en un archivo .editorconfig

(Visual Studio 2019, versión 16.3 y posteriores)

Puede establecer la gravedad de las advertencias del compilador o las reglas del analizador en un archivo EditorConfig con la sintaxis siguiente:

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

Establecer la gravedad de una regla en un archivo .editorconfig tiene prioridad 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.

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

(Visual Studio 2019, versión 16.5 y posteriores)

Puede establecer 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>

Nota

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 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 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 se aplican a CA1822. Pero, según las reglas de precedencia especificadas, la primera entrada de gravedad basada en el identificador de regla tiene prioridad sobre las entradas siguientes. En este ejemplo, CA1822 tiene una gravedad real de "error". Las reglas restantes con la categoría "Performance" tienen una gravedad de tipo "warning", mientras que las reglas del analizador que no tienen la categoría "Performance" tienen una gravedad de tipo "suggestion".

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

1. Si aún no tiene un archivo .editorconfig en el proyecto, agregue 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
   

Nota

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.

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.

1. Cuando se produzca una infracción, mantenga el puntero sobre la línea ondulada 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, seleccione una opción para configurar la gravedad:

   • Configurar la gravedad de <id. de regla>: establezca la gravedad de la regla específica.
   • Configure severity for all <style> analyzers (Configurar la gravedad de todos los analizadores ): establezca la gravedad de todas las reglas de la categoría de regla específica.
   • Configure severity for all analyzers (Configurar la gravedad de todos los analizadores): establezca la gravedad de todas las categorías de reglas del analizador.

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

   

   

3. Una vez ahí, seleccione una de las opciones de gravedad.

   

   

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

   Sugerencia

   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.

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.

   

3. Una vez ahí, seleccione una de las opciones de gravedad.

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

   Sugerencia

   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

Gran parte de la personalización de diagnósticos de analizador se puede realizar desde el Explorador de soluciones. Si instala analizadores como un paquete NuGet, aparecerá un nodo Analizadores en el nodo Referencias o Dependencias del Explorador de soluciones. Si expande Analizadores y, después, expande uno de los ensamblados del analizador, verá todos los diagnósticos de ese ensamblado.

En la ventana Propiedades puede ver las propiedades de un diagnóstico, incluida una descripción y su gravedad predeterminada. Para ver las propiedades, haga clic con el botón derecho en la regla y seleccione Propiedades, o bien seleccione la regla y presione Alt+ENTRAR.

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.

Los iconos situados junto a cada diagnóstico en el Explorador de soluciones se corresponden con los que aparecen en el conjunto de reglas cuando este se abre en el editor:

• Una "x" en un círculo indica una gravedad de tipo Error.
• Un signo "!" en un triángulo indica una gravedad de tipo Advertencia.
• Una "i" en un círculo indica una gravedad de tipo Información.
• Una "i" en un círculo con un fondo de color claro indica una gravedad de tipo Oculto.
• Una flecha hacia abajo dentro de un círculo indica que el diagnóstico se ha suprimido.

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. La mayoría de las herramientas de Visual Studio para la configuración de la gravedad de las reglas del analizador están actualizadas para trabajar con archivos EditorConfig, en lugar de con archivos de conjunto de reglas. Los archivos EditorConfig 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. Se recomienda convertir el archivo de conjunto de reglas existente en un archivo EditorConfig. Además, guarde el archivo EditorConfig en la raíz del repositorio o en la carpeta de la solución. Al usar la raíz del repositorio o la carpeta de la solución, asegúrese de que la configuración de la gravedad establecida en este archivo se aplica automáticamente a todo el repositorio o solución, respectivamente.

Hay dos maneras de convertir un archivo de conjunto de reglas existente en un archivo EditorConfig:

• Desde el Editor de conjuntos de reglas de Visual Studio (requiere Visual Studio 2019 16.5 o versiones posteriores). Si el proyecto ya usa un archivo de conjunto de reglas específico a modo de CodeAnalysisRuleSet, puede convertirlo en un archivo EditorConfig equivalente desde el Editor de conjuntos de reglas de Visual Studio.

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

     El archivo de conjunto de reglas se abrirá en el Editor de conjuntos de reglas. Debería ver una barra de información en la que se puede hacer clic en la parte superior del editor de conjuntos de reglas.

     

  2. Seleccione el vínculo de la barra de información.

     La acción debería abrir un cuadro de diálogo Guardar como que le permite seleccionar el directorio donde quiere generar el archivo EditorConfig.

  3. Seleccione el botón Guardar para generar el archivo EditorConfig.

     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.

• Desde la línea de comandos:

  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.

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

A continuación se muestra un archivo de conjunto de reglas de ejemplo que se va a convertir:

<?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>

A continuación se muestra el archivo EditorConfig convertido:

# 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

Establecer la gravedad de una regla desde el Explorador de soluciones

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 usa un archivo de conjunto de reglas en lugar de un archivo EditorConfig, la entrada de gravedad se agrega al archivo de conjunto de reglas.

   Sugerencia

   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.

Establecer la gravedad de una regla en el archivo de conjunto de reglas

1. Abra el archivo de conjunto de reglas activo de una de las maneras siguientes:

   • En el Explorador de soluciones, haga doble clic en el archivo, haga clic con el botón derecho en el nodo Referencias>Analizadores y seleccione Abrir conjunto de reglas activo.

     

   • En la página de propiedades Análisis de código del proyecto, seleccione Abrir.

   Si es la primera vez que edita el conjunto de reglas, Visual Studio hace una copia del archivo de conjunto de reglas predeterminado, le asigna el nombre <nombreDeProyecto>.ruleset y lo agrega al proyecto. Este conjunto de reglas personalizado también pasa a ser el conjunto de reglas activo del proyecto.

   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 la interfaz de usuario del editor de conjuntos de reglas de Visual Studio.

2. Vaya a la regla expandiendo el ensamblado que la contiene.

3. En la columna Acción, seleccione el valor para abrir una lista desplegable y elija la gravedad que quiera de la lista.

   

Configuración del código generado

Los analizadores se ejecutan en todos los archivos de origen de un proyecto y notifican las infracciones que se han producido en ellos. Pero las infracciones no son útiles en 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 los archivos y no les corresponde corregir infracciones en los archivos generados por herramientas.

De forma predeterminada, el controlador del analizador que ejecuta los analizadores trata 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 Visual Studio 2019 16.5, 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, se usaría esta entrada:

   [*.MyGenerated.cs]
   generated_code = true
   

Suprimir infracciones

Puede suprimir infracciones de reglas mediante varios métodos. Para obtener más 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 la compilación mediante el establecimiento de una propiedad de MSBuild.

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

• La gravedad de una regla infringida se establece en Advertencia (en cuyo caso las infracciones no provocan un error de compilación) o en Errorerror (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.

Sugerencia

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 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

En la siguiente imagen se 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, esos analizadores también se agregan automáticamente 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 en el archivo .csproj o .vbproj del proyecto al que se hace referencia; para ello, establezca el atributo PrivateAssets:

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

Consulte también

• 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 advertencias de análisis de código
• Opciones de configuración para el análisis de código (.NET)