Selecionar a versão do .NET a ser usada

Artigo
05/10/2023

Este artigo explica as políticas usadas pelas ferramentas do .NET, pelo SDK e pelo runtime para a seleção de versões. Essas políticas fornecem um equilíbrio entre a execução de aplicativos usando as versões especificadas e a possibilidade de fácil atualização dos computadores de desenvolvedores e usuários finais. Essas políticas habilitam:

Implantação fácil e eficiente do .NET, incluindo atualizações de segurança e de confiabilidade.
Uso das ferramentas e dos comandos mais recentes independentes do runtime de destino.

A seleção de versão ocorre:

Quando você executa um comando do SDK, o SDK usa a versão mais recente instalada.
Quando você compila um assembly os monikers da estrutura de destino definem as APIs do tempo de build.
Quando você executa um aplicativo .NET, os aplicativos dependentes da estrutura de destino efetuam roll forward.
Quando você publica um aplicativo autossuficiente, as implantações autossuficientes incluem o runtime selecionado.

O restante deste documento examina esses quatro cenários.

O SDK usa a versão mais recente instalada

Os comandos do SDK incluem dotnet new e dotnet run. A CLI do .NET precisa escolher uma versão do SDK para todos os comandos dotnet. Por padrão, ela usa o SDK mais recente instalado no computador, mesmo se:

O projeto se destinar a uma versão anterior do runtime do .NET.
A versão mais recente do SDK do .NET for uma versão prévia.

Você pode aproveitar os recursos e as melhorias mais recentes do SDK mesmo ao direcionar a versões anteriores de runtime do .NET. Você pode direcionar versões de runtime diferentes do .NET usando as mesmas ferramentas de SDK.

Em raras ocasiões, talvez você precise usar uma versão anterior do SDK. Nesse caso, especifique essa versão em um arquivo global. JSON. A política "usar versão mais recente" significa usar o global.json somente para especificar uma versão do SDK do .NET anterior à versão mais recente instalada.

O global.json pode ser colocado em qualquer lugar na hierarquia de arquivos. A CLI procura no diretório do projeto em diante até encontrar o primeiro global.json. Você controla a quais projetos um determinado global.json se aplica a pelo seu lugar no sistema de arquivos. A CLI do .NET procura um arquivo global.json navegando iterativamente do caminho do diretório de trabalho atual em diante. O primeiro arquivo global.json encontrado especifica a versão usada. Se essa versão do SDK estiver instalada, ela será usada. Se o SDK especificado em 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 é:

O dotnet procura um arquivo global.json navegando inversamente de forma iterativa no caminho do diretório de trabalho atual em diante.
O dotnet usa o SDK especificado no primeiro global.json encontrado.
O dotnet usará a versão mais recente do SDK instalada se nenhum global.json for encontrado.

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

Os monikers da estrutura de destino definem as APIs de tempo de build

Você compila seu projeto em relação às APIs definidas em um TFM (moniker da estrutura de destino). Você especifica a estrutura de destino no arquivo de projeto. Defina o elemento TargetFramework no arquivo de projeto, conforme mostrado no exemplo a seguir:

<TargetFramework>net8.0</TargetFramework>

Você pode compilar o projeto em relação a várias TFMs. A definição de várias estruturas de destino é mais comum em bibliotecas, mas também pode ocorrer com aplicativos. Especifique 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 dá suporte a um conjunto fixo de estruturas, limitado à estrutura de destino do runtime com o qual é fornecido. Por exemplo, o SDK do .NET 8 inclui o runtime do .NET 8, que é uma implementação da estrutura de destino net8.0. O SDK do .NET Core 8 dá suporte ao net7.0, net6.0 e net5.0 mas não ao net9.0 (ou superior). Instale o SDK do .NET 9 para compilar para o net9.0.

.NET Standard

O .NET Standard foi uma maneira de direcionar uma superfície de API compartilhada por diferentes implementações do .NET. A partir da versão .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ê visa o .NET e o .NET Framework. O .NET 5 implementa todas as versões do .NET Standard.

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

Roll foward de aplicativos dependentes da estrutura

Quando você executa um aplicativo da fonte com dotnet run, de uma implantação dependente de estrutura com dotnet myapp.dll ou de um arquivo executável dependente de estrutura com myapp.exe, o arquivo executável dotnet é o host do aplicativo.

O host escolhe a versão de patch mais recente instalada no computador. Por exemplo, se você especificar net5.0 em seu arquivo de projeto e 5.0.2 for o runtime mais recente do .NET instalado, o runtime 5.0.2 será usado.

