Sdílet prostřednictvím

Správa verzí balíčků

  • Článek

Konkrétní balíček se vždy označuje pomocí identifikátoru balíčku a přesného čísla verze. Například Entity Framework na nuget.org má k dispozici několik desítek konkrétních balíčků, od verze 4.1.10311 až po verzi 6.1.3 (nejnovější stabilní verze) a různé předběžné verze, jako je 6.2.0-beta1.

Při vytváření balíčku přiřadíte konkrétní číslo verze s volitelnou příponou předběžné verze. Při využívání balíčků můžete na druhé straně zadat přesné číslo verze nebo rozsah přijatelných verzí.

Následující dokument se řídí standardem Sémantic Versioning 2.0.0, který podporuje NuGet 4.3.0+ a Visual Studio 2017 verze 15.3 nebo novější. Některé sémantika semVer v2.0.0 nejsou ve starších klientech podporovány.

V tomto tématu:

Základy verzí

Konkrétní číslo verze je ve formátu Major.Minor.Patch[-Suffix], kde součásti mají následující významy:

  • hlavní: Zásadní změny
  • menší: Nové funkce, ale zpětně kompatibilní
  • oprava : Opravám chyb kompatibilních se zpět pouze
  • -Suffix (volitelné): spojovník následovaný řetězcem označujícím předběžnou verzi (podle konvence Semantic Versioning nebo SemVer).

Příklady :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Důležitý

nuget.org odmítne nahrání balíčku, který nemá přesné číslo verze. Verze musí být zadána v souboru .nuspec nebo projektu použitém k vytvoření balíčku.

Předběžné verze

Tvůrci balíčků můžou technicky vzato použít libovolný řetězec jako příponu k označení předběžné verze, protože NuGet považuje všechny takové verze jako předběžnou verzi a nevytváří žádnou jinou interpretaci. To znamená, že NuGet zobrazí celý řetězec verze v jakémkoli uživatelském rozhraní, takže jakákoli interpretace významu přípony pro příjemce.

To znamená, že vývojáři balíčků obecně dodržují rozpoznané zásady vytváření názvů:

  • -alpha: Alfa verze, která se obvykle používá pro probíhající práci a experimentování.
  • -beta: Beta verze, obvykle ta, která je dokončena pro příští plánovanou verzi, ale může obsahovat známé chyby.
  • -rc: Release Candidate, obvykle verze, která je potenciálně konečná (stabilní), pokud se neobjeví významné chyby.

Při řazeníverzíchm kódem NuGet se řídí standardem SemVer a jako první zvolí verzi bez přípony, použije přednost pro předběžné verze v abecedním pořadí a zachází s čísly zápisu tečky s číselným pořadím.

Poznámka

Předběžná verze čísel s tečkou, jak je uvedeno v 1.0.1-build.23, jsou považovány za součást SemVer 2.0.0 standard, a proto jsou podporovány pouze s 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

Všimněte si, že 1.0.1-alpha10 je seřazen výhradně v opačném abecedním pořadí, zatímco 1.0.1-rc.10 má větší prioritu než 1.0.1-rc.2.

Rozsahy verzí

Při odkazování na závislosti balíčků NuGet podporuje zápis intervalu pro určení rozsahů verzí shrnutý takto:

Zápis Použité pravidlo Popis
1.0 x ≥ 1,0 Minimální verze včetně
[1.0,) x ≥ 1,0 Minimální verze včetně
(1.0,) x > 1,0 Minimální verze, exkluzivní
[1.0] x == 1,0 Přesná shoda verze
(,1.0] x ≤ 1,0 Maximální verze včetně
(,1.0) x < 1,0 Maximální verze s výhradním
[1.0,2.0] 1,0 ≤ x ≤ 2,0 Přesný rozsah včetně
(1.0,2.0) 1,0 < x < 2,0 Přesný rozsah, exkluzivní
[1.0,2.0) 1,0 ≤ x < 2,0 Smíšená minimální a exkluzivní maximální verze
(1.0) neplatný neplatný

Osvědčených

Vždy zadejte verzi nebo rozsah verzí pro závislosti balíčků v souborech projektu, packages.config soubory a .nuspec soubory. Bez rozsahu verzí nebo verzí nejsou při překladu závislosti zaručeny konzistentní výsledky obnovení. Nezadávejte horní mez rozsahů verzí balíčkům, které nevlastníte, pokud nevíte o problému kompatibility. Horní hranice rozsahůverzíchm systémům zabráníte, aby spotřebitelé dostávali cenné aktualizace, a v některých případech je můžou vést k používání nepodporovaných verzí závislostí.

Odkazy v souborech 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)" />

