Udostępnij za pośrednictwem

Przechowywanie wersji pakietów

  • Artykuł

Określony pakiet jest zawsze określany przy użyciu jego identyfikatora pakietu i dokładnego numeru wersji. Na przykład Entity Framework w nuget.org ma kilkadziesiąt dostępnych pakietów, począwszy od wersji 4.1.1.10311 do wersji 6.1.3 (najnowsza stabilna wersja) i różnych wersji wstępnych, takich jak 6.2.0-beta1.

Podczas tworzenia pakietu przypiszesz określony numer wersji z opcjonalnym sufiksem tekstowym wersji wstępnej. Z drugiej strony podczas korzystania z pakietów można określić dokładny numer wersji lub zakres dopuszczalnych wersji.

Poniższy dokument jest zgodny ze standardem Semantic Versioning 2.0.0 obsługiwanym przez programy NuGet 4.3.0+ i Visual Studio 2017 w wersji 15.3 lub nowszej. Niektóre semantyka SemVer w wersji 2.0.0 nie są obsługiwane w starszych klientach.

W tym temacie:

Podstawowe informacje o wersji

Określony numer wersji jest w postaci Major.Minor.Patch[-Sufiks], gdzie składniki mają następujące znaczenie:

  • Główne: zmiany powodujące niezgodność
  • pomocnicza: nowe funkcje, ale zgodne z poprzednimi wersjami
  • Patch: poprawki usterek zgodne z poprzednimi wersjami
  • -Sufiks (opcjonalnie): łącznik, po którym następuje ciąg oznaczający wersję wstępną (zgodnie z konwencją Semantic Versioning lub SemVer).

przykłady :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Ważny

nuget.org odrzuca wszelkie przekazywanie pakietów, które nie ma dokładnego numeru wersji. Wersja musi być określona w pliku .nuspec lub projekcie użytym do utworzenia pakietu.

Wersje wersji wstępnej

Technicznie rzecz biorąc, twórcy pakietów mogą używać dowolnego ciągu jako sufiksu, aby oznaczyć wersję wstępną, ponieważ NuGet traktuje dowolną wersję, taką jak wersja wstępna i nie dokonuje innej interpretacji. Oznacza to, że nuGet wyświetla pełny ciąg wersji w dowolnym interfejsie użytkownika, pozostawiając jakąkolwiek interpretację znaczenia sufiksu użytkownikowi.

Oznacza to, że deweloperzy pakietów zwykle przestrzegają rozpoznanych konwencji nazewnictwa:

  • -alpha: wersja alfa, zwykle używana do pracy w toku i eksperymentowania.
  • -beta: wersja beta, zazwyczaj ta, która jest funkcją ukończoną w następnej planowanej wersji, ale może zawierać znane usterki.
  • -rc: Release candidate(Kandydat na wydanie), zazwyczaj jest to wersja potencjalnie ostateczna (stabilna), chyba że pojawią się istotne błędy.

W przypadku zamawiania wersji według pierwszeństwa program NuGet jest zgodny ze standardem SemVer i wybiera wersję bez sufiksu, a następnie stosuje pierwszeństwo do wersji wstępnych w odwrotnej kolejności alfabetycznej i traktuje liczby notacji kropkowej z kolejnością liczb liczbową.

Nuta

Liczby wersji wstępnych z notacją kropkową, jak w 1.0.1-build.23, są traktowane jako część SemVer 2.0.0 standard, a w związku z tym są obsługiwane tylko w wersji 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

Należy pamiętać, że 1.0.1-alpha10 jest sortowane ściśle w odwrotnej kolejności alfabetycznej, natomiast 1.0.1-rc.10 ma większy pierwszeństwo niż 1.0.1-rc.2.

Zakresy wersji

W przypadku odwoływania się do zależności pakietów pakiet NuGet obsługuje używanie notacji interwału do określania zakresów wersji, podsumowane w następujący sposób:

Notacja Zastosowana reguła Opis
1.0 x ≥ 1.0 Minimalna wersja, włącznie
[1.0,) x ≥ 1.0 Minimalna wersja, włącznie
(1.0,) x > 1.0 Minimalna wersja, wyłączność
[1.0] x == 1.0 Dokładne dopasowanie wersji
(,1.0] x ≤ 1.0 Maksymalna wersja, włącznie
(,1.0) x < 1.0 Maksymalna wersja, wyłączność
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Dokładny zakres, włącznie
(1.0,2.0) 1.0 < x < 2.0 Dokładny zakres, wyłączność
[1.0,2.0) 1.0 ≤ x < 2.0 Mieszana minimalna i wyłączna wersja maksymalna
(1.0) Nieprawidłowy Nieprawidłowy

Najlepsze rozwiązanie

Zawsze określ wersję lub zakres wersji dla zależności pakietów w plikach projektu, plikach packages.config i plikach .nuspec. Bez zakresu wersji lub wersji podczas rozwiązywania zależności spójne wyniki przywracania nie są gwarantowane. Unikaj określania górnej granicy z zakresami wersji dla pakietów, których nie jesteś właścicielem, chyba że znasz problem ze zgodnością. Górne granice z zakresami wersji szkodzą wdrożeniu, zniechęcają konsumentów do uzyskiwania cennych aktualizacji zależności, a w niektórych przypadkach mogą prowadzić ich do korzystania z nieobsługiwanych wersji zależności.

Odwołania w plikach projektu (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)" />

