Información general sobre el análisis de código fuente de .NET

Los analizadores de .NET Compiler Platform (Roslyn) inspeccionan el código de C# o Visual Basic para supervisar la calidad e identificar problemas de estilo. A partir de .NET 5, estos analizadores se incluyen con el SDK de .NET y no es necesario instalarlos por separado. Si el proyecto tiene como destino .NET 5 o una versión posterior, el análisis de código está habilitado de forma predeterminada. Si el proyecto tiene como destino otra implementación de .NET, por ejemplo, .NET Core, .NET Standard o .NET Framework, debe establecer la propiedad EnableNETAnalyzers en true para habilitar manualmente el análisis de código.

Si no quiere cambiar al SDK de .NET 5+, tiene un proyecto de .NET Framework de estilo de SDK, o bien prefiere un modelo basado en paquetes NuGet, los analizadores también están disponibles en el paquete NuGet Microsoft.CodeAnalysis.NetAnalyzers. Es posible que prefiera un modelo basado en paquetes para las actualizaciones de versión a petición.

Si un analizador detecta infracciones de reglas, se notifican como una sugerencia, una advertencia o un error, en función de cómo esté configurada cada regla. Las infracciones de análisis de código aparecen con el prefijo "CA" o "IDE" para diferenciarlas de los errores del compilador.

Análisis de calidad del código

Las reglas de análisis de calidad del código ("CAxxxx") inspeccionan el código de C# o Visual Basic en busca de incidencias de seguridad, rendimiento, diseño y de otro tipo. De forma predeterminada, el análisis está habilitado para los proyectos que tienen como destino .NET 5 o una versión posterior. Puede habilitar el análisis de código en los proyectos que tengan como destino versiones anteriores de .NET estableciendo la propiedad EnableNETAnalyzers en true. También puede deshabilitar el análisis de código para el proyecto si establece EnableNETAnalyzers en false.

Reglas habilitadas

Puede cambiar la gravedad de estas reglas para deshabilitarlas o elevarlas a errores. También puede habilitar más reglas.

• Para obtener una lista de las reglas que se incluyen con cada versión del SDK de .NET, vea Versiones del analizador.
• Para obtener una lista de todas las reglas de calidad del código, vea Reglas de calidad del código.

Habilitación de reglas adicionales

El modo de análisis hace referencia a una configuración de análisis de código predefinida en la que ninguna, algunas o todas las reglas están habilitadas. En el modo de análisis predeterminado (Default), solo se habilita un pequeño número de reglas como advertencias de compilación. Puede cambiar el modo de análisis del proyecto si establece la propiedad <AnalysisMode> en el archivo del proyecto. Entre los valores permitidos se incluyen los siguientes:

A partir de .NET 6, puede omitir <AnalysisMode> en favor de un valor compuesto para la propiedad <AnalysisLevel>. Por ejemplo, el siguiente valor habilita el conjunto de reglas recomendado para la versión más reciente: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Para obtener más información, vea AnalysisLevel.

Para buscar la gravedad predeterminada de cada regla disponible y si la regla está habilitada o no en el modo de análisis predeterminado (Default), vea la lista completa de reglas.

Tratar advertencias como errores

Si usa la marca -warnaserror al compilar los proyectos, todas las advertencias de análisis de código también se tratan como errores. Si no quiere que las advertencias de calidad del código (CAxxxx) se traten como errores cuando -warnaserror está presente, puede establecer la propiedad CodeAnalysisTreatWarningsAsErrors de MSBuild en false en el archivo del proyecto.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Todavía verá advertencias de análisis de código, pero no interrumpirán la compilación.

Actualizaciones más recientes

De forma predeterminada, obtendrá las reglas de análisis de código más recientes y las gravedades de las reglas predeterminadas a medida que actualice a las versiones más recientes del SDK de .NET. Si no quiere este comportamiento, por ejemplo, si quiere asegurarse de que no se habiliten o deshabiliten las reglas nuevas, puede invalidarlo de una de las siguientes maneras:

• Establezca la propiedad AnalysisLevel de MSBuild en un valor específico para bloquear las advertencias a ese conjunto. Al actualizar a un SDK más reciente, todavía obtendrá correcciones de errores para esas advertencias, pero no se habilitarán nuevas advertencias y no se deshabilitarán las existentes. Por ejemplo, para limitar el conjunto de reglas a las que se incluyen en la versión 5.0 del SDK de .NET, agregue la entrada siguiente al archivo del proyecto.

  <PropertyGroup>
    <AnalysisLevel>5.0</AnalysisLevel>
  </PropertyGroup>
  

  Sugerencia

  El valor predeterminado de la propiedad AnalysisLevel es latest, lo que significa que siempre obtendrá las reglas de análisis de código más recientes al cambiar a versiones más recientes del SDK de .NET.

  Para obtener más información y una lista de los valores posibles, vea AnalysisLevel.

