Обзор global.jsonglobal.json overview

Эта статья относится к следующему. ✔️ SDK для .NET Core 2.0 и более поздних версийThis article applies to: ✔️ .NET Core 2.0 SDK and later versions

С помощью файла global.json можно определить, какая версия пакета SDK для .NET Core используется при выполнении команд .NET Core CLI.The global.json file allows you to define which .NET Core SDK version is used when you run .NET Core CLI commands. Выбор пакета SDK для .NET Core не зависит от указания целевой среды выполнения проекта.Selecting the .NET Core SDK is independent from specifying the runtime your project targets. Версия пакета SDK для .NET Core указывает, какие версии .NET Core CLI используются.The .NET Core SDK version indicates which versions of the .NET Core CLI is used.

Как правило, необходимо использовать последнюю версию средств пакета SDK, поэтому вам нужен файл global.json.In general, you want to use the latest version of the SDK tools, so no global.json file is needed. В некоторых сложных сценариях может потребоваться управление версией средств пакета SDK, и в этой статье объясняется, как это сделать.In some advanced scenarios, you might want to control the version of the SDK tools, and this article explains how to do this.

Дополнительные сведения о том, как вместо этого указать среду выполнения, см. в разделе Целевые платформы.For more information about specifying the runtime instead, see Target frameworks.

Пакет SDK для .NET Core ищет файл global.json в текущем рабочем каталоге (который не обязательно совпадает с каталогом проекта) или в одном из его родительских каталогов..NET Core SDK looks for a global.json file in the current working directory (which isn't necessarily the same as the project directory) or one of its parent directories.

Схема файла global.jsonglobal.json schema

sdksdk

Тип: objectType: object

Указывает сведения о пакете SDK для .NET Core для выбора.Specifies information about the .NET Core SDK to select.

versionversion

  • Тип: stringType: string

  • Доступно начиная с пакета SDK для .NET Core 1.0.Available since: .NET Core 1.0 SDK.

Версия пакета SDK для .NET Core для использования.The version of the .NET Core SDK to use.

Это поле:This field:

  • Не поддерживает подстановочные знаки, то есть необходимо указать полный номер версии.Doesn't have wildcard support, that is, the full version number has to be specified.
  • Не поддерживает диапазон версий.Doesn't support version ranges.

allowPrereleaseallowPrerelease

  • Тип: booleanType: boolean

  • Доступно начиная с пакета SDK для .NET Core 3.0.Available since: .NET Core 3.0 SDK.

Указывает, должен ли сопоставитель пакетов SDK учитывать предварительные версии при выборе версии пакета SDK, которую следует использовать.Indicates whether the SDK resolver should consider prerelease versions when selecting the SDK version to use.

Если это значение не задано явно, значение по умолчанию зависит от того, работаете ли вы в Visual Studio:If you don't set this value explicitly, the default value depends on whether you're running from Visual Studio:

  • Если вы не работаете в Visual Studio, значение по умолчанию — true.If you're not in Visual Studio, the default value is true.
  • Если работаете в Visual Studio, используется запрошенное состояние предварительной версии.If you are in Visual Studio, it uses the prerelease status requested. То есть если вы используете предварительную версию Visual Studio или включили параметр Использовать предварительные версии пакета SDK для .NET Core (в разделе Сервис > Параметры > Среда > Функции предварительной версии), значением по умолчанию будет true; в противном случае — false.That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), the default value is true; otherwise, false.

rollForwardrollForward

  • Тип: stringType: string

  • Доступно начиная с пакета SDK для .NET Core 3.0.Available since: .NET Core 3.0 SDK.

Политика наката, используемая при выборе версии пакета SDK (либо в качестве резервной, если определенная версия пакета SDK отсутствует, либо в качестве директивы для использования более поздней версии).The roll-forward policy to use when selecting an SDK version, either as a fallback when a specific SDK version is missing or as a directive to use a higher version. Версия должна быть указана со значением rollForward, если только вы не настраиваете ее равной latestMajor.A version must be specified with a rollForward value, unless you're setting it to latestMajor.

Для понимания доступных политик и их поведения примите во внимание следующие определения для версии пакета SDK в формате x.y.znn:To understand the available policies and their behavior, consider the following definitions for an SDK version in the format x.y.znn:

  • x — основной номер версии.x is the major version.
  • y — дополнительный номер версии.y is the minor version.
  • z — набор возможностей.z is the feature band.
  • nn — версия исправления.nn is the patch version.

