Обзор global.json

Статья
2025-04-11

Эта статья относится к: ✔️ пакету SDK для .NET Core 3.1 и более поздних версий

С помощью файла global.json можно определить, какая версия пакета SDK для .NET используется при выполнении команд .NET CLI. Выбор версии пакета SDK для .NET не зависит от указания версии среды выполнения целевых объектов проекта. Версия пакета SDK для .NET указывает, какая версия интерфейса командной строки .NET используется. В этой статье объясняется, как выбрать версию пакета SDK с помощью global.json.

Если вы всегда хотите использовать последнюю версию пакета SDK, установленную на компьютере, файл global.json не требуется. Однако в сценариях непрерывной интеграции CI обычно требуется указать допустимый диапазон для используемой версии пакета SDK. Файл global.json имеет rollForward функцию, которая предоставляет гибкие способы указания допустимого диапазона версий. Например, следующий global.json файл выбирает 8.0.300 или любую более позднюю группу компонентов или исправление для версии 8.0, установленной на компьютере:

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

Пакет SDK для .NET ищет файл global.json в текущем рабочем каталоге (который не обязательно совпадает с каталогом проекта) или в одном из его родительских каталогов.

Сведения об указании версии среды выполнения вместо версии пакета SDK см. в разделе "Целевые платформы".

Схема global.json

SDK

Тип: object

Указывает сведения о пакете SDK для .NET для выбора.

версия

Тип: string

Версия .NET SDK для использования.

Это поле:

Не поддерживает подстановочные знаки, то есть необходимо указать полный номер версии.
Не поддерживает диапазон версий.

разрешитьПредварительныйВыпуск

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

Указывает, должен ли сопоставитель пакетов SDK учитывать предварительные версии при выборе версии пакета SDK, которую следует использовать.

Если это значение не задано явно, значение по умолчанию зависит от того, работаете ли вы в Visual Studio:

Если вы не используете Visual Studio, значение по умолчанию — true.
Если вы находитесь в Visual Studio, он использует запрашиваемое состояние предварительной версии. То есть, если вы используете предварительную версию Visual Studio или включили параметр Использовать предварительные версии пакета SDK для .NET (в разделе Сервис>Параметры>Среда>Функции предварительной версии), значение по умолчанию — true. В противном случае значение по умолчанию — false.

перемотка вперёд

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

Политика продвижения, используемая при выборе версии SDK, либо в качестве резервной опции при отсутствии определенной версии SDK, либо в качестве директивы для использования более поздней версии. Версия должна быть указана со значением rollForward, если только вы не настраиваете ее равной latestMajor. Поведение переката по умолчанию определяется правилами сопоставления.

Для понимания доступных политик и их поведения примите во внимание следующие определения для версии пакета SDK в формате x.y.znn:

x — основная версия.
y — мино́рная версия.
z — группа функций.
nn — версия исправления.

В следующей таблице описаны возможные значения параметра rollForward.

