选择要使用的 .NET 版本

项目
05/10/2023

本文介绍了 .NET 工具、SDK 和运行时用来选择版本的策略。这些策略可通过使用指定版本，使正在运行的应用程序之间达到平衡，同时实现开发人员和最终用户计算机的轻松升级。通过这些策略可实现：

简单高效的 .NET 部署，包括安全性和可靠性更新。
使用独立于目标运行时的最新工具和命令。

需要选择版本的情况如下：

运行 SDK 命令时，SDK 使用最新安装的版本。
生成程序集时，目标框架名字对象定义生成时 API。
运行 .NET 应用程序时，依赖于目标框架的应用会前滚。
发布独立应用程序时，独立部署包括所选的运行时。

本文档其余部分将介绍这四种方案。

SDK 使用最新安装的版本

SDK 命令包括 dotnet new 和 dotnet run。 .NET CLI 必须为每个 dotnet 命令选择一个 SDK 版本。即使在以下情况下，它也会默认使用计算机上安装的最新 SDK：

项目以旧版 .NET 运行时为目标。
.NET SDK 的最新版本是预览版。

你可以利用最新的 SDK 功能和改进，同时以较旧的 .NET 运行时版本为目标。可以使用相同的 SDK 工具面向不同运行时版本的 .NET。

在少数情况下，可能需要使用版本较旧的 SDK。在 global.json 文件中指定该版本。 “使用最新”策略表示仅使用 global.json 指定低于最新安装版本的 .NET SDK 版本。

可将 global.json 放置在文件层次结构中的任何位置。由用户控制对哪些项目应用给定的 global.json（按其在文件系统中的位置）。 .NET CLI 从当前工作目录路径向上导航，以迭代方式搜索 global.json 文件（不一定与项目目录相同）。找到的第一个 global.json 文件指定要使用的版本。如果已安装该 SDK 版本，则使用该版本。如果找不到 global.json 中指定的 SDK，则 .NET CLI 将使用匹配规则来选择兼容的 SDK，如果找不到，则会失败。

下面的示例演示 global.json 语法：

{
  "sdk": {
    "version": "5.0.0"
  }
}

选择 SDK 版本的过程如下：

dotnet 从当前工作目录向下导航路径，以迭代方式搜索 global.json 文件。
dotnet 使用所找到的第一个 global.json 中指定的 SDK。
如果未找到 global.json，dotnet 使用最新安装的 SDK。

有关 SDK 版本选择的信息，请参阅 global.json 概述一文中的匹配规则和 rollForward 部分。

目标框架名字对象用于定义生成时 API

针对在“目标框架名字对象”(TFM) 中定义的 API 构建项目。在项目文件中指定目标框架。按如下示例所示，设置项目文件中的 TargetFramework 元素：

<TargetFramework>net8.0</TargetFramework>

可针对多个 TFM 构建项目。对库设置多个目标框架更为常见，但也可对应用程序执行此操作。指定 TargetFrameworks 属性（TargetFramework 的复数形式）。目标框架以分号分隔，如下例所示：

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

给定的 SDK 支持固定的一组框架，其中的上限框架为 SDK 附带的运行时的目标框架。例如，.NET 8 SDK 包含 NET 8 运行时，后者是 net8.0 目标框架的实现。 .NET 8 SDK 支持 net7.0、net6.0 和 net5.0，但不支持 net9.0（或更高版本）。安装 .NET 9 SDK 以对 net9.0 进行生成。

.NET Standard

.NET Standard 是一种面向某个 API 图面的方法，该图面由 .NET 的不同实现所共享。从版本 .NET 5（其本身就是一个 API 标准）开始，就几乎与 .NET Standard 无关了，但一种情况除外：当需要同时面向 .NET 和 .NET Framework 时，.NET Standard 会有用。 .NET 5 实现所有 .NET Standard 版本。

有关详细信息，请参阅 .NET 5 和 .NET Standard。

依赖于框架的应用会前滚

在使用 dotnet run 从源运行应用程序时，在使用 dotnet myapp.dll 从框架相关部署运行应用程序时，或使用 myapp.exe 从框架相关可执行文件运行应用程序时，dotnet 可执行文件是应用程序的主机。

该主机选择计算机上安装的最新修补程序版本。例如，如果在项目文件中指定 net5.0，并且 5.0.2 是安装的最新 .NET 运行时，则使用 5.0.2 运行时。

