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

  • Artigo

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.

Nota

A diretiva C# #define não permite que um símbolo receba um valor, como em linguagens como 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 enum variável. Se você quiser criar uma macro no estilo C++, considere alternativas como genéricos. Como as macros são notoriamente propensas a erros, o C# não permite seu uso, mas fornece alternativas mais seguras.

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:

Value Significado
preview O compilador aceita toda a sintaxe de idioma válida da versão de visualização mais recente.
latest O compilador aceita sintaxe da última versão lançada do compilador (incluindo a versão secundária).
latestMajor
ou default		 O compilador aceita a sintaxe da última versão principal do compilador.
12.0 O compilador aceita apenas a sintaxe incluída no C# 12 ou inferior.
11.0 O compilador aceita apenas a sintaxe incluída no C# 11 ou inferior.
10.0 O compilador aceita apenas a sintaxe incluída no C# 10 ou inferior.
9.0 O compilador aceita apenas a sintaxe incluída no C# 9 ou inferior.
8.0 O compilador aceita apenas a sintaxe incluída no C# 8.0 ou inferior.
7.3 O compilador aceita apenas a sintaxe incluída no C# 7.3 ou inferior.
7.2 O compilador aceita apenas a sintaxe incluída no C# 7.2 ou inferior.
7.1 O compilador aceita apenas a sintaxe incluída no C# 7.1 ou inferior.
7 O compilador aceita apenas a sintaxe incluída no C# 7.0 ou inferior.
6 O compilador aceita apenas a sintaxe incluída no C# 6.0 ou inferior.
5 O compilador aceita apenas a sintaxe incluída no C# 5.0 ou inferior.
4 O compilador aceita apenas a sintaxe incluída no C# 4.0 ou inferior.
3 O compilador aceita apenas a sintaxe incluída no C# 3.0 ou inferior.
ISO-2
ou 2		 O compilador aceita apenas a sintaxe incluída na ISO/IEC 23270:2006 C# (2.0).
ISO-1
ou 1		 O compilador aceita apenas a sintaxe incluída na ISO/IEC 23270:2003 C# (1.0/1.2).

Importante

O latest valor geralmente não é recomendado. Com latesto , 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 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 Ligação Description
C# 8.0 e posterior descarregar PDF Especificação da linguagem C# Versão 7: .NET Foundation
C# 7,3 descarregar PDF Norma ECMA-334 7ª Edição
C# 6,0 descarregar PDF Norma ECMA-334 6ª Edição
C# 5,0 Descarregar PDF Norma ECMA-334 5ª Edição
C# 3,0 Baixar DOC Especificação da linguagem C# Versão 3.0: Microsoft Corporation
C# 2,0 Descarregar PDF Norma ECMA-334 4ª Edição
C# 1,2 Baixar DOC Norma ECMA-334 2ª Edição
C# 1,0 Baixar DOC Norma ECMA-334 1ª Edição

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:

Versão em 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 3.0
C# 7,3 Microsoft Visual Studio/Build Tools 2017, versão 15.7
C# 7,2 Microsoft Visual Studio/Build Tools 2017, versão 15.5
C# 7,1 Microsoft Visual Studio/Build Tools 2017, versão 15.3
C# 7,0 Microsoft Visual Studio/Ferramentas de compilação 2017
C# 6 Microsoft Visual Studio/Ferramentas de compilação 2015
C# 5 Microsoft Visual Studio/Build Tools 2012 ou compilador .NET Framework 4.5 incluído
C# 4 Microsoft Visual Studio/Build Tools 2010 ou compilador .NET Framework 4.0 incluído
C# 3 Microsoft Visual Studio/Build Tools 2008 ou compilador do .NET Framework 3.5 incluído
C# 2 Microsoft Visual Studio/Build Tools 2005 ou compilador .NET Framework 2.0 incluído
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 ou compilador .NET Framework 1.0 incluído

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.

Nota

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

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:

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 pelas quais um arquivo é 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 optar por participar usando a diretiva de #nullable pré-processador.