Управление версиями пакета

  • Статья

При указании определенного пакета всегда используется его идентификатор и точный номер версии. Например, для Entity Framework на сайте nuget.org доступно несколько десятков специальных пакетов, начиная с версии 4.1.10311 и заканчивая версией 6.1.3 (последний стабильный выпуск), а также множество предварительных версий, таких как 6.2.0-beta1.

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

Следующий документ следует стандарту семантической версии 2.0.0, поддерживаемой NuGet 4.3.0 + и Visual Studio 2017 версии 15.3+. Некоторые семантики SemVer версии 2.0.0 не поддерживаются в старых клиентах.

В этом разделе:

Основные сведения о версиях

Номер определенной версии выглядит следующим образом: Основной номер.Дополнительный номер.Исправление[-Суффикс]. Компоненты номера имеют следующие значения:

  • Основные: критические изменения
  • Дополнительный: новые функции, но обратная совместимость
  • Исправление: исправление ошибок, совместимых с обратной совместимостью, исправление только
  • -Суффикс (необязательно): дефис , за которым следует строка, обозначающая предварительную версию (после соглашения о семантической версии или SemVer ).

Примеры:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Внимание

nuget.org отклоняет любую загрузку пакета, в которой отсутствует точный номер версии. Версия должна быть указана в .nuspec или файле проекта, с помощью которого был создан пакет.

Предварительные версии

С технической точки зрения, создатели пакетов могут использовать любую строку в качестве суффикса для обозначения предварительной версии, так как NuGet рассматривает любую такую версию как предварительную версию, не делая других интерпретаций. Это значит, что NuGet отображает полную строку версии в любом пользовательском интерфейсе, предоставляя потребителю возможность по-своему интерпретировать значение суффикса.

Тем не менее, разработчики пакетов обычно следуют общепризнанным соглашениям об именовании:

  • -alpha: Альфа-выпуск, обычно используемый для выполнения работы и экспериментирования.
  • -beta: бета-версия, которая обычно содержит полный набор функций для следующего запланированного выпуска, но может иметь известные ошибки;
  • -rc: версия-кандидат, которая обычно может служить итоговой (стабильной), если не будут выявлены серьезные ошибки.

При упорядочении версий по приоритету NuGet следует стандарту SemVer и выбирает версию без суффикса сначала, а затем применяет приоритет к версиям предварительного выпуска в обратном алфавитном порядке и обрабатывает номера точек с числовым порядком.

Примечание.

Предварительные номера с нотацией точек, как и в версии 1.0.1-build.23, считаются частью стандарта SemVer 2.0.0 , и так как они поддерживаются только в NuGet 4.3.0+.

1.0.1
1.0.1-zzz
1.0.1-rc.10
1.0.1-rc.2
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

Обратите внимание, что 1.0.1-alpha10 сортируется строго в обратном алфавитном порядке, в то время как 1.0.1-rc.10 больше приоритета, чем 1.0.1-rc.2.

Диапазоны версий

Что касается зависимостей пакетов, NuGet поддерживает использование интервальной нотации для указания диапазонов версий, которые представлены следующим образом:

Представление Примененное правило Description
1.0 x ≥ 1.0 Минимальная версия, включающая
[1.0,) x ≥ 1.0 Минимальная версия, включающая
(1.0,) x > 1.0 Минимальная версия, исключающая
[1.0] x == 1.0 Точное соответствие версии
(,1.0] x ≤ 1.0 Максимальная версия, включающая
(,1.0) x < 1.0 Максимальная версия, исключающая
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Точный диапазон, включающий
(1.0,2.0) 1.0 < x < 2.0 Точный диапазон, исключающий
[1.0,2.0) 1.0 ≤ x < 2.0 Смешанная включающая минимальная и исключающая максимальная версии
(1.0) недопустимо недопустимо

Примеры

Всегда указывайте версию или диапазон версий для зависимостей пакетов в файлах проекта (packages.config и .nuspec). Без версии или диапазона версий NuGet 2.8.x и более ранние версии выбирают последнюю доступную версию пакета при разрешении зависимости, тогда как NuGet 3.x и более поздние версии выбирают самую раннюю версию пакета. Указав версию или диапазон версий, вы сможете избежать этой неопределенности.

Ссылки в файлах проекта (PackageReference)

<!-- Accepts any version 6.1 and above.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.1" />

<!-- Accepts any 6.x.y version.
     Will resolve to the highest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="6.*" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. 
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. 
     Will resolve to the smallest acceptable stable version.
     -->
<PackageReference Include="ExamplePackage" Version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher.
     Will resolve to the smallest acceptable stable version.-->
<PackageReference Include="ExamplePackage" Version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher.
     Will resolve to the smallest acceptable stable version. -->
<PackageReference Include="ExamplePackage" Version="[1.3.2,1.5)" />

Ссылки в packages.config

В packages.config каждая зависимость указана с точным атрибутом version, который используется при восстановлении пакетов. Атрибут allowedVersions используется только во время выполнения операций обновления, чтобы ограничить версии, до которых может быть обновлен пакет.

<!-- Install/restore version 6.1.0, accept any version 6.1.0 and above on update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="6.1.0" />

<!-- Install/restore version 6.1.0, and do not change during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6.1.0]" />

<!-- Install/restore version 6.1.0, accept any 6.x version during update. -->
<package id="ExamplePackage" version="6.1.0" allowedVersions="[6,7)" />

<!-- Install/restore version 4.1.4, accept any version above, but not including, 4.1.3.
     Could be used to guarantee a dependency with a specific bug fix. -->
<package id="ExamplePackage" version="4.1.4" allowedVersions="(4.1.3,)" />

