选择要使用的 .NET Core 版本Select the .NET Core version to use

本文介绍 .NET Core 工具、SDK 和运行时在选择版本时所使用的策略。This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. 这些策略可通过使用指定版本,使正在运行的应用程序之间达到平衡,同时实现开发人员和最终用户计算机的轻松升级。These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. 这些策略执行以下操作:These policies perform the following actions:

  • 实现 .NET Core 的轻松高效部署,包括安全性和可靠性更新。Easy and efficient deployment of .NET Core, including security and reliability updates.
  • 使用独立于目标运行时的最新工具和命令。Use the latest tools and commands independent of target runtime.

需要选择版本的情况如下:Version selection occurs:

本文档其余部分将介绍这四种方案。The rest of this document examines those four scenarios.

SDK 使用最新安装的版本The SDK uses the latest installed version

SDK 命令包括 dotnet newdotnet runSDK commands include dotnet new and dotnet run. .NET Core CLI 必须为每个 dotnet 命令选择 SDK 版本。The .NET Core CLI must choose an SDK version for every dotnet command. 即使在以下情况下,它也会默认使用计算机上安装的最新 SDK:It uses the latest SDK installed on the machine by default, even if:

  • 项目面向早期 .NET Core 运行时版本。The project targets an earlier version of the .NET Core runtime.
  • .NET Core SDK 的最新版本是预览版本。The latest version of the .NET Core SDK is a preview version.

面向较旧的 .NET Core 运行时版本时,可利用最新的 SDK 功能和功能改进。You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. 可在不同项目上面向 .NET Core 的多个运行时版本,同时对所有项目使用相同的 SDK 工具。You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

在少数情况下,可能需要使用版本较旧的 SDK。On rare occasions, you may need to use an earlier version of the SDK. global.json 文件中指定该版本 。You specify that version in a global.json file. “使用最新”策略表示仅使用 global.json 指定早于最新安装版本的一个 .NET Core SDK 版本 。The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

可将 global.json 放置在文件层次结构中的任何位置 。global.json can be placed anywhere in the file hierarchy. CLI 从项目目录中向上搜索其找到的第一个 global.json 。The CLI searches upward from the project directory for the first global.json it finds. 由用户控制对哪些项目应用给定的 global.json(按其在文件系统中的位置) 。You control which projects a given global.json applies to by its place in the file system. .NET CLI 从当前工作目录路径向上导航,以迭代方式搜索 global.json 文件 。The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. 找到的第一个 global.json 文件指定要使用的版本 。The first global.json file found specifies the version used. 如果已安装该 SDK 版本,则使用该版本。If that SDK version is installed, that version is used. 如果找不到 global.json 中指定的 SDK,则 .NET CLI 将使用匹配规则来选择兼容的 SDK,如果找不到,则会失败。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.

下面的示例演示 global.json 语法 :The following example shows the global.json syntax:

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

选择 SDK 版本的过程如下:The process for selecting an SDK version is:

  1. dotnet 从当前工作目录向下导航路径,以迭代方式搜索 global.json 文件 。dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet 使用所找到的第一个 global.json 中指定的 SDK 。dotnet uses the SDK specified in the first global.json found.
  3. 如果未找到 global.json,dotnet 使用最新安装的 SDK 。dotnet uses the latest installed SDK if no global.json is found.

有关选择 SDK 版本的详细信息,可参阅 global.json 相关文章的匹配规则部分 。You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

目标框架名字对象用于定义生成时 APITarget Framework Monikers define build time APIs

针对在“目标框架名字对象”(TFM) 中定义的 API 构建项目 。You build your project against APIs defined in a Target Framework Moniker (TFM). 在项目文件中指定目标框架You specify the target framework in the project file. 按如下示例所示,设置项目文件中的 TargetFramework 元素:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp3.0</TargetFramework>

可能会针对多个 TFM 构建项目。You may build your project against multiple TFMs. 对库设置多个目标框架更为常见,但也可对应用程序执行此操作。Setting multiple target frameworks is more common for libraries but can be done with applications as well. 指定 TargetFrameworks 属性(TargetFramework 的复数形式)。You specify a TargetFrameworks property (plural of TargetFramework). 目标框架以分号分隔,如下例所示:The target frameworks are semicolon-delimited as shown in the following example:

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

给定的 SDK 支持固定的一组框架,其中的上限框架为 SDK 附带的运行时的目标框架。A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. 例如,.NET Core 3.0 SDK 包含 .NET Core 3.0 运行时,该运行时是 netcoreapp3.0 目标框架的一个实现。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. .NET Core 3.0 SDK 支持 netcoreapp2.1netcoreapp2.2netcoreapp3.0,但不支持 netcoreapp3.1(或更高版本)。The .NET Core 3.0 SDK supports netcoreapp2.1, netcoreapp2.2, netcoreapp3.0, but not netcoreapp3.1 (or higher). 安装 .NET Core 3.1 SDK 以针对 netcoreapp3.1 进行构建。You install the .NET Core 3.1 SDK to build for netcoreapp3.1.

.NET Standard 目标框架中的上限框架同样是 SDK 附带的运行时的目标框架。.NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. .NET Core 3.1 SDK 的上限为 netstandard2.1The .NET Core 3.1 SDK is capped to netstandard2.1. 有关详细信息,请参阅 .NET StandardFor more information, see .NET Standard.

依赖于框架的应用会前滚Framework-dependent apps roll forward

