Usar analizadores de códigoUse code analyzers

Los analizadores de código .NET Compiler Platform ("Roslyn") C# analizan su código de o Visual Basic a medida que escribe..NET Compiler Platform ("Roslyn") code analyzers analyze your C# or Visual Basic code as you type. Cada diagnóstico o regla tiene una gravedad y un estado de supresión predeterminados que se pueden sobrescribir para el proyecto.Each diagnostic or rule has a default severity and suppression state that can be overwritten for your project. En este artículo se describe la configuración de la gravedad de la regla, el uso de conjuntos de reglas y la supresión de infracciones.This article covers setting rule severity, using rule sets, and suppressing violations.

Analizadores en Explorador de solucionesAnalyzers in Solution Explorer

Puede realizar gran parte de la personalización de diagnósticos de analizador desde Explorador de soluciones.You can do much of the customization of analyzer diagnostics from Solution Explorer. Si instala analizadores como un paquete de NuGet, aparece un nodo analizadores en el nodo referencias o dependencias en Explorador de soluciones.If you install analyzers as a NuGet package, an Analyzers node appears under the References or Dependencies node in Solution Explorer. Si expande analizadoresy, a continuación, expande uno de los ensamblados del analizador, verá todos los diagnósticos en el ensamblado.If you expand Analyzers, and then expand one of the analyzer assemblies, you see all the diagnostics in the assembly.

Nodo analizadores en Explorador de soluciones

Puede ver las propiedades de un diagnóstico, incluida su descripción y gravedad predeterminada, en la ventana propiedades .You can view the properties of a diagnostic, including its description and default severity, in the Properties window. Para ver las propiedades, haga clic con el botón derecho en la regla y seleccione propiedades, o seleccione la regla y, a continuación, presione Alt+entrar.To view the properties, right-click on the rule and select Properties, or select the rule and then press Alt+Enter.

Propiedades de diagnóstico en ventana Propiedades

Para ver la documentación en línea de un diagnóstico, haga clic con el botón derecho en el diagnóstico y seleccione Ver ayuda.To see online documentation for a diagnostic, right-click on the diagnostic and select View Help.

Los iconos situados junto a cada diagnóstico en Explorador de soluciones corresponden a los iconos que aparecen en el conjunto de reglas cuando se abre en el editor:The icons next to each diagnostic in Solution Explorer correspond to the icons you see in the rule set when you open it in the editor:

  • la "x" en un círculo indica una gravedad de errorthe "x" in a circle indicates a severity of Error
  • el "!" de un triángulo indica una gravedad de ADVERTENCIAthe "!" in a triangle indicates a severity of Warning
  • la "i" en un círculo indica una gravedad de la informaciónthe "i" in a circle indicates a severity of Info
  • la "i" en un círculo de un fondo de color claro indica una gravedad de ocultathe "i" in a circle on a light-colored background indicates a severity of Hidden
  • la flecha hacia abajo de un círculo indica que se ha suprimido el diagnóstico.the downward-pointing arrow in a circle indicates that the diagnostic is suppressed

Iconos de diagnósticos en Explorador de soluciones

Gravedad de las reglasRule severity

Puede configurar la gravedad de las reglas del analizador, o diagnósticos, si instala los analizadores como un paquete NuGet.You can configure the severity of analyzer rules, or diagnostics, if you install the analyzers as a NuGet package. A partir de la versión 16,3 de Visual Studio 2019, puede configurar la gravedad de una regla en un archivo EditorConfig.Starting in Visual Studio 2019 version 16.3, you can configure the severity of a rule in an EditorConfig file. También puede cambiar la gravedad de una regla de explorador de soluciones o de un archivo de conjunto de reglas.You can also change the severity of a rule from Solution Explorer or in a rule set file.

Puede configurar la gravedad de las reglas del analizador, o diagnósticos, si instala los analizadores como un paquete NuGet.You can configure the severity of analyzer rules, or diagnostics, if you install the analyzers as a NuGet package. Puede cambiar la gravedad de una regla de explorador de soluciones o de un archivo de conjunto de reglas.You can change the severity of a rule from Solution Explorer or in a rule set file.