如果未找到可接受的 5.0.* 版本，则使用新的 5.* 版本。例如，如果指定了 net5.0 并且仅安装了 5.1.0，则应用程序在运行时使用 5.1.0 运行时。此行为称为“次要版本前滚”。此外，不会考虑较低版本。如果未安装可接受的运行时，应用程序将不会运行。

下面几个使用示例展示了在面向版本 5.0 的情况下的此行为：

✔️ 指定了 5.0。 5.0.3 是安装的最高修补程序版本。使用了 5.0.3。
❌ 指定了 5.0。未安装 5.0.* 版本。 3.1.1 是安装的最高运行时版本。会显示一条错误消息。
✔️ 指定了 5.0。未安装 5.0.* 版本。 5.1.0 是安装的最高运行时版本。使用了 5.1.0。
❌ 指定 3.0。未安装 3.x 版本。 5.0.0 是安装的最高运行时版本。会显示一条错误消息。

次要版本回滚会产生一个可能影响最终用户的副作用。请参考以下方案：

应用程序指定需要版本 5.0。
运行时，未安装版本 5.0.*，安装的是 5.1.0。将使用版本 5.1.0。
稍后，用户重新安装 5.0.3 和运行应用程序，而现将使用版本 5.0.3。

5\.0.3 和 5.1.0 可能具有不同行为，序列化二进制数据等方案中尤其如此。

控制前滚行为

在重写默认前滚行为之前，请先熟悉 .NET 运行时兼容性级别。

可通过四种不同的方式配置应用程序的前滚行为：

通过设置 <RollForward> 属性来进行项目级设置：

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

*.runtimeconfig.json 文件。

编译应用程序时，将生成此文件。如果项目中设置了 <RollForward> 属性，*.runtimeconfig.json 文件中会将重新生成为设置 rollForward。用户可以编辑此文件以更改应用程序的行为。
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```

dotnet 命令的 --roll-forward <value> 属性。

运行应用程序时，可以通过命令行控制前滚行为：

dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

DOTNET_ROLL_FORWARD 环境变量。

优先级

运行应用时，前滚行为按以下顺序设置，编号较高的项优先于编号较低的项：

首先计算 *.runtimeconfig.json 配置文件。
接下来，考虑 DOTNET_ROLL_FORWARD 环境变量，替代前面的检查。
最后，传递给正在运行的应用程序的任何 --roll-forward 参数将替代其他所有内容。

值

无论采用什么前滚设置，请使用下列值之一设置该行为：

值	说明
`Minor`	如果未指定，则为默认值。如果缺少所请求的次要版本，则前滚到最低的较高次要版本。如果存在所请求的次要版本，则使用 `LatestPatch` 策略。
`Major`	如果缺少所请求的主要版本，则前滚到下一个可用的更高主要版本和最低的次要版本。如果存在所请求的主要版本，则使用 `Minor` 策略。
`LatestPatch`	前滚到最高补丁版本。此值会禁用次要版本前滚。
`LatestMinor`	即使存在所请求的次要版本，仍前滚到最高次要版本。
`LatestMajor`	即使存在所请求的主要版本，仍前滚到最高主要版本和最高次要版本。
`Disable`	不要前滚，仅绑定到指定的版本。建议不要将此策略用于一般用途，因为它会禁用前滚到最新补丁的功能。该值仅建议用于测试。

独立部署包括所选的运行时

可以将应用程序作为独立分发进行发布。这种方法将 .NET 运行时和库捆绑到应用程序。独立部署不具有对运行时环境的依赖关系。在发布时（而不是运行时）选择运行时版本。

当发布选择了给定运行时系列的最新修补程序版本时所发生的“还原”事件。例如，如果 .NET 5.0.3 是 .NET 5 运行时系列中的最新修补程序版本，dotnet publish 将选择该版本。目标框架（包括最新安装的安全修补程序）与应用程序捆绑打包。

如果为应用程序指定的最小版本不满足要求，会出现错误。 dotnet publish 绑定到最新的运行时修补程序版本（在给定的主要及次要版本系列内）。 dotnet publish 不支持 dotnet run 的前滚语义。若要详细了解补丁和独立式部署，请参阅关于在部署 .NET 应用程序时选择运行时补丁的文章。

独立部署可能需要特定修补程序版本。可以重写项目文件中的最低运行时修补程序版本（重写为更高或更低版本），如下例所示：

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

RuntimeFrameworkVersion 元素重写默认版本策略。对于独立部署，RuntimeFrameworkVersion 指定确切的运行时框架版本。对于依赖于框架的应用程序，RuntimeFrameworkVersion 指定所需的最低运行时框架版本。

通过