选择要使用的 .NET 版本

项目
02/10/2025

本文介绍 .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 可以放置在文件层次结构中的任意位置。你可以通过其在文件系统中的位置来控制给定 global.json 所应用到的项目。 .NET CLI 从当前工作目录路径向上导航，以迭代方式搜索 global.json 文件（不一定与项目目录相同）。找到的第一个 global.json 文件指定使用的版本。如果安装了该 SDK 版本，则使用该版本。如果未找到 global.json 中指定的 SDK，则 .NET CLI 使用匹配的规则选择兼容的 SDK，如果未找到任何 SDK，则失败。

以下示例显示了 global.json 语法：

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

选择 SDK 版本的过程为：

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

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

更新 SDK 版本

请务必定期更新到最新版本的 SDK，以采用最新的功能、性能改进和 bug 修复。若要轻松检查 SDK 的更新，请使用 dotnet sdk check命令。此外，如果使用 global.json选择特定版本，请考虑使用 Dependabot 等工具在新版本可用时自动更新固定的 SDK 版本。

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

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

<TargetFramework>net8.0</TargetFramework>

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

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

给定的 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 是一种以 .NET 的不同实现共享的 API 图面为目标的方法。从 .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 绑定到最新的运行时修补程序版本（在给定的 major.minor 版本系列内）。 dotnet publish 不支持 dotnet run 的前滚语义。有关修补程序和独立部署的详细信息，请参阅有关部署 .NET 应用程序中运行时修补程序选择的文章。

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

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

RuntimeFrameworkVersion 元素将替代默认版本策略。对于独立部署，RuntimeFrameworkVersion 指定具体运行时框架版本。对于依赖框架的应用程序，RuntimeFrameworkVersion 指定所需的运行时框架版本最低。

通过