En la tabla siguiente se muestran las diferentes opciones de gravedad:The following table shows the different severity options:

Gravedad (Explorador de soluciones)Severity (Solution Explorer) Gravedad (archivo EditorConfig)Severity (EditorConfig file) Comportamiento en tiempo de compilaciónBuild-time behavior Comportamiento del editorEditor behavior
ErrorError error Las infracciones aparecen como errores en el lista de errores y en la salida de la compilación de línea de comandos y provocan un error en las compilaciones.Violations appear as Errors in the Error List and in command-line build output, and cause builds to fail. 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.Offending code is underlined with a red squiggle and marked by a small red box in the scroll bar.
AdvertenciaWarning warning Las infracciones aparecen como advertencias en el lista de errores y en la salida de la compilación de línea de comandos, pero no provocan errores en las compilaciones.Violations appear as Warnings in the Error List and in command-line build output, but do not cause builds to fail. 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.Offending code is underlined with a green squiggle and marked by a small green box in the scroll bar.
InfoInfo suggestion Las infracciones aparecen como mensajes en el lista de errores y no en todos los resultados de la compilación de línea de comandos.Violations appear as Messages in the Error List, and not at all in command-line build output. 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.Offending code is underlined with a gray squiggle and marked by a small gray box in the scroll bar.
HiddenHidden silent No es visible para el usuario.Non-visible to user. No es visible para el usuario.Non-visible to user. Sin embargo, el diagnóstico se envía al motor de diagnóstico del IDE.The diagnostic is reported to the IDE diagnostic engine, however.
NoneNone none Se han suprimido por completo.Suppressed completely. Se han suprimido por completo.Suppressed completely.
DefaultDefault default Corresponde a la gravedad predeterminada de la regla.Corresponds to the default severity of the rule. Para determinar cuál es el valor predeterminado de una regla, mire en el ventana Propiedades.To determine what the default value for a rule is, look in the Properties window. Corresponde a la gravedad predeterminada de la regla.Corresponds to the default severity of the rule.

La siguiente captura de pantalla del editor de código muestra tres infracciones diferentes con diferentes niveles de gravedad.The following screenshot of the code editor shows three different violations with different severities. Observe el color de la línea ondulada y el cuadrado pequeño coloreado en la barra de desplazamiento de la derecha.Notice the color of the squiggle and the small, colored square in the scroll bar on the right.

Infracción de error, advertencia e información en el editor de código

En la captura de pantalla siguiente se muestran las tres infracciones que aparecen en el Lista de errores:The following screenshot shows the same three violations as they appear in the Error List:

Infracción de error, advertencia e información en Lista de errores

Establecer la gravedad de la regla en un archivo EditorConfigSet rule severity in an EditorConfig file

(Visual Studio 2019 versión 16,3 y versiones posteriores)(Visual Studio 2019 version 16.3 and later)

La sintaxis general para especificar la gravedad de una regla en un archivo EditorConfig es la siguiente:The general syntax for specifying the severity of a rule in an EditorConfig file is as follows:

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 Explorador de soluciones.Setting a rule's severity in an EditorConfig file takes precedence over any severity that's set in a rule set or in Solution Explorer. Puede configurar manualmente la gravedad en un archivo EditorConfig o automáticamente a través de la bombilla que aparece junto a una infracción.You can manually configure severity in an EditorConfig file or automatically through the light bulb that appears next to a violation.

Configurar manualmente la gravedad de la reglaManually configure rule severity

  1. Si aún no tiene un archivo EditorConfig para el proyecto, agregue uno.If you don't already have an EditorConfig file for your project, add one.

  2. Agregue una entrada para cada regla que desee configurar en la extensión de archivo correspondiente.Add an entry for each rule you want to configure under the corresponding file extension. Por ejemplo, para establecer la gravedad de CA1822 en error para C# los archivos, la entrada tiene el siguiente aspecto:For example, to set the severity for CA1822 to error for C# files, the entry looks as follows:

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

Note

