Selecione a versão .NET a ser usada

Artigo
02/06/2025

Este artigo explica as políticas usadas pelas ferramentas .NET, SDK e tempo de execução para selecionar versões. Essas políticas fornecem um equilíbrio entre a execução de aplicativos usando as versões especificadas e permitindo a facilidade de atualização das máquinas do desenvolvedor e do usuário final. Estas políticas permitem:

Implantação fácil e eficiente do .NET, incluindo atualizações de segurança e confiabilidade.
Use as ferramentas e comandos mais recentes independentemente do tempo de execução do destino.

A seleção da versão ocorre:

Quando você executa um comando SDK, o SDK usa a versão mais recente instalada.
Quando você cria um assembly, monikers da estrutura de destino definem APIs de tempo de compilação.
Quando se executa um aplicativo .NET, aplicativos dependentes da estrutura de destinoavançam.
Quando você publica um aplicativo independente, implantações independentes incluem o tempo de execução selecionado.

O resto do presente documento examina esses quatro cenários.

O SDK usa a versão instalada mais recente

Os comandos do SDK incluem dotnet new e dotnet run. A CLI do .NET deve escolher uma versão do SDK para cada comando dotnet. Ele usa o SDK mais recente instalado na máquina por padrão, mesmo se:

O projeto tem como alvo uma versão anterior do tempo de execução do .NET.
A versão mais recente do SDK do .NET é uma versão de visualização.

Você pode aproveitar os recursos e melhorias mais recentes do SDK ao mesmo tempo que aponta para versões anteriores do runtime do .NET. Você pode direcionar diferentes versões de tempo de execução do .NET usando as mesmas ferramentas SDK.

Em algumas circunstâncias, talvez seja necessário usar uma versão específica do SDK. Você especifica essa versão em um arquivo global.json.

global.json pode ser colocado em qualquer lugar na hierarquia de arquivos. Você controla a quais projetos um determinado global.json se aplica por seu lugar no sistema de arquivos. A CLI do .NET procura um arquivo global.json navegando iterativamente pelo caminho para cima a partir do diretório de trabalho atual (que não é necessariamente o mesmo que o diretório do projeto). O primeiro arquivo global.json encontrado especifica a versão usada. Se essa versão do SDK estiver instalada, essa versão será usada. Se o SDK especificado no global.json não for encontrado, a CLI do .NET usará regras correspondentes para selecionar um SDK compatível ou falhará se nenhum for encontrado.

O exemplo a seguir mostra a sintaxe global.json:

{
  "sdk": {
    "version": "5.0.0"
  }
}

O processo para selecionar uma versão do SDK é:

dotnet procura um arquivo global.json iterativamente invertendo a navegação do caminho para cima a partir do diretório de trabalho atual.
dotnet usa o SDK especificado no primeiro global.json encontrado.
dotnet utiliza o SDK mais recente instalado caso não encontre global.json.

Para obter mais informações sobre a seleção de versão do SDK, consulte as seções Regras de correspondência e Avanço do artigo de visão geral global.json.

Atualizando a versão do SDK

É importante atualizar para a versão mais recente do SDK regularmente para adotar os recursos mais recentes, melhorias de desempenho e correções de bugs. Para verificar facilmente se há atualizações para o SDK, use o comando dotnet sdk check. Além disso, se você selecionar uma versão específica usando global.json, considere uma ferramenta como o Dependabot para atualizar automaticamente a versão fixada do SDK à medida que novas versões forem disponibilizadas.

Os monikers da estrutura de destino definem APIs de tempo de compilação

Você desenvolve o seu projeto com base em APIs definidas em um identificador de estrutura de destino (TFM). No arquivo de projeto, você especifica a estrutura de destino . Defina o elemento TargetFramework em seu arquivo de projeto, conforme mostrado no exemplo a seguir:

<TargetFramework>net8.0</TargetFramework>

Você pode criar seu projeto em relação a vários TFMs. A definição de várias estruturas de destino é mais comum para bibliotecas, mas também pode ser feita com aplicativos. Você especifica uma propriedade TargetFrameworks (plural de TargetFramework). As estruturas de destino são delimitadas por ponto-e-vírgula, conforme mostrado no exemplo a seguir:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Um determinado SDK suporta um conjunto fixo de estruturas, limitado à estrutura de destino do tempo de execução com o qual é fornecido. Por exemplo, o SDK do .NET 8 inclui o runtime do .NET 8, que é uma implementação do framework-alvo net8.0. O SDK do .NET 8 suporta net7.0, net6.0e net5.0, mas não net9.0 (ou superior). Você instala o SDK do .NET 9 para criar para net9.0.

.NET Padrão

O .NET Standard era uma maneira de direcionar uma superfície de API compartilhada por diferentes implementações do .NET. Começando com o lançamento do .NET 5, que é um padrão de API em si, o .NET Standard tem pouca relevância, exceto por um cenário: o .NET Standard é útil quando você deseja direcionar o .NET e o .NET Framework. O .NET 5 implementa todas as versões do .NET Standard.

Para obter mais informações, consulte .NET 5 e .NET Standard.

Avanço de versões de aplicações dependentes da estrutura

Quando executa uma aplicação a partir da origem com dotnet run, a partir de uma implantação dependente de estrutura com dotnet myapp.dll, ou a partir de um executável dependente de estrutura com myapp.exe, o executável dotnet é o host para a aplicação.

O host escolhe a versão de patch mais recente instalada na máquina. Por exemplo, se você especificou net5.0 em seu arquivo de projeto e 5.0.2 é o tempo de execução .NET mais recente instalado, o tempo de execução 5.0.2 é usado.

