Megosztás a következőn keresztül:

Csomag verziószámozása

  • Cikk

Egy adott csomagra mindig a csomagazonosító és a pontos verziószám hivatkozik. A nuget.org Entity Framework például több tucat konkrét csomaggal rendelkezik, amelyek a 4.1.10311-es verziótól a 6.1.3- verzióig (a legújabb stabil kiadásig) és számos előzetes verzióval, például a 6.2.0-beta1.

Csomag létrehozásakor hozzárendel egy adott verziószámot egy opcionális kiadás előtti szöveg utótaggal. A csomagok használatakor azonban megadhat egy pontos verziószámot vagy egy elfogadható verziótartományt.

Az alábbi dokumentum a Szemantikus verziószám 2.0.0 szabványt követi, amelyet a NuGet 4.3.0+ és a Visual Studio 2017 15.3+-os verziója támogat. A SemVer v2.0.0 bizonyos szemantikája nem támogatott a régebbi ügyfeleknél.

Ebben a témakörben:

A verzió alapjai

Egy adott verziószám Major.Minor.Patch[-Utótag]formájában, ahol az összetevők jelentése a következő:

  • fő: Kompatibilitástörő változások
  • Kisebb: Új funkciók, de visszamenőlegesen kompatibilisek
  • Javítás: Csak visszamenőlegesen kompatibilis hibajavítások
  • -Suffix (nem kötelező): egy kötőjel, majd egy sztring, amely egy kiadás előtti verziót jelöl (a Szemantikus verziószámozás vagy a SemVer konvenciót követve).

példák:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Fontos

nuget.org elutasít minden olyan csomagfeltöltést, amely nem tartalmaz pontos verziószámot. A verziót meg kell adni a csomag létrehozásához használt .nuspec vagy projektfájlban.

Kiadás előtti verziók

Technikailag a csomagkészítők bármilyen sztringet használhatnak utótagként a kiadás előtti verzió megjelöléséhez, mivel a NuGet minden ilyen verziót előzetes kiadásként kezel, és nem ad más értelmezést. Ez azt jelenti, hogy a NuGet minden felhasználói felületen megjeleníti a teljes verziós sztringet, így az utótag jelentésének bármilyen értelmezése a fogyasztóra marad.

Ennek ellenére a csomagfejlesztők általában a felismert elnevezési konvenciók szerint járnak el:

  • -alpha: Alfa kiadás, amely általában folyamatban lévő munkához és kísérletezéshez használatos.
  • -beta: Bétaverziós kiadás, amely jellemzően a következő tervezett kiadáshoz készült, de ismert hibákat tartalmazhat.
  • -rc: Kiadási jelölt, általában egy potenciálisan végleges (stabil) kiadás, kivéve, ha jelentős hibák merülnek fel.

Ha a verziók sorrendje elsőbbséget élvez, a NuGet a SemVer szabványt követi, és utótag nélküli verziót választ, majd a kiadás előtti verziókra fordított betűrendben alkalmazza az elsőbbséget, és numerikus sorrendben kezeli a pontjegyzetszámokat.

Jegyzet

Az 1.0.1-build.231.0.1-build.23-as SemVer 2.0.0 szabvány részét képezik, ezért csak a NuGet 4.3.0+támogatottak.

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

Vegye figyelembe, hogy az 1.0.1-alfa10 szigorúan fordított betűrendben van rendezve, míg az 1.0.1-rc.10 nagyobb elsőbbséget élvez az 1.0.1-rc.2-nél.

Verziótartományok

Csomagfüggőségekre való hivatkozáskor a NuGet támogatja az intervallum jelölését a verziótartományok megadásához, az alábbiak szerint összegezve:

Jelölés Alkalmazott szabály Leírás
1.0 x ≥ 1.0 Minimális verzió, beleértve a
[1.0,) x ≥ 1.0 Minimális verzió, beleértve a
(1.0,) x > 1.0 Minimális verzió, kizárólagos
[1.0] x == 1,0 Pontos verzióegyezés
(,1.0] x ≤ 1.0 Maximális verzió, beleértve a
(,1.0) x < 1.0 Maximális verzió, kizárólagos
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Pontos tartomány, beleértve
(1.0,2.0) 1.0 < x < 2.0 Pontos tartomány, exkluzív
[1.0,2.0) 1.0 ≤ x < 2.0 Vegyesen tartalmazott minimális és kizárólagos maximális verzió
(1.0) érvénytelen érvénytelen

Ajánlott eljárás

Mindig adjon meg verzió- vagy verziótartományt a csomagfüggőségekhez a projektfájlokban, packages.config fájlokban és .nuspec fájlokban. Verzió- vagy verziótartomány nélkül a függőség feloldásakor a konzisztens visszaállítási eredmények nem garantáltak. Ne adjon meg felső határt a verziótartományokhoz olyan csomagokhoz, amelyekre nincs szüksége, hacsak nem tud kompatibilitási problémáról. A verziótartományok felső határa árt a bevezetésnek, megakadályozza a felhasználókat abban, hogy értékes frissítéseket kapjanak a függőségekhez, és bizonyos esetekben előfordulhat, hogy a függőségek nem támogatott verzióit használják.

