global.json 概述

本文适用于： ✔️ .NET Core 3.1 SDK 及更高版本

通过 global.json 文件，可定义在运行 .NET CLI 命令时使用的 .NET SDK 版本。 选择 .NET SDK 版本与指定项目所面向的运行时版本无关。 .NET SDK 版本指示使用哪个版本的 .NET CLI。 本文介绍如何使用 global.json 选择 SDK 版本。

如果始终想要使用计算机上安装的最新 SDK 版本，则不需要 global.json 文件。 但在 CI（持续集成）方案中，通常需要为使用的 SDK 版本指定可接受的范围。 global.json 文件具有 rollForward 功能，它提供灵活的方法来指定可接受的版本范围。 例如，以下 global.json 文件为计算机上安装的 6.0 选择 6.0.300 或更高版本的功能区段或修补程序：

{
  "sdk": {
    "version": "6.0.300",
    "rollForward": "latestFeature"
  }
}

.NET SDK 在当前工作目录（不必与项目目录相同）或其某个父目录中查找 global.json 文件。

有关指定运行时版本而不是 SDK 版本的信息，请参阅目标框架。

global.json 架构

SDK

类型：object

指定要选择的 .NET SDK 的相关信息。

version

• 类型：string

要使用的 .NET SDK 版本。

此字段：

• 不支持通配符，也就是说，必须指定完整版本号。
• 不支持版本范围。

allowPrerelease

• 类型：boolean
• 自 .NET Core 3.0 SDK 起可用。

指示在选择要使用的 SDK 版本时，SDK 解析程序是否应考虑预发布版本。

如果未显式设置此值，则默认值将取决于是否从 Visual Studio 运行：

• 如果未使用 Visual Studio，则默认值为 true。
• 如果使用 Visual Studio，它将使用请求的预发布状态。 也就是说，如果使用 Visual Studio 的预览版本，或者设置了“使用 .NET Core SDK 的预览版”选项（在“工具”>“选项”>“环境”>“预览功能”下方），则默认值为 true 。 否则，默认值为 false。

rollForward

• 类型：string
• 自 .NET Core 3.0 SDK 起可用。

选择 SDK 版本时要使用的前滚策略，可作为特定 SDK 版本缺失时的回退，或者作为使用更高版本的指令。 必须使用 rollForward 值指定版本，除非将其设置为 latestMajor。 默认的前滚行为由匹配规则确定。

要了解可用策略及其行为，请考虑以下格式为 x.y.znn 的 SDK 版本定义：

• x 是主版本。
• y 是次版本。
• z 是功能区段。
• nn 是修补程序版本。

下表列出了 rollForward 键的可能值：

“值”	行为
patch	使用指定的版本。 如果找不到，则前滚到最新的修补程序级别。 如果找不到，则失败。 此值是早期 SDK 版本中的旧行为。
feature	对指定的主版本、次版本和功能区段使用最新的修补程序级别。 如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则失败。
minor	对指定的主版本、次版本和功能区段使用最新的修补程序级别。 如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则前滚到同一主版本中的下一个较高次版本和功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则失败。
major	对指定的主版本、次版本和功能区段使用最新的修补程序级别。 如果找不到，则前滚到同一主/次版本中的下一个较高功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则前滚到同一主版本中的下一个较高次版本和功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则前滚到下一个较高主版本、次版本和功能区段，并使用该功能区段的最新修补程序级别。 如果找不到，则失败。
latestPatch	使用安装的最新修补程序级别，该级别与请求的主版本、次版本和功能区段匹配，并且该修补程序级别大于或等于指定的值。 如果找不到，则失败。
latestFeature	使用安装的最高功能区段和修补程序级别，其与请求的主版本和次版本匹配，并且该功能区段和修补级别大于或等于指定的值。 如果找不到，则失败。
latestMinor	使用安装的最高次版本、功能区段和修补程序级别，其与请求的主版本匹配，并且该次版本、功能区段和修补级别大于或等于指定的值。 如果找不到，则失败。
latestMajor	使用安装的最高版本的 .NET SDK，并且该版本大于或等于指定的值。 如果找不到，则失败。
disable	不前滚。 必须完全匹配。

msbuild-sdks

类型：object

可便于在一个位置（而不是在各个项目中）控制项目 SDK 版本。 有关详细信息，请参阅如何解析项目 SDK。

global.json 中的注释

global.json 文件中的注释支持使用 JavaScript 或 C# 样式的注释。 例如：

{
   // This is a comment.
  "sdk": {
    "version": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

示例

下面的示例演示如何不使用预发布版本：

{
  "sdk": {
    "allowPrerelease": false
  }
}

下面的示例展示了如何使用安装的最高版本，此版本大于或等于指定的版本。 所示的 JSON 不允许任何低于 2.2.200 的 SDK 版本，而允许 2.2.200 或任何更高版本（包括 3.0.xxx 和 3.1.xxx）。

{
  "sdk": {
    "version": "2.2.200",
    "rollForward": "latestMajor"
  }
}

下面的示例演示如何使用完全指定的版本：

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

下面的示例展示了如何使用特定主要版本和次要版本的已安装最新功能区段和修补程序版本。 所示的 JSON 不允许任何低于 3.1.102 的 SDK 版本，而允许 3.1.102 或任何更高的 3.1.xxx 版本（如 3.1.103 或 3.1.200）。

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestFeature"
  }
}

