Selecione a versão .NET a ser usada

Artigo
03/05/2024

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 instalada mais recente.
Quando você cria um assembly, os monikers da estrutura de destino definem APIs de tempo de compilação.
Quando você executa um aplicativo .NET, os aplicativos dependentes da estrutura de destino são roll-forward.
Quando você publica um aplicativo independente, as 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 dotnet comando. 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 direcionar versões anteriores do tempo de execução do .NET. Você pode direcionar diferentes versões de tempo de execução do .NET usando as mesmas ferramentas SDK.

Em raras ocasiões, talvez seja necessário usar uma versão anterior do SDK. Você especifica essa versão em um arquivo global.json. A política "usar mais recente" significa que você usa apenas global.json para especificar uma versão do SDK do .NET anterior à versão instalada mais recente.

global.json pode ser colocado em qualquer lugar na hierarquia de arquivos. A CLI pesquisa para cima a partir do diretório do projeto pela primeira global.json encontra. 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. 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 usa o SDK instalado mais recente se nenhuma global.json for encontrada.

Para obter mais informações sobre a seleção de versão do SDK, consulte as seções Regras correspondentes e rollForward do artigo Visão geral do global.json.

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

Você cria seu projeto com base em APIs definidas em um moniker de estrutura de destino (TFM). Você especifica a estrutura de destino no arquivo de projeto. Defina o TargetFramework elemento em seu arquivo de projeto como 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 TargetFrameworks propriedade (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 tempo de execução do .NET 8, que é uma implementação da net8.0 estrutura de destino. O SDK do .NET 8 suporta net7.0, net6.0e net5.0, mas não net9.0 (ou superior). Instalar o SDK do .NET 9 para criar para net9.0.

.NET Standard

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.

Roll-forward de aplicativos dependentes da estrutura

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

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 5.0.2 tempo de execução é usado.

Se nenhuma versão aceitável 5.0.* for encontrada, uma nova 5.* versão será usada. Por exemplo, se você especificou net5.0 e só 5.1.0 está instalado, o aplicativo é executado usando o 5.1.0 tempo de execução. Esse comportamento é conhecido como "roll-forward de versão secundária". 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. 5.0.3.
❌ 5.0 é 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 é 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 roll-forward tem um efeito colateral que pode afetar os usuários 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 roll-forward

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 <RollForward> propriedade:

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

O *.runtimeconfig.json arquivo.

Este ficheiro é produzido quando compila a sua aplicação. Se a <RollForward> propriedade foi definida no projeto, ela é reproduzida no *.runtimeconfig.json arquivo como a rollForward configuração. 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 dotnet propriedade do --roll-forward <value> comando.

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 DOTNET_ROLL_FORWARD variável de ambiente.

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

Valores

No entanto, você define a configuração roll-forward, use um dos seguintes valores para definir o comportamento:

valor	Description
`Minor`	Padrão se não especificado. Roll-forward para a versão secundária superior mais baixa, se a versão secundária solicitada estiver ausente. Se a versão secundária solicitada estiver presente, a `LatestPatch` política 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 `Minor` política será usada.
`LatestPatch`	Roll-forward para a versão de patch mais alta. Esse valor desabilita o roll-forward da versão secundária.
`LatestMinor`	Avançar para a versão secundária mais alta, mesmo que a versão secundária solicitada esteja presente.
`LatestMajor`	Roll-forward para a versão principal mais alta e a versão secundária mais alta, mesmo que a versão principal solicitada esteja presente.
`Disable`	Não faça roll-forward, 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 evento restore que ocorre ao publicar 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 liga-se à versão mais recente do patch de tempo de execução (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 implantações independentes, consulte o artigo sobre seleção de patches de tempo de execução na implantação de aplicativos .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 RuntimeFrameworkVersion elemento 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 aplicativos dependentes da estrutura, o RuntimeFrameworkVersion especifica a versão mínima necessária da estrutura de tempo de execução.