Opções do compilador C# para regras de recursos de linguagem

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

• CheckForOverflowUnderflow / -checked: Gere verificações de estouro.
• AllowUnsafeBlocks / -unsafe: Permitir código 'inseguro'.
• DefineConstants / -define: Defina o(s) símbolo(s) de compilação condicional.
• LangVersion / -langversion: Especifique a versão do idioma, como default (última versão principal) ou latest (versão mais recente, incluindo versões secundárias).
• Nulo / -nullable: habilite o contexto nulo ou avisos anuláveis.

CheckForOverflowUnderflow

A opção CheckForOverflowUnderflow controla o contexto padrão de verificação de estouro que define o comportamento do programa se estouros aritméticos inteiros.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

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

Você também pode controlar explicitamente o contexto de verificação de estouro para as partes do seu código usando as checked instruções and 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, consulte o artigo sobre checked e unchecked instruções.

AllowUnsafeBlocks

A opção de 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 o 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 e ponteiros não seguros.

DefineConstants

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

<DefineConstants>name;name2</DefineConstants>

Esta opção especifica os nomes de um ou mais símbolos que você deseja definir. A opção DefineConstants tem o mesmo efeito que a 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 no arquivo de origem remova a definição. Quando você usa a -define opção, uma #undef diretiva em um arquivo não tem efeito sobre outros arquivos de código-fonte no projeto. Você pode usar símbolos criados por essa opção com #if, #else, #elif e #endif para compilar arquivos de origem condicionalmente. O compilador C# em si não define símbolos ou macros que você pode usar em seu código-fonte; Todas as definições de símbolos devem ser definidas pelo usuário.

LangVersion

A versão de idioma padrão para o compilador C# depende da estrutura de destino para seu aplicativo e da versão do SDK ou Visual Studio instalado. Essas regras são definidas no versionamento da linguagem C#.

A opção LangVersion faz com que o compilador aceite apenas a sintaxe incluída na especificação da 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 idioma mais recentes.

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

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

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

• Embora as atualizações de versão em C# geralmente coincidam com as principais versões do .NET, a nova sintaxe e os novos recursos não estão necessariamente vinculados a essa versão específica da estrutura. Cada recurso específico tem sua própria API .NET mínima ou requisitos de Common Language Runtime que podem permitir que ele seja executado em estruturas de nível inferior incluindo pacotes NuGet ou outras bibliotecas.

• Independentemente de qual configuração LangVersion você usa, use a versão atual do common language runtime para criar seu .exe ou .dll. Uma exceção são os assemblies amigos e ModuleAssemblyName, que funcionam em -langversion:ISO-1.

Para obter outras maneiras de especificar a versão da linguagem C#, consulte Versão da linguagem C#.

Para obter informações sobre como definir essa opção do compilador programaticamente, consulte LanguageVersion.

Especificação da linguagem C#

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

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

Pode ser nulo

A opção Nullable permite especificar o contexto anulável. Ele pode ser definido na configuração do projeto usando a <Nullable> tag :

<Nullable>enable</Nullable>

O argumento deve ser um dos enable, disable, warnings, ou annotations. O enable argumento habilita o contexto anulável. A especificação disable desativará o contexto anulável. Quando você especifica o warnings argumento, o contexto de aviso anulável é habilitado. Quando você especifica o annotations argumento, o contexto de anotação anulável é habilitado. Os valores são descritos e explicados no artigo sobre contextos anuláveis. Você pode saber mais sobre as tarefas envolvidas na habilitação de tipos de referência anuláveis em uma base de código existente em nosso artigo sobre estratégias de migração anuláveis.

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

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
• Membro pós-condições: MemberNotNullAttribute(String) e MemberNotNullAttribute(String[])