В следующей таблице описаны возможные значения параметра rollForward.The following table shows the possible values for the rollForward key:

ЗначениеValue ПоведениеBehavior
patch Использует указанную версию.Uses the specified version.
Если не найдено, выполняет накат до последнего уровня обновления.If not found, rolls forward to the latest patch level.
Если не найдено, происходит сбой.If not found, fails.

Это значение является устаревшим поведением по сравнению с предыдущими версиями пакета SDK.This value is the legacy behavior from the earlier versions of the SDK.
feature Использует последний уровень обновления для указанного основного номера версии, дополнительного номера версии и набора возможностей.Uses the latest patch level for the specified major, minor, and feature band.
Если не найдено, выполняет накат до следующего набора возможностей более высокого уровня в пределах одного и того же основного или дополнительного номера версии и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher feature band within the same major/minor and uses the latest patch level for that feature band.
Если не найдено, происходит сбой.If not found, fails.
minor Использует последний уровень обновления для указанного основного номера версии, дополнительного номера версии и набора возможностей.Uses the latest patch level for the specified major, minor, and feature band.
Если не найдено, выполняет накат до следующего набора возможностей более высокого уровня в пределах одного и того же основного или дополнительного номера версии и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
Если не найдено, выполняет накат до следующего основного номера версии и набора возможностей более высокого уровня в пределах одного и того же основного номера версии и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
Если не найдено, происходит сбой.If not found, fails.
major Использует последний уровень обновления для указанного основного номера версии, дополнительного номера версии и набора возможностей.Uses the latest patch level for the specified major, minor, and feature band.
Если не найдено, выполняет накат до следующего набора возможностей более высокого уровня в пределах одного и того же основного или дополнительного номера версии и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher feature band within the same major/minor version and uses the latest patch level for that feature band.
Если не найдено, выполняет накат до следующего основного номера версии и набора возможностей более высокого уровня в пределах одного и того же основного номера версии и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher minor and feature band within the same major and uses the latest patch level for that feature band.
Если не найдено, выполняет накат до следующего основного номера версии, дополнительного номера версии и набора возможностей более высокого уровня и использует последний уровень обновления для этого набора возможностей.If not found, rolls forward to the next higher major, minor, and feature band and uses the latest patch level for that feature band.
Если не найдено, происходит сбой.If not found, fails.
latestPatch Использует последний установленный уровень обновления, соответствующий запрошенному основному номеру версии, дополнительному номеру версии и набору возможностей с уровнем обновления, который соответствует указанному значению или превышает его.Uses the latest installed patch level that matches the requested major, minor, and feature band with a patch level and that is greater or equal than the specified value.
Если не найдено, происходит сбой.If not found, fails.
latestFeature Использует наивысший установленный набор возможностей и уровень обновления, соответствующий запрошенному основному номеру версии и дополнительному номеру версии с набором возможностей, который соответствует указанному значению или превышает его.Uses the highest installed feature band and patch level that matches the requested major and minor with a feature band that is greater or equal than the specified value.
Если не найдено, происходит сбой.If not found, fails.
latestMinor Использует наивысший установленный основной номер версии, набор возможностей и уровень обновления, соответствующий запрошенному основному номеру версии с дополнительным номером версии, который соответствует указанному значению или превышает его.Uses the highest installed minor, feature band, and patch level that matches the requested major with a minor that is greater or equal than the specified value.
Если не найдено, происходит сбой.If not found, fails.
latestMajor Использует наивысший установленный пакет SDK для .NET Core с основным номером версии, который соответствует указанному значению или превышает его.Uses the highest installed .NET Core SDK with a major that is greater or equal than the specified value.
Если не найдено, происходит сбой.If not found, fail.
disable Накат не выполняется.Doesn't roll forward. Требуется точное соответствие.Exact match required.

msbuild-sdksmsbuild-sdks

Тип: objectType: object

Позволяет управлять версией пакета SDK для проекта в одном месте, а не в отдельном проекте.Lets you control the project SDK version in one place rather than in each individual project. Дополнительные сведения см. в статье Как разрешаются ссылки на пакеты SDK проекта.For more information, see How project SDKs are resolved.

ПримерыExamples

В следующем примере показано, как не использовать предварительные версии:The following example shows how to not use prerelease versions:

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