下面的示例展示了如何使用特定版本的已安装最高修补程序版本。 所示的 JSON 不允许任何低于 3.1.102 的 SDK 版本，而允许 3.1.102 或任何更高的 3.1.1xx 版本（如 3.1.103 或 3.1.199）。

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestPatch"
  }
}

global.json 和 .NET CLI

若要在 global.json 文件中设置 SDK 版本，最好能知道计算机上安装了哪些 SDK 版本。 有关如何执行此操作的详细信息，请参阅如何检查是否已安装 .NET。

若要在计算机上安装其他 .NET SDK 版本，请访问下载 .NET 页面。

可执行 dotnet new 命令，在当前目录中创建一个新的 global.json 文件，如下例所示：

dotnet new globaljson --sdk-version 6.0.100

匹配规则

注意

匹配规则由 dotnet.exe 入口点控制，该入口点在所有已安装的 .NET 运行时中很常见。 如果并行安装了多个运行时，或者正在使用 global.json 文件，则使用已安装的最新版 .NET 运行时的匹配规则。

在确定要使用的 SDK 版本时，以下规则适用：

• 如果未找到 global.json 文件，或者 global.json 未指定 SDK 版本和 allowPrerelease 值，则使用安装的最高 SDK 版本（相当于将 rollForward 设置为 latestMajor） 。 是否考虑 SDK 预发布版本取决于 dotnet 的调用方式：

  • 如果未使用 Visual Studio，则考虑预发布版本。
  • 如果使用 Visual Studio，它将使用请求的预发布状态。 也就是说，如果使用 Visual Studio 的预览版本，或者设置了“使用 .NET SDK 的预览版”选项（在“工具”>“选项”>“环境”>“预览功能”下方），则考虑预发布版本；否则仅考虑发布版本 。

• 如果找到了未指定 SDK 版本但指定了 allowPrerelease 值的 global.json 文件，则使用安装的最高 SDK 版本（相当于将 rollForward 设置为 latestMajor）。 最新 SDK 版本是发布版本还是预发布版本取决于 allowPrerelease 的值。 true 指示考虑预发布版本；false 指示仅考虑发布版本。

• 如果找到 global.json 文件，并且该文件指定了 SDK 版本：

  • 如果未设置 rollForward 值，它将使用 latestPatch 作为默认 rollForward 策略。 否则，请在 rollForward 部分中检查每个值及其行为。
  • 有关是否考虑预发布版本以及未设置 allowPrerelease 时的默认行为的信息，请参阅 allowPrerelease 部分。

针对生成警告的疑难解答

• 以下警告指示你的项目使用 .NET SDK 的预发布版本进行编译：

  使用的是 .NET Core SDK 的预览版本， 可通过当前项目中的 global.json 文件定义 SDK 版本。 有关详细信息，请访问 https://go.microsoft.com/fwlink/?linkid=869452。

  你正在使用的是 .NET 预览版。 请参阅：https://aka.ms/dotnet-core-preview

  .NET SDK 的各种版本均品质优良稳定，在业内口碑良好。 但是，如果不希望使用预发布版本，请在 allowPrerelease 部分中查看可以使用的各种策略。 对于从未安装 .NET Core 3.0 或更高版本运行时或 SDK 的计算机，需要创建一个 global.json 文件，并指定要使用的确切版本。

• 以下警告指示项目面向 EF Core 1.0 或 1.1，后者与 .NET Core 2.1 SDK 及更高版本不兼容：

  启动项目 '{startupProject}' 面向框架 '.NETCoreApp' 的版本 '{targetFrameworkVersion}'。 此版本的 Entity Framework Core .NET 命令行工具仅支持 2.0 或更高版本。 有关使用旧版工具的信息，请参阅 https://go.microsoft.com/fwlink/?linkid=871254。

  从 .NET Core 2.1 SDK（版本 2.1.300）开始，SDK 中包含 dotnet ef 命令。 若要编译项目，请在计算机上安装 .NET Core 2.0 SDK（版本 2.1.201）或更早版本，并使用 global.json 文件定义所需 SDK 版本。 有关 dotnet ef 命令的详细信息，请参阅 EF Core .NET 命令行工具。

• 如果使用 global.json 保留特定版本的 .NET SDK，请注意，Visual Studio 仅安装 .NET SDK 的单个副本。 因此，如果升级 Visual Studio 版本，它将删除用于安装新版本的 .NET SDK 的以前版本。 即使旧版本是不同的主 .NET 版本，它也会删除旧版本。

为了避免 Visual Studio 删除 .NET SDK 的版本，需要从下载页安装单独的 .NET SDK。 请注意，如果这样做，则不再通过 Visual Studio 获取对该 .NET SDK 版本的自动更新，并可能面临安全问题的风险。

另请参阅

• 如何解析 SDK 项目