Значение	Поведение
`patch`	Использует указанную версию. Если не найдено, обновляется до последнего патча. Если не найдено, происходит сбой. Это значение является устаревшим поведением по сравнению с предыдущими версиями пакета SDK.
`feature`	Использует последний уровень обновлений для указанных основных и дополнительных версий, а также набора функций. Если не найдено, переходит к следующему набору возможностей более высокого уровня в пределах основной или дополнительной версии и использует последнюю версию для этого набора возможностей. Если не найдено, происходит сбой.
`minor`	Использует последний уровень обновлений для указанных основных и дополнительных версий, а также набора функций. Если не найдено, переходит к следующей более высокой группе функций в пределах той же основной или дополнительной версии и использует последний корректирующий уровень для этой группы функций. Если не найдено, выполняет переход к следующей более высокой минорной версии и версии с дополнительными функциями в пределах той же основной версии и использует последний уровень обновления для этой версии с дополнительными функциями. Если не найдено, происходит сбой.
`major`	Использует последний уровень обновлений для указанных основных и дополнительных версий, а также набора функций. Если не найдено, переходит к следующей более высокой группе функций в пределах той же основной или дополнительной версии и использует последний корректирующий уровень для этой группы функций. Если не найдено, выполняет переход к следующей более высокой минорной версии и версии с дополнительными функциями в пределах той же основной версии и использует последний уровень обновления для этой версии с дополнительными функциями. Если не найдено, выполняет переход к следующей основной версии, минорной версии и более высокого уровня набору возможностей и использует последний патч-уровень для этого набора возможностей. Если не найдено, происходит сбой.
`latestPatch`	Использует последний установленный уровень патчей, соответствующий запрошенной основной, минорной и функциональной группе с уровнем патчей, превышающим или равным указанному значению. Если не найдено, происходит сбой.
`latestFeature`	Использует наивысший установленный диапазон функций и уровень исправлений, соответствующий запрошенным основному и дополнительному, с функциональной группой и уровнем исправлений, превышающим или равным указанному значению. Если не найдено, происходит сбой.
`latestMinor`	Использует самую высокую установленную младшую версию, release-область и уровень патча, которые соответствуют запрошенной основной версии, имея младшую версию, release-область и уровень патча, превышающие или равные указанному значению. Если не найдено, происходит сбой.
`latestMajor`	Использует самый высокий установленный пакет SDK для .NET с версией, превышающей указанное значение или равное ей. Если не найдено, происходит сбой.
`disable`	Не движется вперед. Требуется точное совпадение.

Пути

Тип: массив string
Доступно с момента: пакет SDK для .NET 10 ( предварительная версия 3).

Указывает расположения, которые следует учитывать при поиске совместимого пакета SDK для .NET. Пути могут быть абсолютными или относительными к расположению файла global.json . Специальное значение $host$ представляет расположение, соответствующее выполняемому dotnet исполняемому файлу.

Пути просматриваются по порядку, в котором они определены, и используется первый подходящий пакет SDK.

сообщение об ошибке

Тип: string
Доступно с момента: пакет SDK для .NET 10 ( предварительная версия 3).

Указывает настраиваемое сообщение об ошибке, отображаемое, когда сопоставитель пакета SDK не может найти совместимый пакет SDK для .NET.

msbuild-sdks

Тип: object

Позволяет управлять версией пакета SDK для проекта в одном месте, а не в отдельном проекте. Дополнительные сведения см. в разделе Как разрешаются SDK проекта.

Комментарии в global.json

Примечания в global.json файлах поддерживаются с помощью комментариев стиля JavaScript или C#. Например:

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

Примеры

В следующем примере показано, как запретить использование предварительной версии:

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

В следующем примере показано, как использовать наивысшую установленную версию, которая равна или больше указанной версии. В формате JSON показано, что запрещается использовать любую версию SDK ниже 7.0.200, но позволяет использовать версию 7.0.200 или любую более позднюю версию, включая 8.0.xxx.

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

В следующем примере показано, как использовать точную указанную версию:

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

В следующем примере показано, как использовать последнюю версию набора возможностей и обновления, установленную для конкретных основной и дополнительной версий. В формате JSON отображается запрет на любую версию пакета SDK до версии 8.0.302 и разрешает версию 8.0.302 или любую более позднюю версию 8.0.xxx, например 8.0.303 или 8.0.402.

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

В следующем примере показано, как использовать наивысшую версию обновления, установленную для конкретной версии. В показанном JSON запрещено использовать любую версию SDK ранее 8.0.102, а разрешается версия 8.0.102 или любая более поздняя версия 8.0.1xx, например 8.0.103 или 8.0.199.

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

В следующем примере показано, как указать дополнительные пути поиска пакета SDK и пользовательское сообщение об ошибке:

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

global.json и .NET CLI

Полезно знать, какие версии пакета SDK установлены на компьютере, чтобы задать их в файле global.json. Сведения о том, как это сделать, см. в разделе Проверка того, установлена ли платформа .NET.

Чтобы установить дополнительные версии .NET SDK на вашем компьютере, посетите страницу загрузки .NET.

Вы можете создать новый файл global.json в текущем каталоге, выполнив команду dotnet new, как в следующем примере:

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

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

Примечание.

