Поделиться через

Package versioning

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

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

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

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

Version basics

Номер конкретной версии находится в форме Major.Minor.Patch[-Suffix], где компоненты имеют следующие значения:

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

Examples:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Important

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

Pre-release versions

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

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

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

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

Note

Номера предварительной версии с нотацией точек, как и в версии 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.

Version ranges

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

Notation Applied rule 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) invalid invalid

Best Practice

Всегда указывайте диапазон версий или версий для зависимостей пакетов в файлах проекта, packages.config файлах и .nuspec файлах. Без диапазона версий или версий при разрешении зависимостей согласованные результаты восстановления не гарантируются. Избегайте указания верхней границы диапазонов версий для пакетов, которыми вы не владеете, если не знаете о проблеме совместимости. Верхние границы для внедрения диапазонов версий, препятствуют потребителям получать ценные обновления зависимостей, а в некоторых случаях могут привести к использованию неподдерживаемых версий зависимостей.

Ссылки в файлах проекта (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 only version 6.1.0. -->
<PackageReference Include="ExamplePackage" Version="[6.1.0]" />

<!-- 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)" />

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

Note

Это критическое изменение для 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.0 в виде отдельного и другого пакета.

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

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

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

Для nuget.org пакет определяется как пакет SemVer версии 2.0.0, если одно из следующих инструкций имеет значение true:

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

При отправке пакета SemVer версии 2.0.0 в nuget.org пакет невидим для старых клиентов и доступен только для следующих клиентов NuGet:

Third-party clients:

  • 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 равны.
  • Last updated on