Reference v packages.config:

V packages.configje každá závislost uvedená s přesným atributem version, který se používá při obnovování balíčků. Atribut allowedVersions se používá pouze během operací aktualizace k omezení verzí, na které může být balíček aktualizován.

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

Reference v .nuspec souborech

Atribut version v elementu <dependency> popisuje verze rozsahu, které jsou přijatelné pro závislost.

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

Normalizovaná čísla verzí

Poznámka

Jedná se o zásadní změnu pro NuGet 3.4 nebo novější.

Při získávání balíčků z úložiště během operací instalace, přeinstalace nebo obnovení nuGet 3.4+ považuje čísla verzí za následující:

  • Počáteční nuly se odeberou z čísel verzí:

    • 1.00 se považuje za 1,0
    • 1.01.1 se považuje za 1.1.1.
    • 1.00.0.1 se považuje za 1.0.0.1

  • Ve čtvrté části čísla verze se vynechá nula.

    • 1.0.0.0 se považuje za 1.0.0.
    • 1.0.01.0 se považuje za 1.0.1

  • Odebere se metadata sestavení SemVer 2.0.0.

    • 1.0.7+r3456 se považuje za 1.0.7

pack a restore operace normalizují verze, kdykoli je to možné. U již vytvořených balíčků tato normalizace nemá vliv na čísla verzí v samotných balíčcích; ovlivňuje pouze to, jak NuGet odpovídá verzím při překladu závislostí.

Úložiště balíčků NuGet však musí s těmito hodnotami zacházet stejným způsobem jako s NuGetem, aby se zabránilo duplikování verzí balíčku. Úložiště, které obsahuje verzi 1.0 balíčku, by nemělo také hostovat verzi 1.0.0 jako samostatný a jiný balíček.

Sémantická správa verzí 2.0.0

Některé sémantika semVer v2.0.0 nejsou ve starších klientech podporovány. NuGet považuje verzi balíčku za specifickou pro SemVer v2.0.0, pokud platí některý z následujících tvrzení:

  • Popisek předběžné verze je oddělený tečkami, například 1.0.0-alpha.1
  • Verze obsahuje metadata sestavení, například 1.0.0+githash

Pro nuget.org je balíček definován jako balíček SemVer v2.0.0, pokud je splněn některý z následujících příkazů:

  • Vlastní verze balíčku je SemVer verze 2.0.0, ale není kompatibilní se semVer v1.0.0, jak je definováno výše.
  • Některé z rozsahů verzí závislostí balíčku mají minimální nebo maximální verzi, která je kompatibilní s semVer v2.0.0, ale není kompatibilní se semVer v1.0.0, definovaná výše; například [1.0.0-alpha.1, ).

Pokud nahrajete balíček specifický pro SemVer v2.0.0 do nuget.org, bude balíček neviditelný pro starší klienty a k dispozici pouze pro následující klienty NuGet:

  • NuGet 4.3.0 nebo novější
  • Visual Studio 2017 verze 15.3 nebo novější
  • Visual Studio 2015 s VSIX v3.6.0
  • .NET SDK 2.0.0+

Klienti třetích stran:

  • JetBrains Rider
  • Paket verze 5.0 nebo novější

Kde se NuGetVersion liší od sémantické správy verzí

Pokud chcete programově používat verze balíčků NuGet, důrazně doporučujeme použít balíček NuGet.Versioning. Statickou metodu NuGetVersion.Parse(string) lze použít k analýze řetězců verzí a VersionComparer lze použít k řazení NuGetVersion instancí.

Pokud implementujete funkce NuGet v jazyce, který se nespustí v rozhraní .NET, tady je známý seznam rozdílů mezi NuGetVersion a sémantickou správou verzí a důvody, proč existující knihovna sémantických verzí nemusí fungovat pro balíčky, které jsou již publikovány v nuget.org.

  1. NuGetVersion podporuje 4. segment verze, Revision, aby byl kompatibilní s System.Versionnebo nadmnožinou . Proto kromě popisků předběžné verze a metadat je řetězec verze Major.Minor.Patch.Revision. Pokud je Revision nula, je podle výše popsané normalizace verzí vynechán z řetězce normalizované verze.
  2. NuGetVersion vyžaduje pouze definování hlavního segmentu. Všechny ostatní jsou volitelné a jsou ekvivalentní nule. To znamená, že 1, 1.0, 1.0.0a 1.0.0.0 jsou všechny přijímány a rovny.
  3. NuGetVersion používá porovnání řetězců nerozlišující malá a velká písmena pro předběžné verze komponent. To znamená, že 1.0.0-alpha a 1.0.0-Alpha jsou stejné.