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 comodefault(versión principal más reciente) olatest(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.
Nota:
Consulte Opciones del compilador para obtener más información sobre cómo configurar estas opciones para el proyecto.
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.
Nota:
El valor de la directiva #define de C# no permite que se le proporcione un valor a un símbolo, como sucede en lenguajes como C++. Por ejemplo, #define no puede usarse para crear una macro o para definir una constante. Si necesita definir una constante, use una variable enum. Si quiere crear una macro de estilo de C++, considere alternativas como genéricos. Como las macros son notoriamente propensas a errores, C# deshabilita su uso pero proporciona alternativas más seguras.
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#.
Advertencia
No se recomienda establecer el elemento LangVersion como latest. La configuración latest significa que el compilador instalado usa su versión más reciente. Esto puede cambiar de equipo a equipo, lo que hace que las compilaciones no sean confiables. Además, habilita las características de lenguaje que pueden requerir tiempo de ejecución o características de biblioteca que no se incluyen en el SDK actual.
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:
| Valor | Significado |
|---|---|
preview |
El compilador acepta toda la sintaxis de lenguaje válida de la última versión preliminar. |
latest |
El compilador acepta la sintaxis de la última versión del compilador (incluida las versión secundaria). |
latestMajoro bien default |
El compilador acepta la sintaxis de la versión principal más reciente del compilador. |
13.0 |
El compilador solo acepta la sintaxis que se incluye en C# 13 o versiones anteriores. |
12.0 |
El compilador solo acepta la sintaxis que se incluye en C# 12 o versiones anteriores. |
11.0 |
El compilador solo acepta la sintaxis que se incluye en C# 11 o versiones anteriores. |
10.0 |
El compilador solo acepta la sintaxis que se incluye en C# 10 o versiones anteriores. |
9.0 |
El compilador solo acepta la sintaxis que se incluye en C# 9 o versiones anteriores. |
8.0 |
El compilador acepta solo la sintaxis que se incluye en C# 8.0 o versiones anteriores. |
7.3 |
El compilador acepta solo la sintaxis que se incluye en C# 7.3 o versiones anteriores. |
7.2 |
El compilador acepta solo la sintaxis que se incluye en C# 7.2 o versiones anteriores. |
7.1 |
El compilador acepta solo la sintaxis que se incluye en C# 7.1 o versiones anteriores. |
7 |
El compilador acepta solo la sintaxis que se incluye en C# 7.0 o versiones anteriores. |
6 |
El compilador acepta solo la sintaxis que se incluye en C# 6.0 o versiones anteriores. |
5 |
El compilador acepta solo la sintaxis que se incluye en C# 5.0 o versiones anteriores. |
4 |
El compilador acepta solo la sintaxis que se incluye en C# 4.0 o versiones anteriores. |
3 |
El compilador acepta solo la sintaxis que se incluye en C# 3.0 o versiones anteriores. |
ISO-2o bien 2 |
El compilador acepta solo la sintaxis que se incluye en ISO/IEC 23270:2006 C# (2.0). |
ISO-1o bien 1 |
El compilador acepta solo la sintaxis que se incluye en ISO/IEC 23270:2003 C# (1.0/1.2). |
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
defaultes diferente de omitir la opción LangVersion. Al especificardefaultse 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 endefault.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 | Link | Descripción |
|---|---|---|
| C# 8.0 y posterior | Descargar PDF | Especificación del lenguaje C# versión 7: .NET Foundation |
| C# 7.3 | Descargar PDF | Estándar ECMA-334, séptima edición |
| C# 6.0 | Descargar PDF | Norma ECMA-334 estándar, sexta edición |
| C# 5.0 | Descargar PDF | Norma ECMA-334 estándar, quinta edición |
| C# 3.0 | Decargar DOC | Especificación del lenguaje C#, versión 3.0: Microsoft Corporation |
| C# 2.0 | Descargar PDF | Norma ECMA-334 estándar, cuarta edición |
| C# 1.2 | Decargar DOC | Norma ECMA-334 estándar, segunda edición |
| C# 1.0 | Decargar DOC | Norma ECMA-334 estándar, primera edición |
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:
| Versión de C# | Versión mínima del SDK |
|---|---|
| C# 12 | Microsoft Visual Studio/Build Tools 2022, versión 17.8 o SDK de .NET 8 |
| C# 11 | Microsoft Visual Studio/Build Tools 2022, versión 17.4, o bien el SDK de .NET 7 |
| C# 10 | Microsoft Visual Studio/Build Tools 2022, o bien el SDK de .NET 6 |
| C# 9.0 | Microsoft Visual Studio/Build Tools 2019, versión 16.8, o bien SDK de .NET 5 |
| C# 8.0 | Microsoft Visual Studio/Build Tools 2019, versión 16.3 o SDK de .NET Core 3.0 |
| C# 7.3 | Microsoft Visual Studio/Build Tools 2017, versión 15.7 |
| C# 7.2 | Microsoft Visual Studio/Build Tools 2017, versión 15.5 |
| C# 7.1 | Microsoft Visual Studio/Build Tools 2017, versión 15.3 |
| C# 7.0 | Microsoft Visual Studio/Build Tools 2017 |
| C# 6 | Microsoft Visual Studio/Build Tools 2015 |
| C# 5 | Microsoft Visual Studio/Build Tools 2012 o compilador empaquetado de .NET Framework 4.5 |
| C# 4 | Microsoft Visual Studio/Build Tools 2010 o compilador empaquetado de .NET Framework 4.0 |
| C# 3 | Microsoft Visual Studio/Build Tools 2008 o compilador empaquetado de .NET Framework 3.5 |
| C# 2 | Microsoft Visual Studio/Build Tools 2005 o compilador empaquetado de .NET Framework 2.0 |
| C# 1.0/1.2 | Microsoft Visual Studio/Build Tools .NET 2002 o compilador empaquetado de .NET Framework 1.0 |
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.
Nota
Cuando no hay ningún conjunto de valores, se aplica el valor predeterminado disable, pero las plantillas de .NET 6 se proporcionan de forma predeterminada con el valor Acepta valores NULL establecido en enable.
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[])
Importante
El contexto global que admite un valor NULL no se aplica a los archivos de código generado. Con independencia de este valor, el contexto que admite un valor NULL está deshabilitado para cualquier archivo de código fuente marcado como generado. Hay cuatro maneras de marcar un archivo como generado:
- En el archivo .editorconfig, especifique
generated_code = trueen una sección que se aplique a ese archivo. - Coloque
<auto-generated>o<auto-generated/>en un comentario en la parte superior del archivo. Puede estar en cualquier línea de ese comentario, pero el bloque de comentario debe ser el primer elemento del archivo. - Inicie el nombre de archivo con TemporaryGeneratedFile_
- Finalice el nombre de archivo con .designer.cs, .generated.cs, .g.cs o .g.i.cs.
Los generadores pueden optar por usar la directiva de preprocesador #nullable.
