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 platforma Entity Framework w nuget.org ma kilkadziesiąt dostępnych pakietów, począwszy od wersji 4.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 ma postać Główna.Pomocnicza.Patch[-Sufiks], gdzie składniki mają następujące znaczenie:

  • Główne: zmiany powodujące niezgodność
  • Pomocnicza: nowe funkcje, ale zgodne z poprzednimi wersjami
  • Poprawka: tylko 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żne

nuget.org odrzuca wszelkie przekazywanie pakietów, które nie ma dokładnego numeru wersji. Wersja musi być określona w .nuspec pliku projektu lub 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 kompletna w następnej planowanej wersji, ale może zawierać znane usterki.
  • -rc: Kandydat do wydania, zazwyczaj wersja, która jest 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ą.

Uwaga

Numery wersji wstępnej z notacją kropkową, jak w wersji 1.0.1-build.23, są traktowane jako część standardu SemVer 2.0.0 , a w związku z tym są obsługiwane tylko w przypadku pakietów 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 Wersja minimalna, włącznie
[1.0,) x ≥ 1.0 Wersja minimalna, włącznie
(1.0,) x > 1.0 Wersja minimalna, wyłącznie
[1.0] x == 1.0 Dokładne dopasowanie wersji
(,1.0] x ≤ 1.0 Wersja maksymalna, włącznie
(,1.0) x < 1.0 Wersja maksymalna, wyłącznie
[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łącznie
[1.0,2.0) 1.0 ≤ x < 2.0 Mieszany — wartość minimalna włącznie i wartość maksymalna wyłącznie
(1.0) nieprawidłowe nieprawidłowe

Przykłady

Zawsze określ wersję lub zakres wersji dla zależności pakietów w plikach projektu, packages.config plikach i .nuspec plikach. Bez zakresu wersji lub wersji nuGet 2.8.x i starszych wybiera najnowszą dostępną wersję pakietu podczas rozpoznawania zależności, natomiast pakiet NuGet 3.x lub nowszy wybiera najniższą wersję pakietu. Określenie wersji lub zakresu wersji pozwala uniknąć tej niepewnoś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 pliku packages.config:

W packages.configsystemie każda zależność jest wyświetlana z dokładnym version atrybutem 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 .nuspec plikach

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

Uwaga

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 oddzielnego i innego pakietu.

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 pakietem 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 pakietu NuGet.Versioning. Metoda NuGetVersion.Parse(string) statyczna może służyć do analizowania ciągów wersji i VersionComparer może służyć do sortowania NuGetVersion wystąpień.

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 i 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 w nuget.org.

  1. NuGetVersion obsługuje 4. segment wersji, Revision, który ma być zgodny z elementem , lub nadzbiorem wartości System.Version. W związku z tym, z wyłączeniem etykiet wersji wstępnej i etykiet metadanych, ciąg wersji to Major.Minor.Patch.Revision. Zgodnie z opisaną powyżej normalizacją wersji, jeśli Revision wartość to zero, zostanie pominięta 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 1wszystkie wartości , 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.