odwołania w packages.config:

W packages.configkażda zależność jest wyświetlana z dokładnym atrybutem version używanym podczas przywracania pakietów. Atrybut allowedVersions jest używany tylko podczas operacji aktualizacji, aby ograniczyć wersje, do których można zaktualizować pakiet.

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

odwołania w plikach .nuspec

Atrybut version w elemecie <dependency> opisuje wersje zakresu, które są dopuszczalne dla zależności.

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

Znormalizowane numery wersji

Nuta

Jest to zmiana powodująca niezgodność dla pakietu NuGet w wersji 3.4 lub nowszej.

W przypadku uzyskiwania pakietów z repozytorium podczas operacji instalacji, ponownej instalacji lub przywracania pakiet NuGet 3.4+ traktuje numery wersji w następujący sposób:

  • Wiodące zera są usuwane z numerów wersji:

    • 1.00 jest traktowany jako 1.0
    • 1.01.1 jest traktowany jako 1.1.1
    • 1.00.0.1 jest traktowany jako 1.0.0.1

  • Zero w czwartej części numeru wersji zostanie pominięte

    • 1.0.0.0 jest traktowany jako 1.0.0
    • 1.0.01.0 jest traktowany jako 1.0.1

  • Metadane kompilacji SemVer 2.0.0 są usuwane

    • 1.0.7+r3456 jest traktowany jako 1.0.7

pack i restore operacje normalizują wersje zawsze, gdy jest to możliwe. W przypadku pakietów już skompilowanych ta normalizacja nie ma wpływu na numery wersji w samych pakietach; ma wpływ tylko na sposób dopasowania pakietów NuGet do wersji podczas rozpoznawania zależności.

Jednak repozytoria pakietów NuGet muszą traktować te wartości w taki sam sposób, jak NuGet, aby zapobiec duplikowaniu wersji pakietu. W związku z tym repozytorium, które zawiera wersję 1.0 pakietu, nie powinno również hostować wersji 1.0.0 jako oddzielny i inny pakiet.

Semantyczne przechowywanie wersji 2.0.0

Niektóre semantyka SemVer w wersji 2.0.0 nie są obsługiwane w starszych klientach. NuGet uznaje wersję pakietu za określoną w wersji SemVer w wersji 2.0.0, jeśli którakolwiek z następujących instrukcji ma wartość true:

  • Etykieta wersji wstępnej jest oddzielona kropką, na przykład 1.0.0-alpha.1
  • Wersja zawiera metadane kompilacji, na przykład 1.0.0+githash

W przypadku nuget.org pakiet jest definiowany jako pakiet SemVer w wersji 2.0.0, jeśli któraś z następujących instrukcji ma wartość true:

  • Własna wersja pakietu jest zgodna ze standardem SemVer w wersji 2.0.0, ale nie jest zgodna ze standardem SemVer w wersji 1.0.0, zgodnie z definicją powyżej.
  • Każdy z zakresów wersji zależności pakietu ma minimalną lub maksymalną wersję zgodną ze standardem SemVer w wersji 2.0.0, ale nie jest zgodna ze standardem SemVer w wersji 1.0.0, zdefiniowaną powyżej; na przykład [1.0.0-alpha.1, ).

Jeśli przekażesz pakiet specyficzny dla programu SemVer w wersji 2.0.0 do nuget.org, pakiet jest niewidoczny dla starszych klientów i jest dostępny tylko dla następujących klientów NuGet:

  • NuGet 4.3.0+
  • Visual Studio 2017 w wersji 15.3 lub nowszej
  • Program Visual Studio 2015 z NuGet VSIX w wersji 3.6.0
  • Zestaw .NET SDK 2.0.0 lub nowszy

Klienci innych firm:

  • JetBrains Rider
  • Paket w wersji 5.0 lub nowszej

Gdzie funkcja NuGetVersion różni się od semantycznego przechowywania wersji

Jeśli chcesz programowo używać wersji pakietów NuGet, zdecydowanie zaleca się użycie pakiet NuGet.Versioning. Metoda statyczna NuGetVersion.Parse(string) może służyć do analizowania ciągów wersji, a VersionComparer można użyć do sortowania wystąpień NuGetVersion.

W przypadku implementowania funkcji NuGet w języku, który nie działa na platformie .NET, poniżej przedstawiono znaną listę różnic między NuGetVersion a semantyczną obsługą wersji oraz przyczyny, dla których istniejąca biblioteka semantycznej obsługi wersji może nie działać w przypadku pakietów już opublikowanych na nuget.org.

  1. NuGetVersion obsługuje 4 segment wersji, Revision, aby był zgodny z lub nadzbiorem System.Version. W związku z tym z wyłączeniem etykiet wersji wstępnej i etykiet metadanych ciąg wersji jest Major.Minor.Patch.Revision. Zgodnie z opisaną powyżej normalizacją wersji, jeśli Revision ma wartość zero, zostanie pominięty z znormalizowanego ciągu wersji.
  2. NuGetVersion wymaga tylko zdefiniowanego segmentu głównego. Wszystkie inne są opcjonalne i są równoważne zero. Oznacza to, że 1, 1.0, 1.0.0i 1.0.0.0 są akceptowane i równe.
  3. NuGetVersion używa porównań ciągów bez uwzględniania wielkości liter dla składników wersji wstępnej. Oznacza to, że 1.0.0-alpha i 1.0.0-Alpha są równe.