В следующем примере показано, как использовать наивысший установленный номер версии, который соответствует указанной версии или больше нее.The following example shows how to use the highest version installed that is greater or equal than the specified version. Показанный JSON не позволяет использовать версию пакета SDK до 2.2.200 и разрешает 2.2.200 или любую более позднюю версию, включая 3.0.xxx и 3.1.xxx.The JSON shown disallows any SDK version earlier than 2.2.200 and allows 2.2.200 or any later version, including 3.0.xxx and 3.1.xxx.

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

В следующем примере показано, как использовать точную указанную версию:The following example shows how to use the exact specified version:

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

В следующем примере показано, как использовать последнюю версию набора возможностей и обновления, установленную для конкретных основной и дополнительной версий.The following example shows how to use the latest feature band and patch version installed of a specific major and minor version. Показанный JSON не позволяет использовать версию пакета SDK до 3.1.102 и разрешает 3.1.102 или любую более позднюю версию 3.1.xxx, например 3.1.103 или 3.1.200.The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.xxx version, such as 3.1.103 or 3.1.200.

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

В следующем примере показано, как использовать наивысшую версию обновления, установленную для конкретной версии.The following example shows how to use the highest patch version installed of a specific version. Показанный JSON не позволяет использовать версию пакета SDK до 3.1.102 и разрешает 3.1.102 или любую более позднюю версию 3.1.1xx, например 3.1.103 или 3.1.199.The JSON shown disallows any SDK version earlier than 3.1.102 and allows 3.1.102 or any later 3.1.1xx version, such as 3.1.103 or 3.1.199.

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

global.json и .NET Core CLIglobal.json and the .NET Core CLI

Полезно знать, какие версии пакета SDK установлены на компьютере, чтобы задать их в файле global.json.It's helpful to know which SDK versions are installed on your machine to set one in the global.json file. Дополнительные сведения о том, как это сделать, см. в разделе Проверка того, установлена ли платформа .NET Core.For more information on how to do that, see How to check that .NET Core is already installed.

Чтобы установить дополнительные версии пакета SDK для .NET Core на компьютере, посетите страницу скачиваемых файлов .NET Core.To install additional .NET Core SDK versions on your machine, visit the Download .NET Core page.

Вы можете создать новый файл global.json в текущем каталоге, выполнив команду dotnet new, как в следующем примере:You can create a new the global.json file in the current directory by executing the dotnet new command, similar to the following example:

dotnet new globaljson --sdk-version 3.0.100

Правила сопоставленияMatching rules

Примечание

Правила сопоставления определяются точкой входа dotnet.exe, которая является общей для всех установленных сред выполнения .NET Core.The matching rules are governed by the dotnet.exe entry point, which is common across all installed .NET Core installed runtimes. Правила сопоставления для последней установленной версии среды выполнения .NET Core используются при параллельной установке сразу нескольких сред выполнения.The matching rules for the latest installed version of the .NET Core Runtime are used when you have multiple runtimes installed side-by-side.

Начиная с .NET Core 3.0 при определении версии пакета SDK для использования применяются следующие правила:Starting with .NET Core 3.0, the following rules apply when determining which version of the SDK to use:

  • Если файл global.json не найден или в файле global.json не указаны версия пакета SDK или значение allowPrerelease, используется наивысшая версия пакета SDK (эквивалентная заданию значения rollForward для параметра latestMajor).If no global.json file is found, or global.json doesn't specify an SDK version nor an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). Необходимость учитывать предварительные версии пакета SDK зависит от того, как вызывается dotnet.Whether prerelease SDK versions are considered depends on how dotnet is being invoked.

    • Если вы не работаете в Visual Studio, учитываются предварительные версии.If you're not in Visual Studio, prerelease versions are considered.
    • Если работаете в Visual Studio, используется запрошенное состояние предварительной версии.If you are in Visual Studio, it uses the prerelease status requested. То есть если вы используете предварительную версию Visual Studio или включили параметр Использовать предварительные версии пакета SDK для .NET Core (в разделе Сервис > Параметры > Среда > Функции предварительной версии), учитываются предварительные версии; в противном случае учитываются только выпущенные версии.That is, if you're using a Preview version of Visual Studio or you set the Use previews of the .NET Core SDK option (under Tools > Options > Environment > Preview Features), prerelease versions are considered; otherwise, only release versions are considered.
  • Если найден файл global.json, в котором не указана версия пакета SDK, но указано значение allowPrerelease, используется наивысшая версия пакета SDK (аналогично заданию значения rollForward для параметра latestMajor).If a global.json file is found that doesn't specify an SDK version but it specifies an allowPrerelease value, the highest installed SDK version is used (equivalent to setting rollForward to latestMajor). На то, может ли последняя версия пакета SDK выпускаться или быть предварительным выпуском, влияет значение allowPrerelease.Whether the latest SDK version can be release or prerelease depends on the value of allowPrerelease. true указывает на то, что предварительные версии учитываются. false указывает на то, что учитываются только выпущенные версии.true indicates prerelease versions are considered; false indicates that only release versions are considered.

  • Если файл global.json найден и в нем указана версия пакета SDK:If a global.json file is found and it specifies an SDK version:

    • Если значение rollFoward не задано, в качестве политики rollForward по умолчанию используется latestPatch.If no rollFoward value is set, it uses latestPatch as the default rollForward policy. В противном случае проверьте каждое значение и их поведение в разделе rollForward.Otherwise, check each value and their behavior in the rollForward section.
    • Сведения о том, учитываются ли предварительные версии и каково поведение по умолчанию, если параметр allowPrerelease не задан, представлены в разделе allowPrerelease.Whether prerelease versions are considered and what's the default behavior when allowPrerelease isn't set is described in the allowPrerelease section.

