Selecionar a versão do .NET Core a ser usadaSelect the .NET Core version to use

Este artigo explica as políticas usadas pelas ferramentas do .NET Core, pelo SDK e pelo runtime para a seleção de versões.This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. 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.These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. Essas políticas executam as seguintes ações:These policies perform the following actions:

  • Implantação fácil e eficiente do .NET Core, incluindo atualizações de segurança e de confiabilidade.Easy and efficient deployment of .NET Core, including security and reliability updates.
  • Uso das ferramentas e dos comandos mais recentes independentes do runtime de destino.Use the latest tools and commands independent of target runtime.

A seleção de versão ocorre:Version selection occurs:

O restante deste documento examina esses quatro cenários.The rest of this document examines those four scenarios.

O SDK usa a versão mais recente instaladaThe SDK uses the latest installed version

Os comandos do SDK incluem dotnet new e dotnet run.SDK commands include dotnet new and dotnet run. A CLI do .NET Core precisa escolher uma versão do SDK para todos os comandos dotnet.The .NET Core CLI must choose an SDK version for every dotnet command. Por padrão, ela usa o SDK mais recente instalado no computador, mesmo se:It uses the latest SDK installed on the machine by default, even if:

  • O projeto se destinar a uma versão anterior do runtime do .NET Core.The project targets an earlier version of the .NET Core runtime.
  • A versão mais recente do SDK do .NET Core for uma versão prévia.The latest version of the .NET Core SDK is a preview version.

Você pode aproveitar os recursos e as melhorias mais recentes do SDK mesmo ao direcionar a versões anteriores de runtime do .NET Core.You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. Você pode direcionar a várias versões de runtime do .NET Core em projetos diferentes, usando as mesmas ferramentas do SDK para todos os projetos.You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

Em raras ocasiões, talvez você precise usar uma versão anterior do SDK.On rare occasions, you may need to use an earlier version of the SDK. Nesse caso, especifique essa versão em um arquivo global. JSON.You specify that version in a global.json file. A política "usar versão mais recente" significa usar o global.json somente para especificar uma versão do SDK do .NET Core anterior à versão mais recente instalada.The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

O global.json pode ser colocado em qualquer lugar na hierarquia de arquivos.global.json can be placed anywhere in the file hierarchy. A CLI procura no diretório do projeto em diante até encontrar o primeiro global.json.The CLI searches upward from the project directory for the first global.json it finds. Você controla a quais projetos um determinado global.json se aplica a pelo seu lugar no sistema de arquivos.You control which projects a given global.json applies to by its place in the file system. A CLI do .NET procura um arquivo global.json navegando iterativamente do caminho do diretório de trabalho atual em diante.The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. O primeiro arquivo global.json encontrado especifica a versão usada.The first global.json file found specifies the version used. Se essa versão do SDK estiver instalada, essa versão será usada.If that SDK version is installed, that version is used. Se o SDK especificado no global.jsem não for encontrado, a CLI do .NET usará regras de correspondência para selecionar um SDK compatível ou falhará se nenhum for encontrado.If the SDK specified in the global.json is not found, the .NET CLI uses matching rules to select a compatible SDK, or fails if none is found.

O exemplo a seguir mostra a sintaxe global.json:The following example shows the global.json syntax:

{
  "sdk": {
    "version": "3.0.0"
  }
}

O processo para selecionar uma versão do SDK é:The process for selecting an SDK version is:

  1. O dotnet procura um arquivo global.json navegando inversamente de forma iterativa no caminho do diretório de trabalho atual em diante.dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. O dotnet usa o SDK especificado no primeiro global.json encontrado.dotnet uses the SDK specified in the first global.json found.
  3. O dotnet usará a versão mais recente do SDK instalada se nenhum global.json for encontrado.dotnet uses the latest installed SDK if no global.json is found.

Saiba mais sobre como selecionar uma versão do SDK na seção Regras de correspondência do artigo sobre o global.json.You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

Os Monikers da Estrutura de Destino definem as APIs de tempo de buildTarget Framework Monikers define build time APIs