在使用 dotnet run 从源运行应用程序时,在使用 dotnet myapp.dll框架相关部署 运行应用程序时,或使用 myapp.exe框架相关可执行文件 运行应用程序时,dotnet 可执行文件是应用程序的主机 。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.

该主机选择计算机上安装的最新修补程序版本。The host chooses the latest patch version installed on the machine. 例如,如果在项目文件中指定 netcoreapp3.0,并且 3.0.4 是安装的最新 .NET 运行时,则使用 3.0.4 运行时。For example, if you specified netcoreapp3.0 in your project file, and 3.0.4 is the latest .NET runtime installed, the 3.0.4 runtime is used.

如果未找到可接受的 3.0.* 版本,则使用新的 3.* 版本。If no acceptable 3.0.* version is found, a new 3.* version is used. 例如,如果指定了 netcoreapp3.0 并且仅安装了 3.1.0,则应用程序在运行时使用 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. 此行为称为“次要版本前滚”。This behavior is referred to as "minor version roll-forward." 此外,不会考虑较低版本。Lower versions also won't be considered. 如果未安装可接受的运行时,应用程序将不会运行。When no acceptable runtime is installed, the application won't run.

如果你面向版本 3.0,则下面几个使用示例展示了此行为:A few usage examples demonstrate the behavior, if you target 3.0:

  • ✔️ 指定 3.0。✔️ 3.0 is specified. 3.0.5 是安装的最高修补程序版本。3.0.5 is the highest patch version installed. 使用 3.0.5。3.0.5 is used.
  • ❌ 指定 3.0。❌ 3.0 is specified. 未安装 3.0.* 版本。No 3.0.* versions are installed. 2.1.1 是安装的最高运行时版本。2.1.1 is the highest runtime installed. 会显示一条错误消息。An error message is displayed.
  • ✔️ 指定 3.0。✔️ 3.0 is specified. 未安装 3.0.* 版本。No 3.0.* versions are installed. 3.1.0 是安装的最高运行时版本。3.1.0 is the highest runtime version installed. 使用 3.1.0。3.1.0 is used.
  • ❌ 指定 2.0。❌ 2.0 is specified. 未安装 2.x 版本。No 2.x versions are installed. 3.0.0 是安装的最高运行时版本。3.0.0 is the highest runtime installed. 会显示一条错误消息。An error message is displayed.

次要版本回滚会产生一个可能影响最终用户的副作用。Minor version roll-forward has one side-effect that may affect end users. 请参考以下方案:Consider the following scenario:

  1. 应用程序指定需要版本 3.0。The application specifies that 3.0 is required.
  2. 运行时,未安装 3.0.*,安装的是 3.1.0。When run, version 3.0.* is not installed, however, 3.1.0 is. 将使用版本 3.1.0。Version 3.1.0 will be used.
  3. 稍后,用户重新安装 3.0.5 和运行应用程序,而现将使用版本 3.0.5。Later, the user installs 3.0.5 and runs the application again, 3.0.5 will now be used.

3.0.5 和 3.1.0 可能具有不同行为,序列化二进制数据等方案中尤其如此。It's possible that 3.0.5 and 3.1.0 behave differently, particularly for scenarios like serializing binary data.

独立部署包括所选的运行时Self-contained deployments include the selected runtime

可以将应用程序作为独立分发进行发布 。You can publish an application as a self-contained distribution. 此方法可将 .NET Core 运行时和库与应用程序进行捆绑。This approach bundles the .NET Core runtime and libraries with your application. 独立部署不具有对运行时环境的依赖关系。Self-contained deployments don't have a dependency on runtime environments. 在发布时(而不是运行时)选择运行时版本。Runtime version selection occurs at publishing time, not run time.

发布进程将选择给定运行时系列中的最新修补程序版本。The publishing process selects the latest patch version of the given runtime family. 例如,dotnet publish 将选择 .NET Core 3.0.4(如果它是 .NET Core 3.0 运行时系列中的最新修补程序版本)。For example, dotnet publish will select .NET Core 3.0.4 if it is the latest patch version in the .NET Core 3.0 runtime family. 目标框架(包括最新安装的安全修补程序)与应用程序捆绑打包。The target framework (including the latest installed security patches) is packaged with the application.

如果为应用程序指定的最新版本不满足要求,会出现错误。It's an error if the minimum version specified for an application isn't satisfied. dotnet publish 绑定到最新的运行时修补程序版本(在给定的主要及次要版本系列内)。dotnet publish binds to the latest runtime patch version (within a given major.minor version family). dotnet publish 不支持 dotnet run 的前滚语义。dotnet publish doesn't support the roll-forward semantics of dotnet run. 有关修补程序和独立部署的详细信息,请参阅有关 .NET Core 应用程序部署中运行时修补程序选择的文章。For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

独立部署可能需要特定修补程序版本。Self-contained deployments may require a specific patch version. 可以重写项目文件中的最低运行时修补程序版本(重写为更高或更低版本),如下例所示: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.4</RuntimeFrameworkVersion>

RuntimeFrameworkVersion 元素重写默认版本策略。The RuntimeFrameworkVersion element overrides the default version policy. 对于独立部署,RuntimeFrameworkVersion 指定确切的运行时框架版本 。For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. 对于依赖于框架的应用程序,RuntimeFrameworkVersion 指定所需的最低运行时框架版本 。For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.

请参阅See also