<!-- Install/restore version 3.1.2, accept any version up below 5.x on update, which might be
     used to prevent pulling in a later version of a dependency that changed its interface.
     However, this form is not recommended because it can be difficult to determine the lowest version. -->
<package id="ExamplePackage" version="3.1.2" allowedVersions="(,5.0)" />

<!-- Install/restore version 1.1.4, accept any 1.x or 2.x version on update, but not
     0.x or 3.x and higher. -->
<package id="ExamplePackage" version="1.1.4" allowedVersions="[1,3)" />

<!-- Install/restore version 1.3.5, accepts 1.3.2 up to 1.4.x on update, but not 1.5 and higher. -->
<package id="ExamplePackage" version="1.3.5" allowedVersions="[1.3.2,1.5)" />

Ссылки в файлах .nuspec

Атрибут version в элементе <dependency> описывает версии диапазона, допустимые для зависимости.

<!-- Accepts any version 6.1 and above. -->
<dependency id="ExamplePackage" version="6.1" />

<!-- Accepts any version above, but not including 4.1.3. Could be
     used to guarantee a dependency with a specific bug fix. -->
<dependency id="ExamplePackage" version="(4.1.3,)" />

<!-- Accepts any version up below 5.x, which might be used to prevent pulling in a later
     version of a dependency that changed its interface. However, this form is not
     recommended because it can be difficult to determine the lowest version. -->
<dependency id="ExamplePackage" version="(,5.0)" />

<!-- Accepts any 1.x or 2.x version, but not 0.x or 3.x and higher. -->
<dependency id="ExamplePackage" version="[1,3)" />

<!-- Accepts 1.3.2 up to 1.4.x, but not 1.5 and higher. -->
<dependency id="ExamplePackage" version="[1.3.2,1.5)" />

Нормализованные номера версий

Примечание.

Это критическое изменение для NuGet 3.4+.

При получении пакетов из репозитория во время выполнения операций установки, переустановки или восстановления NuGet 3.4+ обрабатывает номера версий следующим образом:

  • Начальные нули удаляются из номеров версий:

    • 1.00 обрабатывается как 1.0
    • 1.01.1 обрабатывается как 1.1.1
    • 1.00.0.1 обрабатывается как 1.0.0.1

  • Ноль в четвертой части номера версии будет опущен.

    • 1.0.0.0 обрабатывается как 1.0.0
    • 1.0.01.0 обрабатывается как 1.0.1

  • Удалены метаданные сборки SemVer 2.0.0

    • 1.0.7+r3456 обрабатывается как 1.0.7.

При возможности операции pack и restore нормализуют версии. Что касается уже собранных пакетов, эта нормализация не влияет на номера версий в самих пакетах. Она повлияет только на способ сопоставления версий NuGet при разрешении зависимостей.

Однако репозитории пакетов NuGet должны обрабатывать эти значения так же, как NuGet, чтобы предотвратить дублирование версий пакетов. Таким образом, репозиторий, содержащий пакет версии 1.0, не должен содержать версию 1.0.0 в качестве отдельного пакета.

Семантическое управление версиями 2.0.0

Определенная семантика SemVer версии 2.0.0 не поддерживается в более старых клиентах. NuGet определяет версию пакета как соответствующую SemVer версии 2.0.0, если выполнено любое из следующих условий:

  • Метка предварительной версии разделена точкой, например 1.0.0-alpha.1.
  • Версия содержит метаданные сборки, например 1.0.0+githash.

Сайт nuget.org определяет пакет как SemVer версии 2.0.0, если выполнено любое из следующих условий:

  • Собственная версия пакета совместима с SemVer версии 2.0.0, но не совместима с SemVer версии 1.0.0, как определено выше.
  • Любой из диапазонов версий зависимостей пакета включает минимальную или максимальную версию, совместимую с SemVer версии 2.0.0, но не совместимую с системой SemVer версии 1.0.0, определенной выше, например, [1.0.0-alpha.1,).

Если вы загрузите пакет, соответствующий SemVer версии 2.0.0, на сайт nuget.org, он будет невидим для более старых клиентов и доступен только для приведенных ниже клиентов NuGet:

Сторонние клиенты:

  • JetBrains Rider;
  • Paket версии 5.0+.

Отличия NuGetVersion от Семантического версионирования

Если вы хотите использовать версии пакетов NuGet программно, настоятельно рекомендуем использовать пакет NuGet.Versioning. Статический метод NuGetVersion.Parse(string) можно применять для анализа строк версии, а метод VersionComparer — для сортировки экземпляров NuGetVersion.

Если вы реализуете функциональность NuGet на языке, который не работает на платформе .NET, ниже приведен список известных различий между NuGetVersion и Семантическим версионированием, а также причины, по которым существующая библиотека Семантического версионирования может не работать для пакетов, уже опубликованных на nuget.org.

  1. NuGetVersion поддерживает сегмент 4-й версии (Revision) для совместимости с классом System.Version или использования в качестве надмножества для этого класса. Таким образом, за исключением предварительных выпусков и меток метаданных, строка версии имеет вид Major.Minor.Patch.Revision. В случае нормализации версий, описанной выше, если Revision значение равно нулю, оно не указано в нормализованной строке версии.
  2. NuGetVersion требует определить только сегмент основной версии. Все остальные сегменты необязательны и считаются равными нулю. Это означает, что все варианты 1, 1.0, 1.0.0 и 1.0.0.0 эквивалентны и допустимы.
  3. NuGetVersion использует сравнение нечувствительных строк регистра для компонентов предварительного выпуска. Это означает, что 1.0.0-alpha и 1.0.0-Alpha эквивалентны.