Você compila seu projeto em relação às APIs definidas em um TFM (Moniker da Estrutura de Destino).You build your project against APIs defined in a Target Framework Moniker (TFM). Você especifica a estrutura de destino no arquivo de projeto.You specify the target framework in the project file. Defina o elemento TargetFramework no arquivo de projeto, conforme mostrado no exemplo a seguir:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp3.0</TargetFramework>

Você pode compilar o projeto em relação a várias TFMs.You may build your project against multiple TFMs. A definição de várias estruturas de destino é mais comum em bibliotecas, mas também pode ocorrer com aplicativos.Setting multiple target frameworks is more common for libraries but can be done with applications as well. Especifique uma propriedade TargetFrameworks (plural de TargetFramework).You specify a TargetFrameworks property (plural of TargetFramework). As estruturas de destino são delimitadas por ponto e vírgula, conforme mostrado no exemplo a seguir:The target frameworks are semicolon-delimited as shown in the following example:

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

Um determinado SDK dá suporte a um conjunto fixo de estruturas, limitado à estrutura de destino do runtime com o qual é fornecido.A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. Por exemplo, o SDK do .NET Core 3,0 inclui o tempo de execução do .NET Core 3,0, que é uma implementação da netcoreapp3.0 estrutura de destino.For example, the .NET Core 3.0 SDK includes the .NET Core 3.0 runtime, which is an implementation of the netcoreapp3.0 target framework. O SDK do .NET Core 3,0 dá suporte a netcoreapp2.1 ,, netcoreapp2.2 netcoreapp3.0 , mas não netcoreapp3.1 (ou superior).The .NET Core 3.0 SDK supports netcoreapp2.1, netcoreapp2.2, netcoreapp3.0, but not netcoreapp3.1 (or higher). Você instala o SDK do .NET Core 3,1 para compilar para o netcoreapp3.1 .You install the .NET Core 3.1 SDK to build for netcoreapp3.1.

As estruturas de destino do .NET Standard também são limitadas à estrutura de destino do runtime com o qual o SDK é fornecido..NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. O SDK do .NET Core 3,1 está limitado ao netstandard2.1 .The .NET Core 3.1 SDK is capped to netstandard2.1. Para obter mais informações, confira .NET Standard.For more information, see .NET Standard.

Roll foward de aplicativos dependentes da estruturaFramework-dependent apps roll forward

Quando você executa um aplicativo de origem com dotnet run , de uma implantação dependente de estrutura com o dotnet myapp.dll , ou de um executável dependente de estrutura com myapp.exe , o dotnet executável é o host para o aplicativo.When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

O host escolhe a versão de patch mais recente instalada no computador.The host chooses the latest patch version installed on the machine. Por exemplo, se você especificar netcoreapp3.0 em seu arquivo de projeto e 3.0.2 for o runtime mais recente do .NET instalado, o runtime 3.0.2 será usado.For example, if you specified netcoreapp3.0 in your project file, and 3.0.2 is the latest .NET runtime installed, the 3.0.2 runtime is used.

Se nenhuma versão 3.0.* aceitável for encontrada, uma nova versão 3.* será usada.If no acceptable 3.0.* version is found, a new 3.* version is used. Por exemplo, se você especificar netcoreapp3.0 e só o 3.1.0 estiver instalado, o aplicativo será executado usando o runtime 3.1.0.For example, if you specified netcoreapp3.0 and only 3.1.0 is installed, the application runs using the 3.1.0 runtime. Esse comportamento é conhecido como "roll forward de versão secundária".This behavior is referred to as "minor version roll-forward." As versões inferiores também não serão consideradas.Lower versions also won't be considered. Quando nenhum runtime aceitável estiver instalado, o aplicativo não será executado.When no acceptable runtime is installed, the application won't run.

