Opciones del compilador de C#: notificación de errores y advertencias

Artículo
11/09/2023

Las opciones siguientes controlan cómo el compilador notifica los errores y las advertencias. La nueva sintaxis de MSBuild se muestra en negrita. La sintaxis de csc.exe anterior se muestra en code style.

WarningLevel / -warn: se establece el nivel de advertencia.
AnalysisLevel: se establece el nivel de advertencia opcional.
TreatWarningsAsErrors / -warnaserror: todas las advertencias se tratan como errores.
WarningsAsErrors / -warnaserror: una o varias advertencias se tratan como errores
WarningsNotAsErrors / -warnnotaserror: una o varias advertencias no se tratan como errores
NoWarn / -nowarn: se establece una lista de advertencias deshabilitadas.
CodeAnalysisRuleSet / -ruleset: se especifica un archivo de conjunto de reglas que deshabilita diagnósticos específicos.
ErrorLog / -errorlog: se especifica un archivo para registrar todos los diagnósticos del compilador y el analizador.
ReportAnalyzer / -reportanalyzer: se notifica información adicional del analizador, como el tiempo de ejecución.

WarningLevel

La opción WarningLevel especifica el nivel de advertencia que debe mostrar el compilador.

<WarningLevel>3</WarningLevel>

El valor del elemento es el nivel de advertencia que quiere que se muestre para la compilación: los números más bajos muestran solo advertencias de gravedad alta. Los números más altos muestran más advertencias. El valor debe ser cero o un entero positivo:

Nivel de advertencia	Significado
0	Desactiva la emisión de todos los mensajes de advertencia.
1	Muestra mensajes de advertencia graves.
2	Muestra advertencias de nivel 1 además de determinadas advertencias menos graves, como advertencias sobre ocultar miembros de clase.
3	Muestra advertencias de nivel 2 además de determinadas advertencias menos graves, como advertencias sobre expresiones que siempre se evalúan como `true` o `false`.
4 (valor predeterminado)	Muestra todas las advertencias de nivel 3 además de advertencias informativas.

Advertencia

La línea de comandos del compilador acepta valores mayores que 4 para permitir advertencias de ola de advertencias. Sin embargo, el SDK de .NET establece WarningLevel para que coincida con AnalysisLevel en el archivo del proyecto.

Para información sobre un error o advertencia, puede buscar el código de error en el Índice de la Ayuda. Para conocer otras maneras de obtener información sobre un error o advertencia, vea Errores del compilador de C#. Use TreatWarningsAsErrors para tratar todas las advertencias como errores. Use DisabledWarnings para deshabilitar advertencias concretas.

Nivel de análisis

La opción AnalysisLevel especifica las oleadas de advertencia adicionales y los analizadores que se van a habilitar. Las oleadas de advertencia son comprobaciones adicionales que mejoran el código o garantizan que será compatible con las próximas versiones. Los analizadores proporcionan una funcionalidad similar a Lint para mejorar el código.

<AnalysisLevel>preview</AnalysisLevel>

Nivel de análisis	Significado
5	Muestra todas las advertencias opcionales de la ola 5 de advertencias.
6	Muestra todas las advertencias opcionales de la ola 6 de advertencias.
7	Muestra todas las advertencias opcionales de la ola 7 de advertencias.
más reciente (valor predeterminado)	Muestra todas las advertencias informativas hasta la versión actual (esta inclusive).
Vista previa	Muestra todas las advertencias informativas hasta la versión preliminar más reciente (esta inclusive).
None	Desactiva todas las advertencias informativas.

Para más información sobre las advertencias opcionales, consulte Olas de advertencias.

Para obtener información sobre un error o advertencia, puede buscar el código de error en el Índice de la Ayuda. Para conocer otras maneras de obtener información sobre un error o advertencia, vea Errores del compilador de C#. Use TreatWarningsAsErrors para tratar todas las advertencias como errores. Use NoWarn para deshabilitar determinadas advertencias.

TreatWarningsAsErrors

La opción TreatWarningsAsErrors trata todas las advertencias como errores. También puede usar WarningsAsErrors para establecer solo algunas advertencias como errores. Si activa TreatWarningsAsErrors, puede usar WarningsNotAsErrors para enumerar las advertencias que no se deben tratar como errores.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

En su lugar, todos los mensajes de advertencia se notifican como errores. El proceso de compilación se detiene (no se genera ningún archivo de salida). De forma predeterminada, TreatWarningsAsErrors no está en efecto, lo que significa que las advertencias no impedirán la generación de un archivo de salida. Opcionalmente, si solo quiere que algunas advertencias específicas se traten como errores, puede especificar una lista separada por comas de números de advertencia que se tratarán como errores. Se puede especificar el conjunto de todas las advertencias de nulabilidad con la abreviatura Nullable. Use WarningLevel para especificar el nivel de advertencias que quiere que muestre el compilador. Use NoWarn para deshabilitar determinadas advertencias.

Importante

