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.

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:

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 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:

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.

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:

• Pré-condições simples: AllowNullAttribute e DisallowNullAttribute
• Pós-condições simples: MaybeNullAttribute e NotNullAttribute
• Pós-condições condicionais: MaybeNullWhenAttribute e NotNullWhenAttribute
• DoesNotReturnIfAttribute (por exemplo, DoesNotReturnIf(false) para Debug.Assert) e DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Pós-condições de membro: MemberNotNullAttribute(String) e MemberNotNullAttribute(String[])