• Instale el paquete NuGet Microsoft.CodeAnalysis.NetAnalyzers para desacoplar las actualizaciones de reglas de las actualizaciones del SDK de .NET. En los proyectos que tienen como destino .NET 5+, la instalación del paquete desactiva los analizadores integrados del SDK. Obtendrá una advertencia de compilación si el SDK contiene una versión más reciente del ensamblado del analizador que la del paquete NuGet. Para deshabilitar la advertencia, establezca la propiedad _SkipUpgradeNetAnalyzersNuGetWarning en true.

  Nota

  Si instala el paquete NuGet Microsoft.CodeAnalysis.NetAnalyzers, no debe agregar la propiedad EnableNETAnalyzers al archivo del proyecto ni a un archivo Directory.Build.props. Cuando se instala el paquete NuGet y la propiedad EnableNETAnalyzers se establece en true, se genera una advertencia de compilación.

Análisis de estilo de código

Las reglas de análisis de estilo de código ("IDExxxx") permiten definir y mantener un estilo de código coherente en el código base. Los valores de habilitación predeterminados son los siguientes:

• Compilación de línea de comandos: el análisis de estilo de código está deshabilitado de forma predeterminada para todos los proyectos de .NET en compilaciones de línea de comandos.

  A partir de .NET 5, puede habilitar el análisis de estilo de código durante la compilación, tanto en la línea de comandos como en Visual Studio. Las infracciones de estilo de código aparecen como advertencias o errores con un prefijo "IDE". Esto le permite aplicar estilos de código coherentes en tiempo de compilación.

• Visual Studio: el análisis de estilo de código está habilitado, de forma predeterminada, para todos los proyectos de .NET dentro de Visual Studio como acciones rápidas de refactorización de código.

Para obtener una lista completa de las reglas de análisis de estilo de código, vea Reglas de estilo de código.

Habilitación durante la compilación

Con el SDK de .NET 5 y versiones posteriores, puede habilitar el análisis de estilo de código al realizar la compilación desde la línea de comandos y en Visual Studio. (Pero por motivos de rendimiento, se seguirán aplicando una serie de reglas de estilo de código solo en el IDE de Visual Studio).

Siga estos pasos para habilitar el análisis de estilo de código durante la compilación:

1. Establezca la propiedad EnforceCodeStyleInBuild de MSBuild en true.

2. En un archivo .editorconfig, configure cada regla de estilo de código "IDE" que quiera ejecutar durante la compilación como una advertencia o un error. Por ejemplo:

   [*.{cs,vb}]
   # IDE0040: Accessibility modifiers required (escalated to a build warning)
   dotnet_diagnostic.IDE0040.severity = warning
   

   Sugerencia

   A partir de .NET 9, también puede usar el formato de opción para especificar una gravedad y hacer que se respete en tiempo de compilación. Por ejemplo:

   [*.{cs,vb}]
   # IDE0040: Accessibility modifiers required (escalated to a build warning)
   dotnet_style_require_accessibility_modifiers = always:warning
   

   Como alternativa, puede configurar una categoría completa para que sea una advertencia o un error, de forma predeterminada y, después, desactivar de forma selectiva las reglas de esa categoría que no quiera que se ejecuten durante la compilación. Por ejemplo:

   [*.{cs,vb}]
   
   # Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
   dotnet_analyzer_diagnostic.category-Style.severity = warning
   
   # IDE0040: Accessibility modifiers required (disabled on build)
   dotnet_diagnostic.IDE0040.severity = silent
   

Supresión de una advertencia

Una manera de suprimir una infracción de una regla consiste en establecer la opción de gravedad del id. de esa regla en none en un archivo EditorConfig. Por ejemplo:

dotnet_diagnostic.CA1822.severity = none

Para obtener más información y otras formas de suprimir las advertencias, vea Cómo suprimir advertencias de análisis de código.

Analizadores de terceros

Además de los analizadores de .NET oficiales, también puede instalar analizadores de terceros, como StyleCop, Roslynator,Analizadores de XUnit y Sonar Analyzer.

Vea también

• Referencia de reglas de análisis de calidad del código
• Referencia de reglas de análisis de estilo del código
• Análisis de código en Visual Studio
• SDK de la plataforma del compilador de .NET
• Tutorial: Crear el primer analizador y la corrección de código
• Análisis de código en aplicaciones de ASP.NET Core