Opções do compilador C# para regras de recurso de idioma

As opções a seguir controlam como o compilador interpreta os recursos de linguagem. A nova sintaxe MSBuild é mostrada em Negrito. A sintaxe csc.exe mais antiga é mostrada em code style.

  • CheckForOverflowUnderflow / -checked: gerar verificações de estouro.
  • AllowUnsafeBlocks / -unsafe: permitir código 'inseguro'.
  • DefineConstants / -define: definir símbolos de compilação condicional.
  • LangVersion / -langversion: especificar a versão de idioma como default (versão principal mais recente) ou latest (versão mais recente, incluindo versões secundárias).
  • Anulável / -nullable: habilitar o contexto anulável ou avisos anuláveis.

CheckForOverflowUnderflow

A opção CheckForOverflowUnderflow especifica se uma instrução de aritmética de inteiros que resulta em um valor fora do intervalo do tipo de dados causa uma exceção do tempo de execução.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Uma instrução aritmética de inteiros que está no escopo de uma palavra-chave checked ou unchecked não está sujeita ao efeito da opção CheckForOverflowUnderflow. Se uma instrução de aritmética de inteiros que não está no escopo de uma palavra-chave checked ou unchecked resultar em um valor fora do intervalo do tipo de dados, e CheckForOverflowUnderflow for true,essa instrução causa uma exceção no tempo de execução. Se CheckForOverflowUnderflow for false, essa instrução não causará uma exceção no tempo de execução. O valor padrão para essa opção é false; a verificação de estouro é desabilitada.

AllowUnsafeBlocks

A opção do compilador AllowUnsafeBlocks permite que o código que usa a palavra-chave unsafe seja compilado. O valor padrão para essa opção é false, o que significa que código não seguro não é permitido.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Para obter mais informações sobre código não seguro, consulte Código não seguro e ponteiros.

DefineConstants

A opção DefineConstants define símbolos em todos os arquivos de código-fonte do seu programa.

<DefineConstants>name;name2</DefineConstants>

Essa opção especifica os nomes de um ou mais símbolos que você deseja definir. A opção DefineConstants tem o mesmo efeito que usar uma diretiva de pré-processador #define, exceto que a opção do compilador está em vigor para todos os arquivos no projeto. Um símbolo permanece definido em um arquivo de origem até que uma diretiva #undef remova a definição no arquivo de origem. Quando você usa a opção -define, uma diretiva #undef em um arquivo não terá nenhum efeito em outros arquivos de código-fonte no projeto. Você pode usar os símbolos criados por essa opção com #if, #else, #elif e #endif para compilar os arquivos de origem condicionalmente. O compilador do C# não define símbolos ou macros que podem ser usados em seu código-fonte. Todas as definições de símbolo devem ser definidas pelo usuário.

Observação

A diretiva #define do C# não permite que um valor seja dado a um símbolo, como nas linguagens como a C++. Por exemplo, #define não pode ser usado para criar uma macro ou para definir uma constante. Se você precisar definir uma constante, use uma variável enum. Se você quiser criar uma macro de estilo C++, considere alternativas como os genéricos. Como as macros são notoriamente propensas a erros, o C# não permite o uso delas, mas oferece alternativas mais seguras.

LangVersion

Faz com que o compilador aceite somente a sintaxe incluída na especificação de linguagem C# escolhida.

<LangVersion>9.0</LangVersion>

Os seguintes valores são válidos:

Valor Significado
preview O compilador aceita todas as sintaxes de linguagem válidas da versão prévia mais recente.
latest O compilador aceita a sintaxe da versão lançada mais recente do compilador (incluindo a versão secundária).
latestMajor (default) O compilador aceita a sintaxe da versão principal mais recente lançada do compilador.
10.0 O compilador aceita somente a sintaxe incluída no C# 10 ou inferior.
9.0 O compilador aceita somente a sintaxe incluída no C# 9 ou inferior.
8.0 O compilador aceita somente a sintaxe incluída no C# 8.0 ou inferior.
7.3 O compilador aceita somente a sintaxe incluída no C# 7.3 ou inferior.
7.2 O compilador aceita somente a sintaxe incluída no C# 7.2 ou inferior.
7.1 O compilador aceita somente a sintaxe incluída no C# 7.1 ou inferior.
7 O compilador aceita somente a sintaxe incluída no C# 7.0 ou inferior.
6 O compilador aceita somente a sintaxe incluída no C# 6.0 ou inferior.
5 O compilador aceita somente a sintaxe incluída no C# 5.0 ou inferior.
4 O compilador aceita somente a sintaxe incluída no C# 4.0 ou inferior.
3 O compilador aceita somente a sintaxe incluída no C# 3.0 ou inferior.
ISO-2(ou 2) O compilador aceita somente a sintaxe incluída no ISO/IEC 23270:2006 C# (2.0).
ISO-1(ou 1) O compilador aceita somente a sintaxe incluída no ISO/IEC 23270:2003 C# (1.0/1.2).

A versão da linguagem padrão depende da estrutura de destino do aplicativo e da versão do SDK ou do Visual Studio instalado. Essas regras são definidas em Controle de versão da linguagem C#.

Os metadados referenciados pelo seu aplicativo de C# não estão sujeitos à opção do compilador Langversion.

