Delen via

Pakketversiebeheer

  • Artikel

Een specifiek pakket wordt altijd aangeduid met behulp van de pakket-id en een exact versienummer. Entity Framework op nuget.org heeft bijvoorbeeld enkele tientallen specifieke pakketten beschikbaar, variërend van versie 4.1.10311 tot versie 6.1.3 (de nieuwste stabiele release) en een verscheidenheid aan voorlopige versies, zoals 6.2.0-beta1.

Wanneer u een pakket maakt, wijst u een specifiek versienummer toe met een optioneel voorvoegsel voor de tekst van de voorlopige versie. Wanneer u pakketten gebruikt, kunt u daarentegen een exact versienummer of een bereik van acceptabele versies opgeven.

Het volgende document volgt de Semantic Versioning 2.0.0 standard, ondersteund door NuGet 4.3.0+ en Visual Studio 2017 versie 15.3+. Bepaalde semantiek van SemVer v2.0.0 worden niet ondersteund in oudere clients.

In dit onderwerp:

Basisbeginselen van versies

Een specifiek versienummer heeft de vorm Major.Minor.Patch[-Suffix], waarbij de onderdelen de volgende betekenissen hebben:

  • primaire: belangrijke wijzigingen
  • secundaire: nieuwe functies, maar compatibel met eerdere versies
  • Patch: alleen oplossingen voor achterwaartse fouten
  • -Achtervoegsel (optioneel): een afbreekstreepje gevolgd door een tekenreeks die een voorlopige versie aangeeft (na de Semantische versiebeheer of SemVer conventie).

voorbeelden:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Belangrijk

nuget.org weigert alle pakketuploads die geen exact versienummer hebben. De versie moet worden opgegeven in het .nuspec- of projectbestand dat wordt gebruikt om het pakket te maken.

Pre-releaseversies

Technisch gesproken kunnen pakketmakers elke tekenreeks als achtervoegsel gebruiken om een voorlopige versie aan te geven, omdat NuGet een dergelijke versie als voorlopige versie behandelt en geen andere interpretatie geeft. Dat wil zeggen dat NuGet de volledige versietekenreeks weergeeft in elke gebruikersinterface die elke interpretatie van de betekenis van het achtervoegsel aan de consument overlaat.

Dat gezegd hebbende, volgen pakketontwikkelaars in het algemeen herkende naamconventies:

  • -alpha: Alpha-release, die doorgaans wordt gebruikt voor werk in uitvoering en experimenten.
  • -beta: bètarelease, meestal een versie die volledig is voor de volgende geplande release, maar kan bekende bugs bevatten.
  • -rc: Releasekandidaat, meestal een release die mogelijk definitief (stabiel) is, tenzij er aanzienlijke bugs optreden.

Als u versies rangschikt op prioriteit, volgt NuGet de SemVer-standaard en kiest u eerst een versie zonder achtervoegsel. Vervolgens wordt prioriteit toegepast op voorlopige versies in omgekeerde alfabetische volgorde en worden punt notatienummers met numerieke volgorde behandeld.

Notitie

Prereleasenummers met puntnotatie, zoals in 1.0.1-build.23, worden beschouwd als onderdeel van de SemVer 2.0.0 standaard, en daarom worden alleen ondersteund met 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

Houd er rekening mee dat 1.0.1-alfa10 strikt in omgekeerde alfabetische volgorde wordt gesorteerd, terwijl 1.0.1-rc.10 een hogere prioriteit heeft dan 1.0.1-rc.2.

Versiebereiken

Als u verwijst naar pakketafhankelijkheden, ondersteunt NuGet het gebruik van interval notatie voor het opgeven van versiebereiken, samengevat als volgt:

Notatie Toegepaste regel Beschrijving
1.0 x ≥ 1,0 Minimale versie, inclusief
[1.0,) x ≥ 1,0 Minimale versie, inclusief
(1.0,) x > 1,0 Minimale versie, exclusief
[1.0] x == 1,0 Exacte versieovereenkomst
(,1.0] x ≤ 1,0 Maximale versie, inclusief
(,1.0) x < 1,0 Maximale versie, exclusief
[1.0,2.0] 1,0 ≤ x ≤ 2,0 Exact bereik, inclusief
(1.0,2.0) 1,0 < x < 2,0 Exact bereik, exclusief
[1.0,2.0) 1,0 ≤ x < 2,0 Gemengde inclusief minimum- en exclusieve maximumversie
(1.0) Ongeldig Ongeldig

Aanbevolen procedure

Geef altijd een versie- of versiebereik op voor pakketafhankelijkheden in projectbestanden, packages.config bestanden en .nuspec bestanden. Zonder een versie- of versiebereik wordt bij het oplossen van een afhankelijkheid geen consistente herstelresultaten gegarandeerd. Vermijd het opgeven van een bovengrens voor versiebereiken voor pakketten waarvan u niet de eigenaar bent, tenzij u bekend bent met een compatibiliteitsprobleem. Bovengrens voor versiebereiken kan de acceptatie van versies schaden, consumenten ontmoedigen om waardevolle updates voor afhankelijkheden te krijgen en in sommige gevallen kunnen ze leiden tot het gebruik van niet-ondersteunde versies van afhankelijkheden.