En el caso de los analizadores de estilo de código IDE, también puede configurarlos en un archivo EditorConfig con una sintaxis diferente, por ejemplo, dotnet_style_qualification_for_field = false:suggestion.For IDE code-style analyzers, you can also configure them in an EditorConfig file using a different syntax, for example, dotnet_style_qualification_for_field = false:suggestion. Sin embargo, si establece una gravedad mediante la sintaxis dotnet_diagnostic, tendrá prioridad.However, if you set a severity using the dotnet_diagnostic syntax, it takes precedence. Para obtener más información, vea convenciones de lenguaje para EditorConfig.For more information, see Language conventions for EditorConfig.

Configurar automáticamente la gravedad de la reglaAutomatically configure rule severity

Visual Studio proporciona una manera cómoda de configurar la gravedad de una regla en el menú de bombillas de acciones rápidas .Visual Studio provides a convenient way to configure a rule's severity from the Quick Actions light bulb menu.

  1. Después de que se produzca una infracción, mantenga el mouse sobre la línea ondulada en el editor y abra el menú de bombilla.After a violation occurs, hover over the violation squiggle in the editor and open the light bulb menu. O bien, coloque el cursor en la línea y presione Ctrl+ .Or, put your cursor on the line and press Ctrl+. (punto).(period).

  2. En el menú de bombilla, seleccione configurar o suprimir problemas > Configure <rule ID > Severity.From the light bulb menu, select Configure or Suppress issues > Configure <rule ID> severity.

    Configurar la gravedad de la regla desde el menú de bombilla en Visual Studio

  3. Desde allí, seleccione una de las opciones de gravedad.From there, select one of the severity options.

    Configurar la gravedad de la regla como sugerencia

    Visual Studio agrega una entrada al archivo EditorConfig para configurar la regla en el nivel solicitado, tal como se muestra en el cuadro vista previa.Visual Studio adds an entry to the EditorConfig file to configure the rule to the requested level, as shown in the preview box.

    Tip

    Si aún no tiene un archivo EditorConfig en el proyecto, Visual Studio crea uno automáticamente.If you don't already have an EditorConfig file in the project, Visual Studio creates one for you.

Establecer la gravedad de la regla desde Explorador de solucionesSet rule severity from Solution Explorer

  1. En Explorador de soluciones, expanda referencias alosanalizadores > (o las dependencias@no__t-**5 para los** proyectos de .net Core).In Solution Explorer, expand References > Analyzers (or Dependencies > Analyzers for .NET Core projects).

  2. Expanda el ensamblado que contiene la regla para la que desea establecer la gravedad.Expand the assembly that contains the rule you want to set severity for.

  3. Haga clic con el botón derecho en la regla y seleccione establecer gravedad del conjunto de reglas.Right-click on the rule and select Set Rule Set Severity. En el menú emergente, seleccione una de las opciones de gravedad.In the fly-out menu, select one of the severity options.

    La gravedad de la regla se guarda en el archivo de conjunto de reglas activo.The severity for the rule is saved in the active rule set file.

Establecer la gravedad de la regla en el archivo de conjunto de reglasSet rule severity in the rule set file

Archivo de conjunto de reglas en Explorador de soluciones

  1. Abra el archivo del conjunto de reglas activo haciendo doble clic en él en Explorador de soluciones, seleccionando abrir conjunto de reglas activas en el menú contextual del nodo referencias > analizadores o seleccionando abrir en el código. Página de propiedades de análisis del proyecto.Open the active rule set file by double-clicking it in Solution Explorer, selecting Open Active Rule Set on the right-click menu of the References > Analyzers node, or by selecting Open on the Code Analysis property page for the project.

    Si es la primera vez que está editando el conjunto de reglas, Visual Studio realiza una copia del archivo de conjunto de reglas predeterminado, lo denomina <projectname >. rulesety lo agrega al proyecto.If this is the first time you're editing the rule set, Visual Studio makes a copy of the default rule set file, names it <projectname>.ruleset, and adds it to your project. Este conjunto de reglas personalizado también se convierte en el conjunto de reglas activo para el proyecto.This custom rule set also becomes the active rule set for your project.

    Note

    Los proyectos de .NET Core y .NET Standard no admiten los comandos de menú para conjuntos de reglas en Explorador de soluciones, por ejemplo, abrir el conjunto de reglas activo..NET Core and .NET Standard projects do not support the menu commands for rule sets in Solution Explorer, for example, Open Active Rule Set. Para especificar un conjunto de reglas no predeterminado para un proyecto de .NET Core o .NET Standard, agregue manualmente la propiedad CodeAnalysisRuleSet al archivo de proyecto.To specify a non-default rule set for a .NET Core or .NET Standard project, manually add the CodeAnalysisRuleSet property to the project file. Todavía puede configurar las reglas en el conjunto de reglas en la interfaz de usuario del editor de conjuntos de reglas de Visual Studio.You can still configure the rules within the rule set in the Visual Studio rule set editor UI.

  2. Vaya a la regla expandiendo su ensamblado contenedor.Browse to the rule by expanding its containing assembly.

  3. En la columna acción , seleccione el valor para abrir una lista desplegable y seleccione la gravedad deseada en la lista.In the Action column, select the value to open a drop-down list, and select the desired severity from the list.

    Archivo de conjunto de reglas abierto en el editor