Alguns exemplos de uso demonstram o comportamento, se você visar 3,0:A few usage examples demonstrate the behavior, if you target 3.0:

  • ✔️ 3,0 está especificado.✔️ 3.0 is specified. 3.0.3 é a versão de patch mais alta instalada.3.0.3 is the highest patch version installed. 3.0.3 é usado.3.0.3 is used.
  • ❌ 3,0 está especificado.❌ 3.0 is specified. Nenhuma versão 3,0. * está instalada.No 3.0.* versions are installed. 2.1.1 é o tempo de execução mais alto instalado.2.1.1 is the highest runtime installed. Uma mensagem de erro é exibida.An error message is displayed.
  • ✔️ 3,0 está especificado.✔️ 3.0 is specified. Nenhuma versão 3,0. * está instalada.No 3.0.* versions are installed. 3.1.0 é a versão de tempo de execução mais alta instalada.3.1.0 is the highest runtime version installed. 3.1.0 é usado.3.1.0 is used.
  • ❌ 2,0 está especificado.❌ 2.0 is specified. Não há nenhuma versão 2.x instalada.No 2.x versions are installed. 3.0.0 é o tempo de execução mais alto instalado.3.0.0 is the highest runtime installed. Uma mensagem de erro é exibida.An error message is displayed.

O roll forward de versão secundária tem um efeito colateral que pode afetar os usuários finais.Minor version roll-forward has one side-effect that may affect end users. Considere o cenário a seguir.Consider the following scenario:

  1. O aplicativo especifica que 3,0 é necessário.The application specifies that 3.0 is required.
  2. Quando executado, a versão 3,0. * não está instalada, no entanto, 3.1.0 é.When run, version 3.0.* is not installed, however, 3.1.0 is. A versão 3.1.0 será usada.Version 3.1.0 will be used.
  3. Posteriormente, o usuário instala o 3.0.3 e executa o aplicativo novamente, 3.0.3 será usado agora.Later, the user installs 3.0.3 and runs the application again, 3.0.3 will now be used.

É possível que 3.0.3 e 3.1.0 se comportem de forma diferente, especialmente em cenários como a serialização de dados binários.It's possible that 3.0.3 and 3.1.0 behave differently, particularly for scenarios like serializing binary data.

As implantações autossuficientes incluem o runtime selecionadoSelf-contained deployments include the selected runtime

É possível publicar um aplicativo como uma distribuição autossuficiente.You can publish an application as a self-contained distribution. Essa abordagem inclui o runtime e as bibliotecas do .NET Core com seu aplicativo.This approach bundles the .NET Core runtime and libraries with your application. As implantações autossuficientes não são dependentes dos ambientes de runtime.Self-contained deployments don't have a dependency on runtime environments. A seleção da versão do runtime ocorre no momento da publicação, não no runtime.Runtime version selection occurs at publishing time, not run time.

O processo de publicação seleciona a versão de patch mais recente da família de determinado runtime.The publishing process selects the latest patch version of the given runtime family. Por exemplo, dotnet publish selecionará o .NET Core 3.0.3 se for a versão de patch mais recente na família de tempo de execução do .NET Core 3,0.For example, dotnet publish will select .NET Core 3.0.3 if it is the latest patch version in the .NET Core 3.0 runtime family. A estrutura de destino (incluindo os patches de segurança mais recentes instalados) é empacotada com o aplicativo.The target framework (including the latest installed security patches) is packaged with the application.

É um erro quando a versão mínima especificada para um aplicativo não é atendida.It's an error if the minimum version specified for an application isn't satisfied. 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 binds to the latest runtime patch version (within a given major.minor version family). dotnet publish não dá suporte à semântica de roll forward de dotnet run.dotnet publish doesn't support the roll-forward semantics of dotnet run. Para obter mais informações sobre patches e implantações autossuficientes, consulte o artigo sobre seleção de patch de runtime na implantação de aplicativos .NET Core.For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

As implantações autossuficientes podem exigir uma versão de patch específica.Self-contained deployments may require a specific patch version. 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:You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>3.0.3</RuntimeFrameworkVersion>

O elemento RuntimeFrameworkVersion substitui a política de versão padrão.The RuntimeFrameworkVersion element overrides the default version policy. Para implantações autossuficientes, o RuntimeFrameworkVersion especifica a versão exata da estrutura do runtime.For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. Para aplicativos dependentes da estrutura, o RuntimeFrameworkVersion especifica a versão mínima da estrutura de runtime necessária.For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.

Confira tambémSee also