Verwijzingen in projectbestanden (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)" />

Verwijzingen in packages.config:

In packages.configwordt elke afhankelijkheid weergegeven met een exact version kenmerk dat wordt gebruikt bij het herstellen van pakketten. Het kenmerk allowedVersions wordt alleen gebruikt tijdens updatebewerkingen om de versies te beperken waarop het pakket kan worden bijgewerkt.

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

verwijzingen in .nuspec bestanden

Het kenmerk version in een <dependency> element beschrijft de bereikversies die acceptabel zijn voor een afhankelijkheid.

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

Genormaliseerde versienummers

Notitie

Dit is een belangrijke wijziging voor NuGet 3.4+.

Wanneer u pakketten uit een opslagplaats verkrijgt tijdens installatie-, opnieuw- of herstelbewerkingen, behandelt NuGet 3.4+ versienummers als volgt:

  • Voorloopnullen worden verwijderd uit versienummers:

    • 1.00 wordt behandeld als 1,0
    • 1.01.1 wordt behandeld als 1.1.1
    • 1.00.0.1 wordt behandeld als 1.0.0.1

  • Een nul in het vierde deel van het versienummer wordt weggelaten

    • 1.0.0.0 wordt behandeld als 1.0.0
    • 1.0.01.0 wordt behandeld als 1.0.1

  • Metagegevens van de build van SemVer 2.0.0 worden verwijderd

    • 1.0.7+r3456 wordt behandeld als 1.0.7

pack en restore normaliseren waar mogelijk versies. Voor pakketten die al zijn gebouwd, heeft deze normalisatie geen invloed op de versienummers in de pakketten zelf; dit is alleen van invloed op hoe NuGet overeenkomt met versies bij het oplossen van afhankelijkheden.

NuGet-pakketopslagplaatsen moeten deze waarden echter op dezelfde manier behandelen als NuGet om duplicatie van pakketversies te voorkomen. Een opslagplaats met versie 1.0 van een pakket mag dus niet ook versie 1.0.0 hosten als een afzonderlijk en ander pakket.

Semantische versiebeheer 2.0.0

Bepaalde semantiek van SemVer v2.0.0 wordt niet ondersteund in oudere clients. NuGet beschouwt een pakketversie als SemVer v2.0.0 specifiek als een van de volgende instructies waar is:

  • Het label vóór release is gescheiden door puntjes, bijvoorbeeld 1.0.0-alpha.1
  • De versie bevat build-metadata, bijvoorbeeld 1.0.0+githash

Voor nuget.org wordt een pakket gedefinieerd als een SemVer v2.0.0-pakket als een van de volgende instructies waar is:

  • De eigen versie van het pakket is SemVer v2.0.0-compatibel, maar niet SemVer v1.0.0-compatibel, zoals hierboven is gedefinieerd.
  • Een van de afhankelijkheidsversiebereiken van het pakket heeft een minimale of maximale versie die compatibel is met SemVer v2.0.0, maar niet met SemVer v1.0.0, zoals hierboven is gedefinieerd; bijvoorbeeld [1.0.0-alpha.1, ).

Als u een SemVer v2.0.0-specifiek pakket uploadt naar nuget.org, is het pakket onzichtbaar voor oudere clients en alleen beschikbaar voor de volgende NuGet-clients:

  • NuGet 4.3.0+
  • Visual Studio 2017 versie 15.3+
  • Visual Studio 2015 met NuGet VSIX v3.6.0
  • .NET SDK 2.0.0+

Clients van derden:

  • JetBrains Rider
  • Paket versie 5.0+

Waarbij NuGetVersion afwijkt van Semantic Versioning

Als u NuGet-pakketversies programmatisch wilt gebruiken, is het raadzaam om het pakket NuGet.Versioningte gebruiken. De statische methode NuGetVersion.Parse(string) kan worden gebruikt om de versietekenreeksen te parseren en VersionComparer kan worden gebruikt om NuGetVersion exemplaren te sorteren.

Als u NuGet-functionaliteit implementeert in een taal die niet wordt uitgevoerd op .NET, vindt u hier de bekende lijst met verschillen tussen NuGetVersion en Semantische versiebeheer, en de redenen waarom een bestaande Semantische versiebeheerbibliotheek mogelijk niet werkt voor pakketten die al op nuget.org zijn gepubliceerd.

  1. NuGetVersion ondersteunt een 4e versiesegment, Revision, om compatibel te zijn met, of een superset van, System.Version. Daarom wordt een versietekenreeks Major.Minor.Patch.Revision, met uitzondering van prerelease- en metagegevenslabels. Als Revision nul is, wordt deze volgens de hierboven beschreven versienormalisatie weggelaten uit de genormaliseerde versietekenreeks.
  2. NuGetVersion hoeft alleen het primaire segment te worden gedefinieerd. Alle andere zijn optioneel en zijn gelijk aan nul. Dit betekent dat 1, 1.0, 1.0.0en 1.0.0.0 allemaal worden geaccepteerd en gelijk zijn.
  3. NuGetVersion maakt gebruik van niet-hoofdlettergevoelige tekenreeksvergelijkingen voor pre-release-onderdelen. Dit betekent dat 1.0.0-alpha en 1.0.0-Alpha gelijk zijn.