Opciones del compilador de C# para las reglas de características del lenguaje

Las opciones siguientes controlan cómo el compilador interpreta las características del lenguaje. La nueva sintaxis de MSBuild se muestra en negrita. La sintaxis de csc.exe anterior se muestra en code style.

• CheckForOverflowUnderflow / -checked: se generan comprobaciones de desbordamiento.
• AllowUnsafeBlocks / -unsafe: se permite código "no seguro".
• DefineConstants / -define: se definen símbolos de compilación condicional.
• LangVersion / -langversion: se especifica la versión del lenguaje como default (versión principal más reciente) o latest (versión más reciente, incluidas las versiones secundarias).
• Nullable / -nullable: se habilita el contexto que admite un valor NULL o advertencias que admiten un valor NULL.

CheckForOverflowUnderflow

La opción CheckForOverflowUnderflow controla el contexto de comprobación de desbordamiento predeterminado que define el comportamiento del programa si el aritmético de enteros se desborda.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Cuando CheckForOverflowUnderflow es true, el contexto predeterminado es un contexto comprobado y la comprobación de desbordamiento está habilitada; de lo contrario, el contexto predeterminado es un contexto no comprobado. El valor predeterminado para esta opción es false; es decir, la comprobación de desbordamiento está deshabilitada.

También puede controlar explícitamente el contexto de comprobación de desbordamiento para las partes del código mediante las instrucciones checked y unchecked.

Para obtener información sobre cómo afecta el contexto de comprobación de desbordamiento a las operaciones y qué operaciones se ven afectadas, vea el artículo acerca de las instrucciones checked y unchecked.

AllowUnsafeBlocks

La opción del compilador AllowUnsafeBlocks permite la compilación de código en el que se usa la palabra clave unsafe. El valor predeterminado de esta opción es false, lo que significa que no se permite el código no seguro.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Para obtener más información sobre el código no seguro, vea Código no seguro y punteros.

DefineConstants

La opción DefineConstants define símbolos en todos los archivos de código fuente del programa.

<DefineConstants>name;name2</DefineConstants>

Esta opción especifica los nombres de uno o más símbolos que quiera definir. La opción DefineConstants tiene el mismo efecto que la directiva del preprocesador #define, salvo que la opción del compilador está en vigor para todos los archivos del proyecto. Un símbolo permanece definido en un archivo de origen hasta que una directiva #undef en el archivo de origen quita la definición. Cuando usa la opción -define, una directiva #undef en un archivo no tiene ningún efecto en otros archivos de código fuente del proyecto. Los símbolos creados por esta opción se pueden usar con #if, #else, #elif y #endif para compilar los archivos de origen condicionalmente. El propio compilador de C# no define ningún símbolo o macro que puede usar en su código fuente; todas las definiciones de símbolo deben definirse por el usuario.

LangVersion

La versión de idioma predeterminada para el compilador de C# depende de la plataforma de destino de la aplicación y la versión del SDK o de Visual Studio instalada. Esas reglas se definen en el control de versiones del lenguaje C#.

La opción LangVersion hace que el compilador acepte solo la sintaxis que se incluye en la especificación del lenguaje C# especificada, por ejemplo:

<LangVersion>9.0</LangVersion>

Valores válidos son:

Consideraciones

• Para asegurarse de que el proyecto usa la versión predeterminada del compilador recomendada para la plataforma de destino, no use la opción LangVersion. Puede actualizar la plataforma de destino para acceder a las características de lenguaje más recientes.

• Especificar LangVersion con el valor default es diferente de omitir la opción LangVersion. Al especificar default se usa la versión más reciente del lenguaje que admite el compilador, sin tener en cuenta la plataforma de destino. Por ejemplo, compilar un proyecto destinado a .NET 6 desde Visual Studio versión 17.6 usa C# 10 si no se especifica LangVersion, pero usa C# 11 si LangVersion está establecido en default.

• Los metadatos a los que hace referencia la aplicación de C# no están sujetos a la opción del compilador LangVersion.

• Como cada versión del compilador de C# contiene extensiones para la especificación del lenguaje, LangVersion no ofrece las funciones equivalentes de una versión anterior del compilador.

• Aunque las actualizaciones de versión de C# generalmente coinciden con las versiones principales de .NET, la sintaxis y las características nuevas no están necesariamente asociadas a esa versión de marco específica. Cada característica específica tiene su propia API mínima de .NET o requisitos de Common Language Runtime que pueden permitir que se ejecute en marcos de versiones anteriores mediante la inclusión de paquetes NuGet u otras bibliotecas.

• Independientemente de la configuración de LangVersion que utilice, use la versión actual de Common Language Runtime para crear el archivo .exe o .dll. Una excepción son los ensamblados de confianza y ModuleAssemblyName, que funcionan en -langversion:ISO-1.

Para obtener otras formas de especificar la versión del lenguaje C#, vea Control de versiones del lenguaje C#.

Para obtener información sobre cómo establecer esta opción del compilador mediante programación, vea LanguageVersion.

Especificación del lenguaje C#

Versión del SDK mínima necesaria para admitir todas las características del lenguaje

En la tabla siguiente se enumeran las versiones mínimas del SDK con el compilador de C# que admite la versión del lenguaje correspondiente:

Nullable

La opción Nullable le permite especificar el contexto que admite un valor NULL. Se puede establecer en la configuración del proyecto mediante la etiqueta <Nullable>:

<Nullable>enable</Nullable>

El argumento debe ser uno de enable, disable, warnings o annotations. El argumento enable habilita el contexto que admite un valor NULL. Si se especifica disable, se deshabilitará el contexto que admite un valor NULL. Al especificar el argumento warnings, se habilita el contexto de advertencia que admite un valor NULL. Al especificar el argumento annotations, se habilita el contexto de anotación que admite un valor NULL. Los valores se describen y se explican en el artículo sobre contextos que aceptan valores NULL. Puede obtener más información sobre las tareas implicadas en la habilitación de tipos de referencia que aceptan valores NULL en un código base existente en nuestro artículo sobre estrategias de migración que aceptan valores NULL.

El análisis de flujo se utiliza para inferir la nulabilidad de las variables del código ejecutable. La nulabilidad inferida de una variable es independiente de la nulabilidad declarada de dicha variable. Las llamadas de método se analizan incluso cuando se omiten de forma condicional. Es el caso de Debug.Assert en modo de versión.

La invocación de métodos anotados con los siguientes atributos también afectará al análisis de flujo:

• Condiciones previas simples: AllowNullAttribute y DisallowNullAttribute
• Condiciones posteriores simples: MaybeNullAttribute y NotNullAttribute
• Condiciones posteriores condicionales: MaybeNullWhenAttribute y NotNullWhenAttribute
• DoesNotReturnIfAttribute (por ejemplo, DoesNotReturnIf(false) para Debug.Assert) y DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Condiciones posteriores de miembros: MemberNotNullAttribute(String) y MemberNotNullAttribute(String[])