Hay dos diferencias sutiles entre el uso del elemento <TreatWarningsAsErrors> en el archivo csproj y el uso del modificador de línea de comandos de MSBuild warnaserror. TreatWarningsAsErrors solo afecta al compilador de C#, no a ninguna otra tarea de MSBuild del archivo csproj. El modificador de línea de comandos warnaserror afecta a todas las tareas. En segundo lugar, el compilador no genera ninguna salida en ninguna advertencia cuando se usa TreatWarningsAsErrors. El compilador genera la salida cuando se usa el modificador de línea de comandos warnaserror.

WarningsAsErrors y WarningsNotAsErrors

Las opciones WarningsAsErrors y WarningsNotAsErrors invalidan la opción TreatWarningsAsErrors de una lista de advertencias. Esta opción se puede usar con todas las advertencias de CS. El prefijo "CS" es opcional. Puede usar el número o "CS" seguido del número de error o advertencia. Para ver otros elementos que afectan a las advertencias, consulte las propiedades comunes de MSBuild.

Habilite las advertencias 0219 y 0168 como errores:

<WarningsAsErrors>0219,CS0168</WarningsAsErrors>

Deshabilite las mismas advertencias como errores:

<WarningsNotAsErrors>0219,CS0168</WarningsNotAsErrors>

Use WarningsAsErrors para configurar un conjunto de advertencias como errores. Use WarningsNotAsErrors para configurar un conjunto de advertencias que no deben ser errores cuando se han establecido todas las advertencias como errores.

NoWarn

La opción noWarn permite suprimir el compilador de mostrar una o varias advertencias, donde warningnumber1 y warningnumber2 son números de advertencia que desea que el compilador suprima. Separe varios números de advertencia con una coma.

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Solo tendrá que especificar la parte numérica del identificador de advertencia. Por ejemplo, si quiere suprimir CS0028, podría especificar <NoWarn>28</NoWarn>. El compilador omitirá silenciosamente los números de advertencia pasados a NoWarn que eran válidos en versiones anteriores, pero que se han quitado. Por ejemplo, CS0679 era válido en el compilador de Visual Studio .NET 2002, pero se ha eliminado posteriormente.

Las advertencias siguientes no se pueden suprimir mediante la opción NoWarn:

Advertencia del compilador (nivel 1) CS2002
Advertencia del compilador (nivel 1) CS2023
Advertencia del compilador (nivel 1) CS2029

Tenga en cuenta que las advertencias están pensadas para ser una indicación de un posible problema con el código, por lo que debe comprender los riesgos de deshabilitar cualquier advertencia determinada. Use NoWarn solo cuando esté seguro de que una advertencia es un falso positivo y no puede ser un error de runtime.

Es posible que quiera usar un enfoque más específico para deshabilitar las advertencias:

La mayoría de los compiladores proporcionan formas de deshabilitar las advertencias solo para determinadas líneas de código, de modo que pueda seguir revisando las advertencias si se producen en otro lugar del mismo proyecto. Para suprimir una advertencia solo en una parte específica del código de C#, use advertencia #pragma.
Si el objetivo es ver una salida más concisa y centrada en el registro de compilación, es posible que desee cambiar el nivel de detalle del registro de compilación. Para obtener más información, vea Cómo: Ver, guardar y configurar archivos de registro de compilación.

Para agregar números de advertencia a cualquier valor establecido previamente para NoWarn sin sobrescribirlo, haga referencia a $(NoWarn) como se muestra en el ejemplo siguiente:

   <NoWarn>$(NoWarn);newwarningnumber3;newwarningnumber4</NoWarn>

CodeAnalysisRuleSet

Especifica un archivo de conjunto de reglas que configura diagnósticos específicos.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

MyConfiguration.ruleset es la ruta del archivo de conjunto de reglas. Para obtener más información sobre el uso de conjuntos de reglas, vea el artículo en la documentación de Visual Studio sobre conjuntos de reglas.

ErrorLog

Especifique un archivo para registrar todos los diagnósticos del compilador y el analizador.

<ErrorLog>compiler-diagnostics.sarif</ErrorLog>

La opción ErrorLog hace que el compilador genere un registro de formato de intercambio de resultados de análisis estático (SARIF). Los registros SARIF suelen ser leídos por herramientas que analizan los resultados de los diagnósticos del compilador y el analizador.

Puede especificar el formato SARIF mediante el argumento version para el elemento ErrorLog:

<ErrorLog>logVersion21.json,version=2.1</ErrorLog>

El separador puede ser una coma (,) o un punto y coma (;). Los valores válidos para la versión son: "1", "2" y "2.1". El valor predeterminado es "1". "2" y "2.1" significan la versión 2.1.0 de SARIF.

ReportAnalyzer

Notifica información adicional del analizador, como el tiempo de ejecución.

<ReportAnalyzer>true</ReportAnalyzer>

La opción ReportAnalyzer hace que el compilador emita información de registro de MSBuild adicional en la que se detallan las características de rendimiento de los analizadores de la compilación. Los creadores del analizador la usan normalmente como parte de la validación del analizador.