Como cada versão do compilador do C# contém extensões para a especificação de linguagem, Langversion não dá a funcionalidade equivalente de uma versão anterior do compilador.

Além disso, embora as atualizações de versão do C# geralmente coincidam com as versões principais do .NET, a nova sintaxe e as funcionalidades não estão necessariamente vinculadas a essa versão de estrutura específica. Embora as novas funcionalidades definitivamente exijam uma nova atualização do compilador que também é liberada junto com a revisão do C#, cada funcionalidade específica tem seus próprios requisitos mínimos de API ou do Common Language Runtime do .NET que podem permitir que ela seja executada em estruturas de nível inferior com a inclusão de pacotes NuGet ou de outras bibliotecas.

Independentemente de qual configuração Langversion for usada, use a versão atual do Common Language Runtime para criar seu .exe ou .dll. Uma exceção são os assemblies amigáveis e ModuleAssemblyName, que funcionarão em-langversion:ISO-1.

Para descobrir outras maneiras de especificar a versão da linguagem C#, confira Controle de versão da linguagem C#.

Para saber mais sobre como definir essa opção do compilador programaticamente, veja LanguageVersion.

Especificação da linguagem C#

Versão Link Descrição
C# 7.0 e posterior Não disponível no momento
C# 6.0 Link Especificação da Linguagem C# Versão 6 – Rascunho não oficial: .NET Foundation
C# 5.0 Baixar PDF Padrão ECMA-334 – 5ª Edição
C# 3.0 Baixar DOC Especificação da Linguagem C# Versão 3.0: Microsoft Corporation
C# 2.0 Baixar PDF Padrão ECMA-334 – 4ª Edição
C# 1.2 Baixar DOC Especificação da Linguagem C# Versão 1.2: Microsoft Corporation
C# 1.0 Baixar DOC Especificação da Linguagem C# Versão 1.0: Microsoft Corporation

Versão mínima do SDK necessária para dar suporte a todos os recursos de idioma

A tabela a seguir lista as versões mínimas do SDK com o compilador C# que dá suporte à versão de idioma correspondente:

Versão do C# Versão mínima do SDK
C# 10 Microsoft Visual Studio/Build Tools 2022 ou SDK do .NET 6
C# 9.0 Microsoft Visual Studio/Build Tools 2019, versão 16.8 ou SDK do .NET 5
C# 8.0 Microsoft Visual Studio/Build Tools 2019, versão 16.3 ou SDK do .NET Core
C# 7.3 Microsoft Visual Studio/Ferramentas de Build 2017, versão 15.7
C# 7.2 Microsoft Visual Studio/Ferramentas de Build 2017, versão 15.5
C# 7.1 Microsoft Visual Studio/Ferramentas de Build 2017, versão 15.3
C# 7.0 Microsoft Visual Studio/Ferramentas de Build 2017
C# 6 Microsoft Visual Studio/Ferramentas de Build 2015
C# 5 Microsoft Visual Studio/Ferramentas de Build 2012 ou compilador do .NET Framework 4.5 em pacote
C# 4 Microsoft Visual Studio/Ferramentas de Build 2010 ou compilador do .NET Framework 4.0 em pacote
C# 3 Microsoft Visual Studio/Ferramentas de Build 2008 ou compilador do .NET Framework 3.5 em pacote
C# 2 Microsoft Visual Studio/Ferramentas de Build 2005 ou compilador do .NET Framework 2.0 em pacote
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 ou compilador em pacote .NET Framework 1.0

Nullable

A opção Nullable permite que você especifique o contexto anulável. Ele pode ser definido na configuração do projeto usando a marca <Nullable>:

<Nullable>enable</Nullable>

O argumento deve enable, disable, warnings ou annotations. O argumento enable habilita o contexto anulável. A especificação disable desabilitará o contexto anulável. Ao fornecer o argumento warnings, o contexto de aviso anulável é habilitado. Ao especificar o argumento annotations, o contexto de anotação anulável é habilitado.

Observação

Quando não há nenhum valor definido, o valor disable padrão é aplicado, no entanto, os modelos .NET 6 são, por padrão, fornecidos com o valor Nullable definido como enable.

A análise de fluxo é usada para inferir a nulidade de variáveis no código executável. A nulidade inferida de uma variável é independente da nulidade declarada da variável. As chamadas de método são analisadas mesmo quando são condicionalmente omitidas. Por exemplo, Debug.Assert no modo de versão.

A invocação de métodos anotados com os seguintes atributos também afetará a análise de fluxo:

Importante

O contexto global anulável não se aplica aos arquivos de código gerados. Independentemente dessa configuração, o contexto anulável é desabilitado para qualquer arquivo de origem marcado como gerado. Há quatro maneiras de um arquivo ser marcado como gerado:

  1. No .editorconfig, especifique generated_code = true em uma seção que se aplica a esse arquivo.
  2. Coloque <auto-generated> ou <auto-generated/> em um comentário na parte superior do arquivo. Ele pode estar em qualquer linha nesse comentário, mas o bloco de comentários deve ser o primeiro elemento no arquivo.
  3. Inicie o nome do arquivo com TemporaryGeneratedFile_
  4. Termine o nome do arquivo com .designer.cs, .generated.cs, .g.cs ou .g.i.cs.

Os geradores podem aceitar usando a diretiva de pré-processador #nullable.