Устранение неполадок с предупреждениями сборкиTroubleshoot build warnings

  • Следующее предупреждение означает, что проект был скомпилирован с использованием предварительной версии пакета SDK для .NET Core:The following warning indicates that your project was compiled using a prerelease version of the .NET Core SDK:

    Вы работаете с предварительной версией пакета SDK для .NET Core.You are working with a preview version of the .NET Core SDK. Версию пакета SDK можно указать в файле global.json в текущем проекте.You can define the SDK version via a global.json file in the current project. Дополнительные сведения см. на странице https://go.microsoft.com/fwlink/?linkid=869452.More at https://go.microsoft.com/fwlink/?linkid=869452.

    Версии пакета SDK для .NET Core имеют гарантированное качество..NET Core SDK versions have a history and commitment of being high quality. Однако если вы не хотите использовать предварительную версию, ознакомьтесь с различными стратегиями, которые можно применять в отношении пакета SDK для .NET Core 3.0 или более поздней версии, обратившись к разделу allowPrerelease.However, if you don't want to use a prerelease version, check the different strategies you can use with the .NET Core 3.0 SDK or a later version in the allowPrerelease section. Для компьютеров, на которые никогда не устанавливалась среда выполнения .NET Core 3.0 или более поздней версии или пакет SDK, необходимо создать файл global.json и указать точную версию, которую требуется использовать.For machines that have never had a .NET Core 3.0 or higher Runtime or SDK installed, you need to create a global.json file and specify the exact version you want to use.

  • Следующее предупреждение означает, что проект предназначен для EF Core 1.0 или 1.1, которые несовместимы с пакетом SDK для .NET Core 2.1 и более поздних версий:The following warning indicates that your project targets EF Core 1.0 or 1.1, which isn't compatible with .NET Core 2.1 SDK and later versions:

    Запускаемый проект '{startupProject}' нацелен на версию платформы '.NETCoreApp' '{targetFrameworkVersion}'.Startup project '{startupProject}' targets framework '.NETCoreApp' version '{targetFrameworkVersion}'. Эта версия средств командной строки .NET Entity Framework Core поддерживает только версию 2.0 или более позднюю.This version of the Entity Framework Core .NET Command-line Tools only supports version 2.0 or higher. Сведения об использовании более старой версии средств см. на странице https://go.microsoft.com/fwlink/?linkid=871254.For information on using older versions of the tools, see https://go.microsoft.com/fwlink/?linkid=871254.

    Начиная с пакета SDK для .NET Core 2.1 (версия 2.1.300) поддерживается команда dotnet ef.Starting with .NET Core 2.1 SDK (version 2.1.300), the dotnet ef command comes included in the SDK. Чтобы скомпилировать проект, установите пакет SDK для .NET Core 2.0 (версия 2.1.201) или более ранней версии на своем компьютере и определите необходимую версию пакета SDK с помощью файла global.json.To compile your project, install .NET Core 2.0 SDK (version 2.1.201) or earlier on your machine and define the desired SDK version using the global.json file. Дополнительные сведения о команде dotnet ef см. в разделе Утилиты командной строки для EF Core .NET.For more information about the dotnet ef command, see EF Core .NET Command-line Tools.

См. такжеSee also