Обзор global.json

Статья
05/10/2023

Эта статья относится к: ✔️ пакету 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 файл выбирает 6.0.300 или любую более позднюю группу компонентов или исправление для версии 6.0, установленной на компьютере:

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

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

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

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

пакет SDK

Тип: object

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

версия

Тип: string

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

Это поле:

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

allowPrerelease

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

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

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

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

rollForward

Тип: 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`	Использует самый высокий установленный дополнительный, полоса компонентов и уровень исправлений, соответствующий запрошенной основной с дополнительным, полосой компонентов и уровнем исправлений, превышающим указанное значение. Если не найдено, происходит сбой.
`latestMajor`	Использует самый высокий установленный пакет SDK для .NET с версией, превышающей указанное значение или равное ей. Если не найдено, происходит сбой.
`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 не позволяет использовать версию пакета SDK до 2.2.200 и разрешает 2.2.200 или любую более позднюю версию, включая 3.0.xxx и 3.1.xxx.

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

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

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

В следующем примере показано, как использовать последнюю версию набора возможностей и обновления, установленную для конкретных основной и дополнительной версий. Показанный JSON не позволяет использовать версию пакета SDK до 3.1.102 и разрешает 3.1.102 или любую более позднюю версию 3.1.xxx, например 3.1.103 или 3.1.200.

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

В следующем примере показано, как использовать наивысшую версию обновления, установленную для конкретной версии. Показанный JSON не позволяет использовать версию пакета SDK до 3.1.102 и разрешает 3.1.102 или любую более позднюю версию 3.1.1xx, например 3.1.103 или 3.1.199.

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

global.json и .NET CLI

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

Чтобы установить дополнительные версии пакета SDK для .NET на компьютере, посетите страницу скачиваемых файлов .NET.

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

dotnet new globaljson --sdk-version 6.0.100

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

Примечание.

Правила сопоставления определяются точкой входа 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 не задано, в качестве политики rollForward по умолчанию используется latestPatch. В противном случае проверьте каждое значение и их поведение в разделе rollForward.
- Сведения о том, учитываются ли предварительные версии и каково поведение по умолчанию, если параметр allowPrerelease не задан, представлены в разделе allowPrerelease.

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

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

Вы работаете с предварительной версией пакета SDK для .NET Core. Версию пакета SDK можно указать в файле global.json в текущем проекте. Дополнительные сведения см. на странице https://go.microsoft.com/fwlink/?linkid=869452.

Используется предварительная версия .NET. См. статью: https://aka.ms/dotnet-core-preview

Версии пакета 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.

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

См. также

Как разрешаются пакеты SDK проекта