Suprimir infraccionesSuppress violations

Hay varias maneras de suprimir las infracciones de reglas:There are multiple ways to suppress rule violations:

  • En un archivo EditorConfigIn an EditorConfig file

    Establezca la gravedad en none, por ejemplo, dotnet_diagnostic.CA1822.severity = none.Set the severity to none, for example, dotnet_diagnostic.CA1822.severity = none.

  • En el menú analizarFrom the Analyze menu

    Seleccione analizar > compilación y suprimir problemas activos en la barra de menús para suprimir todas las infracciones actuales.Select Analyze > Build and Suppress Active Issues on the menu bar to suppress all current violations. A veces, esto se conoce como "línea de referencia".This is sometimes referred to as "baselining".

  • En el menú analizarFrom the Analyze menu

    Seleccione analizar > Ejecutar Análisis de código y suprimir problemas activos en la barra de menús para suprimir todas las infracciones actuales.Select Analyze > Run Code Analysis and Suppress Active Issues on the menu bar to suppress all current violations. A veces, esto se conoce como "línea de referencia".This is sometimes referred to as "baselining".

  • Desde Explorador de solucionesFrom Solution Explorer

    Establezca la gravedad de la regla en ninguno.Set the rule's severity to None.

  • En el Editor de conjuntos de reglasFrom the rule set editor

    Desactive la casilla situada junto a su nombre o establezca acción en ninguno.Uncheck the box next to its name or set Action to None.

  • Desde el Editor de códigoFrom the code editor

    Coloque el cursor en la línea de código con la infracción y presione Ctrl+punto (.) para abrir el menú acciones rápidas .Place the cursor in the line of code with the violation and press Ctrl+Period (.) to open the Quick Actions menu. Seleccione suprimir CAXXXX > en origen o en archivo de supresión.Select Suppress CAXXXX > in Source/in Suppression File.

    Suprimir diagnóstico del menú acciones rápidas

  • Desde el lista de erroresFrom the Error List

    Seleccione las reglas que desea suprimir y, a continuación, haga clic con el botón derecho y seleccione suprimir > en origen/en el archivo de supresión.Select the rules you want to suppress, and then right-click and select Suppress > In Source/In Suppression File.

    • Si se suprime en origen, se abre el cuadro de diálogo vista previa de los cambios y se muestra una vista previa de la C# #pragma ADVERTENCIA o Visual Basic #Disable Directiva de ADVERTENCIA que se agrega al código fuente.If you suppress In Source, the Preview Changes dialog opens and shows a preview of the C# #pragma warning or Visual Basic #Disable warning directive that's added to the source code.

      Vista previa de la adición de #pragma ADVERTENCIA en el archivo de código

    • Si selecciona en archivo de supresión, se abre el cuadro de diálogo vista previa de los cambios y se muestra una vista previa del atributo SuppressMessageAttribute que se agrega al archivo de supresiones global.If you select In Suppression File, the Preview Changes dialog opens and shows a preview of the SuppressMessageAttribute attribute that's added to the global suppressions file.

      Vista previa de la adición del atributo SuppressMessage al archivo de supresión

    En el cuadro de diálogo vista previa de los cambios , seleccione aplicar.In the Preview Changes dialog, select Apply.

    Note

    Si no ve la opción de menú suprimir en Explorador de soluciones, es probable que la infracción provenga de la compilación y no del análisis activo.If you don't see the Suppress menu option in Solution Explorer, the violation is likely coming from build and not live analysis. El lista de errores muestra los diagnósticos, o las infracciones de las reglas, desde el análisis de código activo y la compilación.The Error List displays diagnostics, or rule violations, from both live code analysis and build. Como los diagnósticos de compilación pueden estar obsoletos, por ejemplo, si ha editado el código para corregir la infracción pero no se ha vuelto a generar, no podrá suprimir estos diagnósticos del lista de errores.Since the build diagnostics can be stale, for example, if you've edited the code to fix the violation but haven't rebuilt, you cannot suppress these diagnostics from the Error List. Los diagnósticos del análisis en vivo, o IntelliSense, siempre están actualizados con los orígenes actuales y se pueden suprimir del lista de errores.Diagnostics from live analysis, or IntelliSense, are always up-to-date with current sources and can be suppressed from the Error List. Para excluir diagnósticos de compilación de la selección, cambie el lista de errores filtro de origen de compilación + IntelliSense a solo IntelliSense.To exclude build diagnostics from your selection, switch the Error List source filter from Build + IntelliSense to IntelliSense Only. A continuación, seleccione los diagnósticos que desea suprimir y continúe como se describió anteriormente.Then, select the diagnostics you want to suppress and proceed as described previously.

    Lista de errores filtro de origen en Visual Studio

