Opciones del compilador de C# para reglas de características de 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: permitir unsafe código.
• DefineConstants / -define: defina 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. Cuando CheckForOverflowUnderflow es false, el contexto predeterminado es un contexto no comprobado. El valor predeterminado de esta opción es false, lo que significa que la comprobación de desbordamiento está deshabilitada.

También puede controlar explícitamente el contexto de comprobación de desbordamiento para 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 a qué operaciones afecta, consulte el artículo sobre checked las instrucciones 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.

Habilitación de las reglas de seguridad de memoria actualizadas

Las reglas de seguridad de memoria actualizadas son una característica en versión preliminar en C# 15 y .NET 11. Usan dos configuraciones del compilador independientes:

• La preview versión del lenguaje habilita la nueva sintaxis y la relajación del puntero.
• La updated-memory-safety-rules característica del compilador habilita las reglas actualizadas, incluidas las obligaciones de llamador no seguras , y hace que el compilador registre la elección en el ensamblado con el MemorySafetyRulesAttribute atributo .

Una propiedad futura del SDK estable, MemorySafetyRules, se planea como un tercer nivel de activación para cuando la característica sale de la versión preliminar (por ejemplo, <MemorySafetyRules>2</MemorySafetyRules>), pero esa propiedad aún no está implementada.

Para un proyecto, use ambas opciones:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>

Para un programa basado en archivos, agregue las directivas equivalentes:

#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview

La propiedad AllowUnsafeBlocks es independiente. Controla si el origen puede usar la unsafe palabra clave . Un proyecto puede habilitar las reglas actualizadas sin permitir código no seguro, en cuyo caso recibe errores cuando llama a las API no seguras.

Si un ensamblado aplica las reglas actualizadas en otra depende de qué lado opte por:

• Autor de llamada del modelo actualizado, destinatario del modelo actualizado: los marcadores del autor de la llamada viajan a través de unsafe metadatos. El autor de la llamada ajusta cada llamada a un miembro no seguro necesario en un unsafe bloque.
• Llamador de modelo actualizado, destinatario del modelo original: un modo de compatibilidad trata a cualquier miembro de llamada con un tipo de puntero en su firma como requiere-unsafe, por lo que el sitio de llamada necesita un bloque envolvente unsafe . Este modo impide que una API basada en puntero pierda silenciosamente su unsafe requisito.
• Autor de llamada del modelo original, destinatario del modelo actualizado: se siguen aplicando las reglas de puntero originales. Un miembro no seguro requiere que no tenga ningún tipo de puntero en su firma se pueda llamar desde código seguro, ya que el autor de la llamada del modelo original no puede leer los nuevos marcadores.

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>

Algunas características en versión preliminar requieren una participación independiente además de <LangVersion>preview</LangVersion>. Por ejemplo, las reglas de seguridad de memoria actualizadas de C# 15 usan la updated-memory-safety-rules característica del compilador. Para obtener más información, consulte Habilitación de las reglas de seguridad de memoria actualizadas.

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. Actualice 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.

• La opción del compilador LangVersion no afecta a los metadatos a los que hace referencia la aplicación de C#.

• 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 sus propios requisitos mínimos de .NET API o Common Language Runtime que podrían permitirle ejecutarse en marcos de nivel inferior 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

Use la opción Que acepta valores NULL para especificar el contexto que acepta valores NULL. Establézcalo en la configuración del proyecto mediante la <Nullable> etiqueta :

<Nullable>enable</Nullable>

El argumento debe ser uno de enable, disable, warnings o annotations. El enable argumento activa el contexto que acepta valores NULL. El disable argumento desactiva el contexto que acepta valores NULL. El warnings argumento activa el contexto de advertencia que acepta valores NULL. El annotations argumento activa el contexto de anotación que acepta valores NULL. Para obtener más información sobre estos valores, vea Contextos que aceptan valores NULL. Para más información sobre cómo habilitar tipos de referencia que aceptan valores NULL en un código base existente, consulte Estrategias de migración que aceptan valores NULL.

El análisis de flujo deduce la nulabilidad de las variables dentro del código ejecutable. La nulabilidad inferida de una variable es independiente de la nulabilidad declarada de dicha variable. El compilador analiza las llamadas al método incluso cuando la llamada se omite condicionalmente de la salida compilada. Por ejemplo, el compilador sigue analizando una llamada a Debug.Assert para comprobar si la llamada es condicional y no se compila en compilaciones de versión.

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

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