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

  • Artículo

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.

Nota

Los analizadores de .NET son independientes de la plataforma de destino. Es decir, el proyecto no necesita tener como destino una implementación de .NET específica. Los analizadores funcionan para proyectos que tienen como destino .NET 5+ y versiones anteriores de .NET, como .NET Core 3.1 y .NET Framework 4.7.2. Pero para habilitar el análisis de código mediante la propiedad EnableNETAnalyzers, el proyecto debe hacer referencia a un SDK de proyecto.

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.

Sugerencia

Si usa Visual Studio, muchas reglas de analizador tienen correcciones de código asociadas que se pueden aplicar para corregir el problema. Las correcciones de código se muestran en el menú del icono de bombilla.

Reglas habilitadas

Las siguientes reglas están habilitadas de forma predeterminada como errores o advertencias en .NET 8. Se habilitan reglas adicionales como sugerencias.

Id. de diagnóstico Category Gravedad Versión agregada Descripción
CA1416 Interoperabilidad Advertencia .NET 5 Validación de la compatibilidad con las plataformas
CA1417 Interoperabilidad Advertencia .NET 5 No usar OutAttribute en parámetros de cadena para P/Invoke
CA1418 Interoperabilidad Advertencia .NET 6 Uso de una cadena de plataforma válida
CA1420 Interoperabilidad Advertencia .NET 7 El uso de características que requieren serialización en tiempo de ejecución cuando esta está deshabilitada producirá excepciones en tiempo de ejecución.
CA1422 Interoperabilidad Advertencia .NET 7 Validación de la compatibilidad con las plataformas
CA1831 Rendimiento Advertencia .NET 5 Usar AsSpan en lugar de indizadores basados en intervalos para una cadena cuando proceda
CA1856 Rendimiento Error .NET 8 Uso incorrecto del atributo ConstantExpected
CA1857 Rendimiento Advertencia .NET 8 Se espera una constante para el parámetro
CA2013 Confiabilidad Advertencia .NET 5 No usar ReferenceEquals con tipos de valor
CA2014 Confiabilidad Advertencia .NET 5 No usar stackalloc en bucles
CA2015 Confiabilidad Advertencia .NET 5 No definir finalizadores para los tipos derivados de MemoryManager<T>
CA2017 Confiabilidad Advertencia .NET 6 El recuento de parámetros no coincide
CA2018 Confiabilidad Advertencia .NET 6 El argumento count para Buffer.BlockCopy debe especificar el número de bytes que se copiará
CA2021 Confiabilidad Advertencia .NET 8 No llame a Enumerable.Cast<T> ni Enumerable.OfType<T> con tipos incompatibles
CA2200 Uso Advertencia .NET 5 Reiniciar para mantener los detalles de la pila
CA2247 Uso Advertencia .NET 5 El argumento pasado al constructor TaskCompletionSource debe ser una enumeración TaskCreationOptions en lugar de TaskContinuationOptions
CA2252 Uso Error .NET 6 Participación en las características en versión preliminar
CA2255 Uso Advertencia .NET 6 El atributo ModuleInitializer no debe usarse en bibliotecas
CA2256 Uso Advertencia .NET 6 Todos los miembros declarados en interfaces primarias deben tener una implementación en una interfaz con atributos DynamicInterfaceCastableImplementation
CA2257 Uso Advertencia .NET 6 Los miembros definidos en una interfaz con DynamicInterfaceCastableImplementationAttribute deben ser static
CA2258 Uso Advertencia .NET 6 No se admite proporcionar una interfaz DynamicInterfaceCastableImplementation en Visual Basic
CA2259 Uso Advertencia .NET 7 ThreadStatic afecta únicamente a los campos estáticos.
CA2260 Uso Advertencia .NET 7 Use el parámetro de tipo correcto.
CA2261 Uso Advertencia .NET 8 No utilice ConfigureAwaitOptions.SuppressThrowing con Task<TResult>

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

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:

Valor Descripción
None Todas las reglas están deshabilitadas. Puede incluir de forma selectiva reglas individuales para habilitarlas.
Default Modo predeterminado, en el que ciertas reglas están habilitadas como advertencias de compilación, otras están habilitadas como sugerencias del IDE de Visual Studio y el resto están deshabilitadas.
Minimum Modo más agresivo que el modo Default. Algunas sugerencias que se recomiendan encarecidamente para el cumplimiento de la compilación se habilitan como advertencias de compilación. Para ver qué reglas incluye, inspeccione el archivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modo más agresivo que el modo Minimum, donde se habilitan más reglas como advertencias de compilación. Para ver qué reglas incluye, inspeccione el archivo %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Todas las reglas están habilitadas como advertencias de compilación*. Puede excluir de forma selectiva reglas individuales para deshabilitarlas.

* Las reglas siguientes no se habilitan al establecer AnalysisMode en All o establecer AnalysisLevel en latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 y las reglas del analizador de métricas de código (CA1501, CA1502, CA1505, CA1506 y CA1509). Estas reglas heredadas podrían quedar en desuso en versiones futuras. Pero todavía es posible habilitarlas individualmente mediante una entrada dotnet_diagnostic.CAxxxx.severity = <severity>.

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.

Ejecución del análisis de código como Acción de GitHub

La Acción de GitHub dotnet/code-analysis permite ejecutar analizadores de código de .NET como parte de la integración continua (CI) en un modo sin conexión. Para obtener más información, vea Acción de GitHub de análisis de código de .NET.

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