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 řadu předběžných verzí, 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émantické verze 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í: Zásadní změny
  • Podverze: Nové funkce, ale zpětně kompatibilní
  • Oprava: Opravám chyb, které jsou zpětně kompatibilní
  • -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 .nuspec v souboru projektu nebo 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 vydání, 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ředprodejní čísla s zápisem tečky, jak je uvedeno v 1.0.1-build.23, jsou považovány za součást standardu SemVer 2.0.0 a jako takové jsou podporovány pouze u NuGetu 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:

Notace 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 (vyjma)
[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 (vyjma)
[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 (vyjma)
[1.0,2.0) 1,0 ≤ x < 2,0 Kombinace minimální (včetně) a maximální (vyjma) verze
(1.0) neplatné neplatné

Příklady

Vždy zadejte verzi nebo rozsah verzí pro závislosti balíčků v souborech projektu, packages.config souborech a .nuspec souborech. Bez rozsahu verzí nebo verzí zvolí NuGet 2.8.x a starší nejnovější dostupnou verzi balíčku při překladu závislosti, zatímco NuGet 3.x a novější zvolí nejnižší verzi balíčku. Určení verze nebo rozsahu verzí zabrání této nejistotě.

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

Odkazy v packages.config:

Každá packages.configzávislost je uvedena s přesným version atributem, který se používá při obnovování balíčků. Atribut allowedVersions se používá pouze během aktualizačních operací k omezení verzí, na které se balíček může aktualizovat.

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

Odkazy 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 proto nemělo hostovat také verzi 1.0.0 jako samostatný a jiný balíček.

Sémantika správy 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 NuGet 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 ji použít k řazení NuGetVersion instancí.

Pokud implementujete funkce NuGet v jazyce, který se nespouští v .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 , Revisionbýt kompatibilní s, nebo nadmnožinou , System.Version. Proto vyloučení předprodeje a popisků metadat je Major.Minor.Patch.Revisionřetězec verze . Podle výše popsané normalizace verzí se v případě Revision nulové hodnoty vynechá 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.01.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 rovny.