Uso de la línea de comandosCommand-line usage

Al compilar el proyecto en la línea de comandos, las infracciones de la regla aparecen en la salida de la compilación si se cumplen las condiciones siguientes:When you build your project at the command line, rule violations appear in the build output if the following conditions are met:

  • Los analizadores se instalan como un paquete Nuget y no como una extensión VSIX.The analyzers are installed as a Nuget package and not as a VSIX extension.

  • Una o varias reglas se infringen en el código del proyecto.One or more rules are violated in the project's code.

  • La gravedad de una regla infringida se establece en cualquiera de las advertencias, en cuyo caso las infracciones no provocan un error en la compilación, o error, en cuyo caso las infracciones causan un error en la compilación.The severity of a violated rule is set to either warning, in which case violations don't cause build to fail, or error, in which case violations cause build to fail.

El nivel de detalle de la salida de la compilación no afecta a si se muestran las infracciones de la regla.The verbosity of the build output does not affect whether rule violations are shown. Incluso con un nivel de detalle silencioso , las infracciones de reglas aparecen en la salida de la compilación.Even with quiet verbosity, rule violations appear in the build output.

Tip

Si está acostumbrado a ejecutar el análisis heredado desde la línea de comandos, ya sea con FxCopCmd. exe o a través de MSBuild con la marca RunCodeAnalysis , aquí se muestra cómo hacerlo con los analizadores de código.If you're accustomed to running legacy analysis from the command line, either with FxCopCmd.exe or through msbuild with the RunCodeAnalysis flag, here's how to do that with code analyzers.

Para ver las infracciones del analizador en la línea de comandos al compilar el proyecto con MSBuild, ejecute un comando similar al siguiente:To see analyzer violations at the command line when you build your project using msbuild, run a command like this:

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

En la imagen siguiente se muestra el resultado de la compilación de la línea de comandos de compilar un proyecto que contiene una infracción de la regla del analizador:The following image shows the command-line build output from building a project that contains an analyzer rule violation:

Salida de MSBuild con infracción de regla

Proyectos dependientesDependent projects

En un proyecto de .NET Core, si agrega una referencia a un proyecto que tiene analizadores de NuGet, esos analizadores también se agregan automáticamente al proyecto dependiente.In a .NET Core project, if you add a reference to a project that has NuGet analyzers, those analyzers are automatically added to the dependent project too. 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 estableciendo el atributo PrivateAssets :To disable this behavior, for example if the dependent project is a unit test project, mark the NuGet package as private in the .csproj or .vbproj file of the referenced project by setting the PrivateAssets attribute:

<PackageReference Include="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="2.9.0" PrivateAssets="all" />

Vea tambiénSee also