Правила сопоставления управляются dotnet.exe точкой входа, которая является общей для всех установленных сред выполнения .NET. Правила сопоставления для последней установленной версии среды выполнения .NET используются при наличии нескольких сред выполнения, установленных параллельно или при использовании файла global.json .

Следующие правила применяются при определении используемой версии пакета SDK:

Если файл global.json не найден или global.json не указывает версию пакета SDK и не указывает allowPrerelease значение, используется самая высокая установленная версия пакета SDK (эквивалентна параметру rollForward).latestMajor Учитывается ли предварительная версия пакета SDK, зависит от того, как dotnet вызывается:
- Если вы не работаете в Visual Studio, учитываются предварительные версии.
- Если вы находитесь в Visual Studio, он использует запрашиваемое состояние предварительной версии. То есть, если вы используете предварительную версию Visual Studio или включили параметр Использовать предварительные версии пакета SDK для .NET (в разделе Сервис>Параметры>Среда>Функции предварительной версии), учитываются предварительные версии; в противном случае учитываются только выпущенные версии.
Если найден файл global.json, в котором не указана версия пакета SDK, но указано значение allowPrerelease, используется наивысшая версия пакета SDK (аналогично заданию значения rollForward для параметра latestMajor). На то, может ли последняя версия пакета SDK выпускаться или быть предварительным выпуском, влияет значение allowPrerelease. true указывает на то, что предварительные версии учитываются. false указывает на то, что учитываются только выпущенные версии.
Если файл global.json найден и в нем указана версия пакета SDK:
- Если значение rollForward не задано, в качестве политики patch по умолчанию используется rollForward. В противном случае проверьте каждое значение и их поведение в разделе rollForward.
- Сведения о том, учитываются ли предварительные версии и каково поведение по умолчанию, если параметр allowPrerelease не задан, представлены в разделе allowPrerelease.

Диагностика и устранение предупреждений сборки

Следующие предупреждения означают, что проект был скомпилирован с использованием предварительной версии пакета SDK для .NET:

Вы используете предварительную версию .NET. См.: https://aka.ms/dotnet-support-policy

Версии пакета SDK для .NET имеют гарантированное качество. Однако если вы не хотите использовать предварительную версию, ознакомьтесь с различными стратегиями, которые можно применять в разделе allowPrerelease. Для компьютеров, на которые никогда не устанавливалась среда выполнения .NET Core 3.0 или более поздней версии или пакет SDK, необходимо создать файл global.json и указать точную версию, которую требуется использовать.
Следующее предупреждение означает, что проект предназначен для EF Core 1.0 или 1.1, которые несовместимы с пакетом SDK для .NET Core 2.1 и более поздних версий:

Запускаемый проект '{startupProject}' нацелен на версию платформы '.NETCoreApp' '{targetFrameworkVersion}'. Эта версия средств командной строки .NET Entity Framework Core поддерживает только версию 2.0 или более позднюю. Сведения об использовании более старой версии средств см. на странице https://go.microsoft.com/fwlink/?linkid=871254.

Начиная с пакета SDK для .NET Core 2.1 (версия 2.1.300) поддерживается команда dotnet ef. Чтобы скомпилировать проект, установите пакет SDK для .NET Core 2.0 (версия 2.1.201) или более ранней версии на своем компьютере и определите необходимую версию пакета SDK с помощью файла global.json. Дополнительные сведения о команде dotnet ef см. в разделе Утилиты командной строки для EF Core .NET.
Если вы используете global.json для пребывания в определенной версии пакета SDK для .NET, обратите внимание, что Visual Studio устанавливает только одну копию пакета SDK для .NET. Поэтому при обновлении версии Visual Studio она удаляет предыдущую версию пакета SDK для .NET, которая использовалась для установки новой версии. Она удаляет старую версию, даже если это другая основная версия .NET.

Чтобы Visual Studio не удаляла версии SDK для .NET, установите автономный пакет SDK для .NET со страницы загрузки. Однако, если вы сделаете это, вы больше не будете получать автоматические обновления для этой версии .NET SDK через Visual Studio и можете столкнуться с риском для безопасности.

См. также

Как определяются SDK проекта