Opções do compilador C# para regras de características da 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

  • CheckForOverflowUnderflow / -checked: Gere verificações de estouro.
  • AllowUnsafeBlocks / -unsafe: Permitir unsafe código.
  • DefineConstants / -define: Defina símbolos 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.

Nota

Para mais informações sobre como configurar estas opções para o seu projeto, consulte Opções do compilador.

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 o CheckForOverflowUnderflow está true, o contexto predefinido é um contexto verificado e a verificação de overflow está ativada. Quando o CheckForOverflowUnderflow é false, o contexto padrão é um contexto não verificado. O valor padrão desta opção é false, o que significa que a verificação de overflow está desativada.

Também pode controlar explicitamente o contexto de verificação de overflow para partes do seu código usando as checked instruções e.unchecked

Para informações sobre como o contexto de verificação de overflow afeta as operações e quais as operações que afeta, consulte o artigo sobre checked as instruções andunchecked.

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.

Ativar as regras atualizadas de segurança de memória

As regras atualizadas de segurança de memória são uma funcionalidade de pré-visualização em C# 15 e .NET 11. Utilizam duas definições independentes do compilador:

  • A preview versão em linguagem permite a nova sintaxe e relaxamentos de ponteiros.
  • A updated-memory-safety-rules funcionalidade do compilador permite as regras atualizadas, incluindo obrigações de chamadas inseguras , e faz com que o compilador grave a escolha na assembly com o MemorySafetyRulesAttribute atributo.

Uma futura propriedade estável do SDK, MemorySafetyRules, está planeada como um terceiro nível de ativação para quando a funcionalidade sair da pré-visualização (por exemplo, <MemorySafetyRules>2</MemorySafetyRules>), mas essa propriedade ainda não está implementada.

Para um projeto, use ambas as definições:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>

Para um programa baseado em ficheiros, adicione as diretivas equivalentes:

#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview

A propriedade AllowUnsafeBlocks é independente. Controla se a fonte pode usar a unsafe palavra-chave. Um projeto pode ativar as regras atualizadas sem permitir código inseguro, caso em que recebe erros ao chamar APIs requires-unsafe.

Se uma assembleia aplica as regras atualizadas contra outra depende de qual lado opta por aderir:

  • Chamada modelo atualizado, chamada modelo atualizado: Os marcadores do unsafe chamado viajam através dos metadados. O chamador envolve cada chamada para um membro inseguro de requisitos num unsafe bloco.
  • Callee modelo atualizado, callee modelo original: Um modo de compatibilidade trata qualquer membro chamado com um tipo de ponteiro na sua assinatura como requires-unsafe, pelo que o local da chamada precisa de um bloco de anexo unsafe . Este modo impede que uma API baseada em ponteiro perca silenciosamente o seu unsafe requisito.
  • Apelador modelo original, chamado modelo atualizado: As regras originais do ponteiro continuam a aplicar-se. Um membro requires-unsafe que não tem tipo de ponteiro na sua assinatura torna-se chamável a partir do código seguro, porque o chamador do modelo original não consegue ler os novos marcadores.

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 tenha um valor, como em linguagens como C++. Por exemplo, #define não se pode criar uma macro ou definir uma constante. Se você precisar definir uma constante, use uma enum variável. Se quiseres criar uma macro ao estilo C++, considera 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#.

Aviso

Não definas o LangVersion elemento para latest. A latest configuração significa que o compilador instalado usa sua versão mais recente. Essa versão pode mudar de máquina para máquina, tornando as compilações pouco fiáveis. Além disso, permite funcionalidades de linguagem que podem exigir funcionalidades de runtime ou de biblioteca que não estão incluídas no SDK atual.

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

<LangVersion>9.0</LangVersion>

Algumas funcionalidades de pré-visualização requerem um opt-in separado além de <LangVersion>preview</LangVersion>. Por exemplo, as regras de segurança de memória atualizadas em C# 15 utilizam a updated-memory-safety-rules funcionalidade do compilador. Para mais informações, consulte Ativar as regras de segurança de memória atualizadas.

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.
15.0 O compilador aceita apenas a sintaxe incluída em C# 15 ou inferior.
14.0 O compilador aceita apenas a sintaxe incluída no C# 14 ou inferior.
13.0 O compilador aceita apenas a sintaxe incluída no C# 13 ou inferior.
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).

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 . Atualize o framework de destino para aceder a funcionalidades mais recentes da linguagem.

  • Especificar LangVersion com o valor é diferente de omitir a default. 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.

  • A opção compilador LangVersion não afeta os metadados referenciados pela sua aplicação C#.

  • 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 funcionalidade específica tem a sua própria API mínima .NET ou requisitos de runtime de linguagem comum que podem permitir que funcione em frameworks down-level ao incluir 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

Use a opção Nullable para especificar o contexto nullable. Defina-o na configuração do projeto usando a <Nullable> etiqueta:

<Nullable>enable</Nullable>

O argumento deve ser um dos enable, disable, warnings, ou annotations. O enable argumento baseia-se no contexto anulável. O disable argumento desliga o contexto anulável. O warnings argumento baseia-se no contexto de aviso anulável. O annotations argumento baseia-se no contexto de anotação anulável. Para mais informações sobre estes valores, veja Contextos anuláveis. Para saber mais sobre como ativar tipos de referência anuláveis numa base de código existente, consulte estratégias de migração anulável.

Nota

Se não definir um valor, o valor padrão é disable. No entanto, os templates .NET 6 e mais recentes definem o valor Nullable por enable defeito.

A análise de fluxo infere a anulabilidade das variáveis dentro do código executável. A anulabilidade inferida de uma variável é independente da anulabilidade declarada da variável. O compilador analisa chamadas de método mesmo quando a chamada é condicionalmente omitida da saída compilada. Por exemplo, o compilador continua a analisar uma chamada para Debug.Assert nulidade, mesmo que a chamada seja condicional e não esteja compilada em versões de release.

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

Importante

O contexto global anulável não se aplica a ficheiros de código gerados. Independentemente dessa configuração, o contexto anulável é desabilitado para qualquer arquivo de origem marcado como gerado. Um ficheiro é marcado como gerado de uma das seguintes formas:

  1. No .editorconfig, especifique generated_code = true em uma seção que se aplica a esse arquivo.
  2. Inclui <auto-generated> ou <auto-generated/> num comentário no topo do ficheiro. Podes colocá-lo em qualquer linha do comentário, mas o bloco de comentários deve ser o primeiro elemento do ficheiro.
  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 aderir usando a #nullable diretiva do pré-processador.

  • Last updated on