Hivatkozások projektfájlokban (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)" />

hivatkozások a packages.config:

A packages.configminden függőség pontosan version attribútummal szerepel, amelyet a csomagok visszaállításakor használnak. A allowedVersions attribútum csak a frissítési műveletek során használatos, hogy korlátozza azokat a verziókat, amelyekre a csomag frissíthető.

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

hivatkozások .nuspec fájlokban

A <dependency> elem version attribútuma a függőségek számára elfogadható tartományverziókat ismerteti.

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

Normalizált verziószámok

Jegyzet

Ez a NuGet 3.4+ kompatibilitástörő változása.

Amikor csomagokat szerez be egy adattárból a telepítési, újratelepítési vagy visszaállítási műveletek során, a NuGet 3.4+ a következő módon kezeli a verziószámokat:

  • A rendszer eltávolítja a kezdő nullákat a verziószámokból:

    • Az 1.00 1.0-ként van kezelve
    • Az 1.01.1 az 1.1.1.
    • Az 1.00.0.1 1.0.0.1

  • A verziószám negyedik részének nullája ki lesz hagyva

    • Az 1.0.0.0 1.0.0
    • Az 1.0.01.0 1.0.1-ként van kezelve

  • A SemVer 2.0.0 build metaadatai el lettek távolítva

    • Az 1.0.7+r3456 1.0.7

pack és restore műveletek minden lehetséges esetben normalizálják a verziókat. A már elkészített csomagok esetében ez a normalizálás nem befolyásolja a csomagok verziószámát; ez csak azt befolyásolja, hogy a NuGet hogyan egyezik a verziókkal a függőségek feloldásakor.

A NuGet-csomagtáraknak azonban ugyanúgy kell kezelniük ezeket az értékeket, mint a NuGetet, hogy megakadályozzák a csomagverziók duplikálását. Így egy csomag 1.0-s verziót tartalmazó adattár nem üzemeltethet 1.0.0-s verziót különálló és eltérő csomagként.

Szemantikus verziószámozás 2.0.0

A SemVer 2.0.0-s verziójának bizonyos szemantikája nem támogatott a régebbi ügyfeleknél. A NuGet a csomagverziót a SemVer 2.0.0-s verziójának tekinti, ha az alábbi állítások valamelyike igaz:

  • A kiadás előtti címke pontelválasztó, például 1.0.0-alpha.1
  • A verzió build-metaadatokkal rendelkezik, például 1.0.0+githash

A nuget.org esetében a csomag a SemVer v2.0.0-s csomagként van definiálva, ha az alábbi utasítások valamelyike igaz:

  • A csomag saját verziója a SemVer 2.0.0-s verziója, de nem felel meg a Fent meghatározott SemVer 1.0.0-s verziójának.
  • A csomag bármely függőségi verziótartománya rendelkezik egy minimális vagy maximális verzióval, amely a SemVer 2.0.0-s verziójának megfelelő, de nem a Fent definiált SemVer 1.0.0-s verziónak megfelelő; például [1.0.0-alpha.1, ).

Ha egy SemVer v2.0.0-specifikus csomagot tölt fel a nuget.org, a csomag a régebbi ügyfelek számára láthatatlan, és csak a következő NuGet-ügyfelek számára érhető el:

  • NuGet 4.3.0+
  • Visual Studio 2017 15.3+-os verzió
  • Visual Studio 2015 NuGet VSIX 3.6.0-s
  • .NET SDK 2.0.0+

Külső ügyfelek:

  • JetBrains Rider
  • Paket 5.0+-os verzió

Ahol a NuGetVersion eltér a szemantikus verziószámozástól

Ha programozott módon szeretné használni a NuGet-csomagverziókat, erősen ajánlott a NuGet.Versioningcsomag használata. A statikus NuGetVersion.Parse(string) metódus használható a verziósztringek elemzésére, VersionComparer pedig NuGetVersion példányok rendezésére.

Ha olyan nyelven implementálja a NuGet-funkciókat, amely nem .NET-en fut, az alábbi lista tartalmazza a NuGetVersion és a szemantikus verziószámozás közötti különbségek ismert listáját, valamint azokat az okokat, amelyek miatt előfordulhat, hogy egy meglévő szemantikus verziószámozási kódtár nem működik a nuget.org már közzétett csomagok esetében.

  1. NuGetVersion támogatja a 4. verziós szegmenst, Revision, hogy kompatibilis legyen a System.Version. Ezért az elő- és metaadatcímkék kivételével a verziósztring Major.Minor.Patch.Revision. A fent ismertetett verziónormalizálás szerint, ha Revision nulla, akkor a normalizált verzió sztringje nem jelenik meg.
  2. NuGetVersion csak a fő szegmens definiálására van szükség. A többi nem kötelező, és nullával egyenértékű. Ez azt jelenti, hogy 1, 1.0, 1.0.0és 1.0.0.0 mind elfogadottak és egyenlőek.
  3. NuGetVersion a kis- és nagybetűk érzéketlen sztring-összehasonlítását használja a kiadás előtti összetevőkhöz. Ez azt jelenti, hogy 1.0.0-alpha és 1.0.0-Alpha egyenlőek.