Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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: Permitirunsafecódigo. -
DefineConstants /
-define: definir símbolos de compilação condicional. -
LangVersion /
-langversion: especificar a versão de idioma comodefault(versão principal mais recente) oulatest(versão mais recente, incluindo versões secundárias). -
Anulável /
-nullable: habilitar o contexto anulável ou avisos anuláveis.
Observação
Para obter mais informações sobre como configurar essas opções para seu projeto, consulte as opções do Compilador.
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 está habilitada. Quando CheckForOverflowUnderflow é false, o contexto padrão é um contexto desmarcado. O valor padrão dessa opção é false, o que significa que a verificação de estouro está desabilitada.
Você também pode controlar explicitamente o contexto de verificação de estouro para partes do código usando as instruções e unchecked as checked instruções.
Para obter informações sobre como o contexto de verificação de estouro afeta as operações e quais operações ele afeta, consulte o artigo sobre checked e unchecked instruções.
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.
Habilitar as regras de segurança de memória atualizadas
As regras de segurança de memória atualizadas são um recurso de visualização no C# 15 e .NET 11. Eles usam duas configurações de compilador independente:
- A
previewversão do idioma habilita as novas sintaxes e relaxamentos de ponteiro. - O
updated-memory-safety-rulesrecurso do compilador habilita as regras atualizadas, incluindo obrigações de chamador não seguras , e faz com que o compilador registre a opção no assembly com o MemorySafetyRulesAttribute atributo.
Uma futura propriedade MemorySafetyRulesestável do SDK é planejada como uma terceira camada de ativação para quando o recurso sair da versão prévia (por exemplo), <MemorySafetyRules>2</MemorySafetyRules>mas essa propriedade ainda não foi implementada.
Para um projeto, use as duas configurações:
<PropertyGroup>
<LangVersion>preview</LangVersion>
<Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>
Para um programa baseado em arquivo, adicione as diretivas equivalentes:
#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview
A propriedade AllowUnsafeBlocks é independente. Ele controla se a origem pode usar a unsafe palavra-chave. Um projeto pode habilitar as regras atualizadas sem permitir código não seguro. Nesse caso, ele recebe erros quando chama APIs não seguras.
Se um assembly impõe as regras atualizadas contra outra depende de qual lado aceita:
-
Chamador de modelo atualizado, receptor de chamada de modelo atualizado: os marcadores do
unsafereceptor viajam por meio de metadados. O chamador encapsula cada chamada para um membro não seguro em umunsafebloco. -
Chamador de modelo atualizado, receptor de chamada de modelo original: um modo de compatibilidade trata qualquer membro do receptor com um tipo de ponteiro em sua assinatura como não seguro, portanto, o site de chamada precisa de um bloco delimitador
unsafe. Esse modo impede que uma API baseada em ponteiro perca silenciosamente seuunsaferequisito. - Chamador de modelo original, receptor de chamada de modelo atualizado: as regras de ponteiro originais ainda se aplicam. Um membro não seguro que não tem nenhum tipo de ponteiro em sua assinatura torna-se callable do código seguro, porque o chamador do modelo original não pode 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>
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 C# #define não permite que um símbolo tenha um valor, como em linguagens como C++. Por exemplo, #define não é possível criar uma macro nem definir uma constante. Se você precisar definir uma constante, use uma variável enum. 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 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#.
Aviso
Não defina o LangVersion elemento como latest. A configuração latest significa que o compilador instalado usa sua versão mais recente. Essa versão pode mudar de computador para computador, tornando os builds não confiáveis. Além disso, ele habilita recursos de linguagem que podem exigir recursos de runtime ou biblioteca que não estão incluídos no SDK atual.
A opção LangVersion faz com que o compilador aceite apenas a sintaxe incluída na especificação da linguagem C#, por exemplo:
<LangVersion>9.0</LangVersion>
Alguns recursos de visualização exigem uma aceitação separada além de <LangVersion>preview</LangVersion>. Por exemplo, as regras de segurança de memória atualizadas do C# 15 usam o recurso do updated-memory-safety-rules compilador. Para obter mais informações, consulte Habilitar as regras de segurança de memória atualizadas.
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). |
latestMajorou default |
O compilador aceita a sintaxe da versão principal mais recente lançada do compilador. |
15.0 |
O compilador aceita apenas a sintaxe incluída no C# 15 ou inferior. |
14.0 |
O compilador aceita apenas a sintaxe incluída no C# 14 ou inferior. |
13.0 |
O compilador aceita somente a sintaxe incluída no C# 13 ou inferior. |
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-2ou 2 |
O compilador aceita somente a sintaxe incluída no ISO/IEC 23270:2006 C# (2.0). |
ISO-1ou 1 |
O compilador aceita somente a sintaxe incluída no 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 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 dedefaultusa 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 comodefault.A opção do compilador LangVersion não afeta os metadados referenciados pelo aplicativo C#.
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 recurso específico tem seus próprios requisitos mínimos de API .NET ou 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 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
Use a opção Nullable para especificar o contexto anulável. Defina-o na configuração do projeto usando a <Nullable> marca:
<Nullable>enable</Nullable>
O argumento deve enable, disable, warnings ou annotations. O enable argumento ativa o contexto anulável. O disable argumento desativa o contexto anulável. O warnings argumento ativa o contexto de aviso anulável. O annotations argumento ativa o contexto de anotação anulável. Para obter mais informações sobre esses valores, consulte contextos anuláveis. Para saber mais sobre como habilitar tipos de referência anuláveis em uma base de código existente, consulte estratégias de migração anuláveis.
Observação
Se você não definir um valor, o valor padrão será disable. No entanto, .NET modelos 6 e mais recentes definem o valor enableanulável como por padrão.
A análise de fluxo infere a nulidade de variáveis dentro do código executável. A nulidade inferida de uma variável é independente da nulidade declarada da variável. O compilador analisa chamadas de método mesmo quando a chamada é omitida condicionalmente da saída compilada. Por exemplo, o compilador ainda analisa uma chamada para Debug.Assert nulidade, mesmo que a chamada seja condicional e não seja compilada em builds de versão.
A invocação de métodos anotados com os seguintes atributos também afeta 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[])
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. Um arquivo é marcado como gerado de uma das seguintes maneiras:
- No .editorconfig, especifique
generated_code = trueem uma seção que se aplica a esse arquivo. - Inclua
<auto-generated>ou<auto-generated/>em um comentário na parte superior do arquivo. Você pode colocá-lo em qualquer linha no comentário, mas o bloco de comentários deve ser o primeiro elemento no arquivo. - Inicie o nome do arquivo com TemporaryGeneratedFile_
- Termine o nome do arquivo com .designer.cs, .generated.cs, .g.cs ou .g.i.cs.
Os geradores podem aceitar usando a #nullable diretiva de pré-processador.
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