Se nenhuma versão 5.0.* aceitável for encontrada, uma nova versão 5.* será usada. Por exemplo, se você especificar net5.0 e só o 5.1.0 estiver instalado, o aplicativo será executado usando o runtime 5.1.0. Esse comportamento é conhecido como "roll forward de versão secundária". Versões inferiores também não serão consideradas. Quando nenhum runtime aceitável estiver instalado, o aplicativo não será executado.

Veja alguns exemplos de uso que demonstram o comportamento, caso seu destino seja a versão 5.0:

✔️ 5.0 é especificado. A 5.0.3 é a versão de patch mais recente instalada. A 5.0.3 é usada.
❌A 5.0 é especificada. Não há versão 5.0.* instalada. O 3.1.1 é o runtime mais recente instalado. Uma mensagem de erro é exibida.
✔️ 5.0 é especificado. Não há versão 5.0.* instalada. 5.1.0 é a versão de runtime mais recente instalada. A 5.1.0 é usada.
❌A 3.0 é especificada. Não há uma versão 3.x instalada. O 5.0.0 é o runtime mais recente instalado. Uma mensagem de erro é exibida.

O roll forward de versão secundária tem um efeito colateral que pode afetar os usuários finais. Considere o cenário a seguir.

O aplicativo especifica que a versão 5.0 é necessária.
Quando executado, a versão 5.0.* não está instalada, mas a 5.1.0 está. A versão 5.1.0 será usada.
Posteriormente, o usuário instala a versão 5.0.3 e executa o aplicativo novamente. A 5.0.3 será então usada.

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

Controlar o comportamento de roll forward

Antes de substituir o comportamento rollforward padrão, familiarize-se com o nível de compatibilidade de runtime do .NET.

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

Configuração no projeto definindo a propriedade <RollForward>:

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

O arquivo *.runtimeconfig.json.

Esse arquivo é produzido quando você compila seu aplicativo. Se a propriedade <RollForward> foi definida no projeto, ela será reproduzida no arquivo *.runtimeconfig.json como a configuração rollForward. Os usuários podem editar esse arquivo para alterar o comportamento do 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 por meio 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 roll forward é definido pela ordem a seguir quando o aplicativo é executado, itens de numeração maior têm precedência sobre itens de numeração menor:

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

Valores

No entanto, defina a configuração de roll-forward. Use um dos seguintes valores para definir o comportamento:

Valor	Descrição
`Minor`	Padrão, se não especificado. Se a versão secundária solicitada estiver ausente, efetue roll forward para a menor versão secundária mais recente. Se a versão secundária solicitada estiver presente, a política `LatestPatch` será usada.
`Major`	Se a versão principal solicitada estiver ausente, efetuar roll forward para a versão principal mais recente disponível e a versão secundária mais antiga. Se a versão principal solicitada está presente, a política `Minor` é usada.
`LatestPatch`	Efetuar roll forward para a versão de patch mais recente. Esse valor desabilita o roll forward da versão secundária.
`LatestMinor`	Efetuar roll forward para a versão secundária mais recente, mesmo se a versão secundária solicitada estiver presente.
`LatestMajor`	Efetuar roll forward para a versão principal e a secundária mais recentes, mesmo se a principal solicitada estiver presente.
`Disable`	Não efetuar roll forward, apenas associar à versão especificada. Essa política não é recomendada para uso geral, pois desabilita a capacidade de efetuar roll forward para os patches mais recentes. Esse valor só é recomendado para teste.

As implantações autossuficientes incluem o runtime selecionado

É possível publicar um aplicativo como uma distribuição autossuficiente. Essa abordagem inclui o runtime e as bibliotecas do .NET com seu aplicativo. As implantações autossuficientes não são dependentes dos ambientes de runtime. A seleção da versão do runtime ocorre no momento da publicação, não no runtime.

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

Há um erro quando a versão mínima especificada de um aplicativo não é atendida. O dotnet publish vincula-se à última versão de patch de runtime (em uma determinada família de versão principal.secundária). dotnet publish não dá suporte à semântica de roll forward de dotnet run. Para obter mais informações sobre patches e implantações autossuficientes, confira o artigo sobre seleção de patch de runtime na implantação de aplicativos .NET.

As implantações autossuficientes podem exigir uma versão de patch específica. Você pode substituir a versão de patch mínima do runtime (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 autossuficientes, o RuntimeFrameworkVersion especifica a versão exata da estrutura do runtime. Para aplicativos dependentes da estrutura, o RuntimeFrameworkVersion especifica a versão mínima da estrutura de runtime necessária.