Selecione a versão do .NET a ser usada

Este artigo explica as políticas usadas pelas ferramentas .NET, SDK e runtime para selecionar versões. Essas políticas fornecem um equilíbrio entre executar aplicativos usando as versões especificadas e habilitar a facilidade de atualizar computadores de desenvolvedor e de usuário final. Essas políticas permitem:

• Implantação fácil e eficiente do .NET, incluindo atualizações de segurança e confiabilidade.
• Use as ferramentas e os comandos mais recentes independentemente 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 deve escolher uma versão do SDK para cada comando dotnet. Ele usa o SDK mais recente instalado no computador por padrão, mesmo se:

• O projeto tem como destino uma versão anterior do runtime do .NET.
• A versão mais recente do SDK do .NET é 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 diferentes versões de runtime do .NET usando as mesmas ferramentas do SDK.

Em algumas circunstâncias, talvez seja necessário usar uma versão específica do SDK. Especifique 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 o caminho para cima 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 é:

1. dotnet pesquisa um arquivo global.json navegando iterativamente inversamente o caminho para cima do diretório de trabalho atual.
2. dotnet usa o SDK especificado no primeiro global.json encontrado.
3. 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.

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 no 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 Dependabot para atualizar automaticamente a versão do SDK fixada à medida que novas versões estiverem disponíveis.

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. Definir várias estruturas de destino é mais comum para bibliotecas, mas também pode ser feito 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 ele é fornecido. Por exemplo, o SDK do .NET 8 inclui o runtime do .NET 8, que é uma implementação do framework de destino net8.0. O SDK do .NET 8 dá suporte a net7.0, net6.0e net5.0, mas não 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 do lançamento do .NET 5, que é um padrão de API em si, o .NET Standard tem pouca relevância, exceto em um cenário: o .NET Standard é útil quando você deseja direcionar tanto ao .NET quanto ao .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 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 mais recente do patch instalada no computador. Por exemplo, se você especificou net5.0 no arquivo de projeto e 5.0.2 é o runtime do .NET mais recente instalado, o runtime do 5.0.2 será usado.

Se nenhuma versão de 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 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 for 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. 5.0.3 é a versão de patch mais alta instalada. 5.0.3 é usado.
• A ❌ 5.0 é especificada. Nenhuma versão 5.0.* está instalada. A maior versão do runtime instalada é a 3.1.1. Uma mensagem de erro é exibida.
• ✔️ 5.0 é especificado. Nenhuma versão 5.0.* está instalada. 5.1.0 é a versão de runtime mais alta instalada. 5.1.0 é usado.
• A ❌ 3.0 é especificada. Nenhuma versão 3.x está instalada. 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 seguinte cenário:

1. O aplicativo especifica que 5.0 é necessário.
2. Quando executada, a versão 5.0.* não está instalada, no entanto, a 5.1.0 é. A versão 5.1.0 será usada.
3. Posteriormente, o usuário instala a 5.0.3 e executa o aplicativo novamente, a versão 5.0.3 agora será usada.

É possível que 5.0.3 e 5.1.0 se comportem de forma diferente, especialmente para cenários como serializar 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 para um aplicativo pode ser configurado de quatro maneiras diferentes:

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

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

2. 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 de 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"
       }
     }
   }
   

3. 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
   

4. A variável de ambiente DOTNET_ROLL_FORWARD.

Precedência

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

1. Primeiro, o arquivo de configuração *.runtimeconfig.json é avaliado.
2. Em seguida, a variável de ambiente DOTNET_ROLL_FORWARD é considerada, substituindo a verificação anterior.
3. 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:

As implantações autossuficientes incluem o runtime selecionado

É possível publicar um aplicativo como uma distribuição autossuficiente. Essa abordagem agrupa 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 de versão de runtime ocorre no tempo de publicação, não no tempo de execução.

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 for a versão mais recente do patch na família de runtime do .NET 5. A estrutura de destino (incluindo os patches de segurança mais recentes instalados) é empacotada com o aplicativo.

Ocorrerá um erro se a versão mínima especificada para um aplicativo não for 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 alterar a versão mínima do patch de 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.

Consulte também

• Ecossistemas e repositórios suportados pelo Dependabot.
• Baixar e instalar o .NET.
• Como verificar se o .NET já está instalado.
• Como remover o runtime do .NET e o SDK.