Se nenhuma versão 5.0.* aceitável for encontrada, uma nova versão 5.* será usada. Por exemplo, se você especificou net5.0 e apenas 5.1.0 está instalado, o aplicativo é executado usando o tempo de execução 5.1.0. Esse comportamento é conhecido como "roll-forward de versão menor". Versões inferiores também não serão consideradas. Quando nenhum tempo de execução aceitável é instalado, o aplicativo não é executado.

Alguns exemplos de uso demonstram o comportamento, se você segmentar 5.0:

✔️ 5.0 é especificado. 5.0.3 é a versão de patch mais alta instalada. Está a utilizar-se a versão 5.0.3.
❌ 5.0 está especificado. Nenhuma versão 5.0.* está instalada. 3.1.1 é o tempo de execução mais alto instalado. É apresentada uma mensagem de erro.
✔️ 5.0 é especificado. Nenhuma versão 5.0.* está instalada. 5.1.0 é a versão de tempo de execução mais alta instalada. 5.1.0 é utilizado.
❌ 3.0 está especificado. Nenhuma versão 3.x está instalada. 5.0.0 é o tempo de execução mais alto instalado. É apresentada uma mensagem de erro.

A versão secundária de avanço progressivo tem um efeito colateral que pode afetar os utilizadores finais. Considere o seguinte cenário:

O aplicativo especifica que 5.0 é necessário.
Quando executada, a versão 5.0.* não está instalada, no entanto, a 5.1.0 está. Será utilizada a versão 5.1.0.
Mais tarde, o usuário instala 5.0.3 e executa o aplicativo novamente, 5.0.3 agora será usado.

É possível que 5.0.3 e 5.1.0 se comportem de forma diferente, particularmente para cenários como a serialização de dados binários.

Controlar o comportamento de avanço

Antes de substituir o comportamento de roll-forward padrão, familiarize-se com o nível de compatibilidade de tempo de execução do .NET .

O comportamento de roll-forward para um aplicativo pode ser configurado de quatro maneiras diferentes:

Configuração no nível do projeto definindo a propriedade <RollForward>:

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

O arquivo *.runtimeconfig.json.

Este ficheiro é produzido quando compila a sua aplicação. Se a propriedade <RollForward> foi definida no projeto, ela é reproduzida no arquivo *.runtimeconfig.json como a configuração rollForward. Os usuários podem editar esse arquivo para alterar o comportamento do seu aplicativo.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
A propriedade --roll-forward <value> do comando dotnet.

Ao executar um aplicativo, você pode controlar o comportamento de roll-forward através da linha de comando:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
A variável de ambiente DOTNET_ROLL_FORWARD.

Precedência

O comportamento de avanço é definido pela seguinte ordem quando seu aplicativo é executado, com itens numerados mais altos tendo precedência sobre itens numerados mais baixos:

Primeiro, o arquivo de configuração *.runtimeconfig.json é avaliado.
Em seguida, a variável de ambiente DOTNET_ROLL_FORWARD é considerada, substituindo a verificação anterior.
Finalmente, qualquer parâmetro --roll-forward passado para o aplicativo em execução substitui todo o resto.

Valores

No entanto, ao definir a configuração roll-forward, utilize um dos seguintes valores para configurar o comportamento:

Valor	Descrição
`Minor`	Padrão se não for especificado. Avançar para a menor versão menor superior, se a versão menor solicitada estiver ausente. Se a versão secundária solicitada estiver presente, então a política `LatestPatch` será usada.
`Major`	Avançar para a próxima versão principal superior disponível e para a versão secundária mais baixa, se a versão principal solicitada estiver ausente. Se a versão principal solicitada estiver presente, a política de `Minor` será usada.
`LatestPatch`	Avançar para a versão de atualização mais alta. Este valor desativa o roll-forward da versão menor.
`LatestMinor`	Avançar para a versão menor mais alta, mesmo que a versão menor solicitada esteja presente.
`LatestMajor`	Avançar para a maior versão principal e a maior versão secundária, mesmo que a versão principal solicitada esteja presente.
`Disable`	Não faça progressão, apenas vincule-se à versão especificada. Esta política não é recomendada para uso geral, uma vez que desativa a capacidade de avançar para os patches mais recentes. Este valor só é recomendado para testes.

As implantações independentes incluem o tempo de execução selecionado

Você pode publicar um aplicativo como uma distribuição independente. Essa abordagem agrupa o tempo de execução e as bibliotecas do .NET com seu aplicativo. As implantações autônomas não dependem de ambientes de tempo de execução. A seleção da versão do tempo de execução ocorre no momento da publicação, não no tempo de execução.

O restaurar evento que ocorre quando a publicação seleciona a versão de patch mais recente da família de tempo de execução dada. Por exemplo, dotnet publish selecionará .NET 5.0.3 se for a versão de patch mais recente na família de tempo de execução do .NET 5. A estrutura de destino (incluindo os patches de segurança instalados mais recentes) é empacotada com o aplicativo.

Ocorre um erro se a versão mínima especificada para um aplicativo não for satisfeita. dotnet publish vincula-se à versão mais recente do patch de runtime (dentro de uma determinada família de versões major.minor). dotnet publish não suporta a semântica roll-forward do dotnet run. Para obter mais informações sobre patches e implementações autónomas, consulte o artigo sobre de seleção de patches de runtime ao implementar aplicações .NET.

Implantações independentes podem exigir uma versão de patch específica. Você pode substituir a versão mínima do patch de tempo de execução (para versões superiores ou inferiores) no arquivo de projeto, conforme mostrado no exemplo a seguir:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

O elemento RuntimeFrameworkVersion substitui a política de versão padrão. Para implantações independentes, o RuntimeFrameworkVersion especifica a versão exata da estrutura de tempo de execução. Para aplicações dependentes do framework, o RuntimeFrameworkVersion especifica a versão mínima do framework de runtime necessária.

Partilhar via