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 controla o contexto da verificação de estouro padrão que define o comportamento do programa no caso de estouros aritméticos inteiros.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Quando CheckForOverflowUnderflow é true, o contexto padrão é um contexto verificado e a verificação de estouro é habilitada; caso contrário, o contexto padrão é um contexto desmarcado. O valor padrão para essa opção é false, ou seja, verificação de estouro é desabilitada.

Você também pode controlar explicitamente o contexto de verificação de estouro para as partes do código usando as instruções checked e unchecked.

Para obter informações sobre como o contexto de verificação de estouro afeta as operações e quais operações são afetadas, confira o artigo sobre checked e instruções unchecked.

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

A versão da linguagem padrão para o compilador C# 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#.

A opção LangVersion faz com que o compilador aceite somente a sintaxe incluída na especificação de linguagem C# especificada, por exemplo:

<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
ou default
O compilador aceita a sintaxe da versão principal mais recente lançada do compilador.
12.0 O compilador aceita somente a sintaxe incluída no C# 12 ou versão inferior.
11.0 O compilador aceita somente a sintaxe incluída no C# 11 ou inferior.
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).

Importante

O valor latest geralmente não é recomendado. Com latest, o compilador habilita os recursos mais recentes, mesmo que esses recursos dependam de atualizações não incluídas na estrutura de destino configurada.

Considerações

  • Para garantir que seu projeto use a versão padrão do compilador recomendada para sua estrutura de destino, não use a opção LangVersion. Você pode atualizar a estrutura de destino para acessar recursos de linguagem mais recentes.

  • Especificar LangVersion com o valor default é diferente de omitir a opção LangVersion. A especificação de default usa a versão mais recente da linguagem com suporte do compilador, sem levar em conta a estrutura de destino. Por exemplo, a criação de um projeto que tenha como destino o .NET 6 na versão 17.6 do Visual Studio 17.6 usará o C# 10 se LangVersion não for especificado, mas usará o C# 11 se LangVersion estiver definido como default.

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

  • 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. Cada funcionalidade específica tem os 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# 8.0 e posterior Baixar PDF Especificação da linguagem C# Versão 7: .NET Foundation
C# 7.3 Baixar PDF ECMA-334 Standard 7ª Edição
C# 6.0 Baixar PDF Padrão ECMA-334 – 6ª Edição
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 ECMA-334 Standard 2ª Edição
C# 1.0 Baixar DOC ECMA-334 Standard 1ª Edição

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# 12 Microsoft Visual Studio/Build Tools 2022 versão 17.8 ou SDK do .NET 8
C# 11 Microsoft Visual Studio/Build Tools 2022, versão 17.4 ou SDK do .NET 7
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. Quando você especifica o argumento warnings, o contexto de aviso anulável é habilitado. Quando você especifica o argumento annotations, o contexto de anotação anulável é habilitado. Os valores são descritos e explicados no artigo sobre Contextos anuláveis. Saiba mais sobre as tarefas envolvidas na habilitação de tipos de referência anuláveis em uma base de código existente no artigo sobre estratégias de migração anuláveis.

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