global.json 概述

该global.json文件允许您定义.NET SDK版本，当您运行.NET CLI命令时使用。选择 .NET SDK 与指定项目目标运行时无关。.NET SDK 版本指示使用的 .NET CLI 版本。 一般情况下，您希望使用最新版本的 SDK 工具，因此不需要global.json文件。在一些高级场景中，您可能希望控制 SDK 工具的版本，本文将解释如何做到这一点。 有关改为指定运行时的更多信息，请参阅目标框架。 .NET SDK在当前工作目录（不一定与项目目录相同）或其父目录之一中查找global.json文件。 global.json 模式 软件开发工具包 类型： object 指定有关要选择的 .NET SDK 的信息。 版本 类型： string 要使用的 .NET SDK 的版本。 这个领域： 不支持通配符；也就是说，您必须指定完整的版本号。 不支持版本范围。 允许预发行 类型： boolean 从以下版本可用：.NET Core 3.0 SDK。 指示 SDK 解析器在选择要使用的 SDK 版本时是否应考虑预发布版本。 如果未明确设置此值，则默认值取决于您是否从 Visual Studio 运行： 如果您不在Visual Studio 中，则默认值为true. 如果您在 Visual Studio 中，它会使用请求的预发布状态。也就是说，如果您使用的是 Visual Studio 的预览版，或者您设置了使用 .NET SDK 的预览选项（在工具>选项>环境>预览功能下），则默认值为true。否则，默认值为false。 前滚 类型： string 从以下版本可用：.NET Core 3.0 SDK。 选择 SDK 版本时使用的前滚策略，作为缺少特定 SDK 版本时的回退或作为使用更高版本的指令。一个版本必须与指定rollForward值，除非你将其设置为latestMajor。默认前滚行为由匹配规则决定。 要了解可用的策略及其行为，请考虑以下格式的 SDK 版本定义x.y.znn： x 是主要版本。 y 是次要版本。 z 是特征带。 nn 是补丁版本。 下表显示了rollForward键的可能值： 表格1 价值 行为 patch 使用指定的版本。 如果未找到，则前滚到最新的补丁级别。 如果找不到，则失败。 此值是早期版本的 SDK 的旧行为。 feature 对指定的主要、次要和功能带使用最新的补丁级别。 如果未找到，则前滚到同一大调/小调中的下一个更高的功能带，并使用该功能带的最新补丁级别。 如果找不到，则失败。 minor 对指定的主要、次要和功能带使用最新的补丁级别。 如果未找到，则前滚到同一主要/次要版本中的下一个更高的功能带，并使用该功能带的最新补丁级别。 如果未找到，则前滚到同一大调内的下一个更高的小调和功能带，并使用该功能带的最新补丁级别。 如果找不到，则失败。 major 对指定的主要、次要和功能带使用最新的补丁级别。 如果未找到，则前滚到同一主要/次要版本中的下一个更高的功能带，并使用该功能带的最新补丁级别。 如果未找到，则前滚到同一大调内的下一个更高的小调和功能带，并使用该功能带的最新补丁级别。 如果未找到，则前滚到下一个更高的主要、次要和功能带，并使用该功能带的最新补丁级别。 如果找不到，则失败。 latestPatch 使用最新安装的补丁级别，该补丁级别与请求的主要、次要和功能带与补丁级别相匹配，并且大于或等于指定的值。 如果找不到，则失败。 latestFeature 使用与请求的主要和次要功能区和补丁程序级别大于或等于指定值相匹配的最高已安装功能区和补丁程序级别。 如果找不到，则失败。 latestMinor 使用与请求的主版本相匹配的最高安装次版本、功能区域和补丁级别，并且次版本、功能区域和补丁级别大于或等于指定的值。 如果找不到，则失败。 latestMajor 使用版本高于或等于指定值的最高安装 .NET SDK。 如果找不到，则失败。 disable 不向前滚动。需要完全匹配。 msbuild-sdks 类型： object 让您可以在一个地方而不是在每个单独的项目中控制项目 SDK 版本。有关更多信息，请参阅如何解决项目 SDK。 例子 以下示例显示了如何不使用预发布版本： JSON 复制 { "sdk": { "allowPrerelease": false } } 以下示例显示如何使用安装的高于或等于指定版本的最高版本。显示的 JSON 不允许早于 2.2.200 的任何 SDK 版本，并允许 2.2.200 或任何更高版本，包括 3.0.xxx 和 3.1.xxx。 JSON 复制 { "sdk": { "version": "2.2.200", "rollForward": "latestMajor" } } 以下示例显示了如何使用确切指定的版本： JSON 复制 { "sdk": { "version": "3.1.100", "rollForward": "disable" } } 以下示例显示了如何使用特定主要和次要版本的最新功能带和补丁版本。显示的 JSON 不允许早于 3.1.102 的任何 SDK 版本，并允许 3.1.102 或任何更高的 3.1.xxx 版本，例如 3.1.103 或 3.1.200。 JSON 复制 { "sdk": { "version": "3.1.102", "rollForward": "latestFeature" } } 下面的例子展示了如何使用特定版本安装的最高补丁版本。显示的 JSON 不允许早于 3.1.102 的任何 SDK 版本，并允许 3.1.102 或任何更高的 3.1.1xx 版本，例如 3.1.103 或 3.1.199。 JSON 复制 { "sdk": { "version": "3.1.102", "rollForward": "latestPatch" } } global.json 和 .NET CLI 要在global.json文件中设置 SDK 版本，了解您的机器上安装了哪些 SDK 版本会很有帮助。有关如何执行此操作的信息，请参阅如何检查 .NET 是否已安装。 要在您的计算机上安装其他 .NET SDK 版本，请访问下载 .NET页面。 您可以通过执行dotnet new命令在当前目录中创建一个新的global.json文件，类似于以下示例： .NET 命令行界面 复制 dotnet new globaljson --sdk-version 6.0.100 匹配规则 笔记 匹配规则由dotnet.exe入口点管理，这在所有已安装的 .NET 安装运行时中是通用的。当您并行安装多个运行时，或者您正在使用global.json文件时，将使用最新安装的 .NET 运行时版本的匹配规则。 .NET Core 3.x 和 .NET 5+ .NET 核心 2.x 从 .NET Core 3.0 开始，在确定要使用的 SDK 版本时适用以下规则： 如果未找到global.json文件，或者global.json未指定 SDK 版本或allowPrerelease值，则使用已安装的最高 SDK 版本（相当于设置rollForward为latestMajor）。是否考虑预发布 SDK 版本取决于dotnet调用方式。 如果您不在Visual Studio 中，则会考虑预发布版本。 如果您在 Visual Studio 中，它会使用请求的预发布状态。也就是说，如果您使用的是 Visual Studio 的预览版本，或者您设置了使用 .NET SDK 的预览选项（在工具>选项>环境>预览功能下），则考虑预发布版本；否则，只考虑发布版本。 如果发现global.json文件未指定 SDK 版本但指定了allowPrerelease值，则使用已安装的最高 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）开始，该dotnet ef命令包含在 SDK 中。要编译您的项目，请在您的计算机上安装 .NET Core 2.0 SDK（版本 2.1.201）或更早版本，并使用global.json文件定义所需的 SDK 版本。有关该dotnet ef命令的详细信息，请参阅EF Core .NET 命令行工具。