Dela via

Paketversionshantering

  • Artikel

Ett specifikt paket refereras alltid till med hjälp av dess paketidentifierare och ett exakt versionsnummer. Till exempel har Entity Framework på nuget.org flera dussin specifika paket tillgängliga, från version 4.1.10311 till version 6.1.3 (den senaste stabila versionen) och en mängd olika förhandsversioner som 6.2.0-beta1.

När du skapar ett paket tilldelar du ett specifikt versionsnummer med ett valfritt textsuffix i förväg. När du använder paket kan du å andra sidan ange antingen ett exakt versionsnummer eller ett antal godkända versioner.

Följande dokument följer Semantic Versioning 2.0.0 standard, som stöds av NuGet 4.3.0+ och Visual Studio 2017 version 15.3+. Vissa semantik för SemVer v2.0.0 stöds inte i äldre klienter.

I det här avsnittet:

Grunderna i version

Ett specifikt versionsnummer finns i formuläret Major.Minor.Patch[-Suffix], där komponenterna har följande betydelser:

  • större: Icke-bakåtkompatibla ändringar
  • Mindre: Nya funktioner, men bakåtkompatibla
  • Patch: Endast bakåtkompatibla felkorrigeringar
  • -Suffix (valfritt): ett bindestreck följt av en sträng som anger en förhandsversion (enligt semantisk versionshantering eller SemVer- konvention).

exempel:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Viktig

nuget.org avvisar alla paketuppladdningar som saknar ett exakt versionsnummer. Versionen måste anges i .nuspec- eller projektfilen som används för att skapa paketet.

Förhandsversioner

Tekniskt sett kan paketskapare använda valfri sträng som ett suffix för att ange en förhandsversion, eftersom NuGet behandlar en sådan version som förhandsversion och inte gör någon annan tolkning. Det vill säga, NuGet visar den fullständiga versionssträngen i det användargränssnitt som ingår, vilket lämnar alla tolkningar av suffixets innebörd till konsumenten.

Med detta sagt följer paketutvecklare vanligtvis erkända namngivningskonventioner:

  • -alpha: Alfaversion, som vanligtvis används för pågående arbete och experimentering.
  • -beta: Betaversion, vanligtvis en som är funktions färdig för nästa planerade version, men som kan innehålla kända buggar.
  • -rc: Versionskandidat, vanligtvis en version som är potentiellt slutgiltig (stabil) om inte betydande buggar uppstår.

När du beställer versioner efter prioritet följer NuGet SemVer-standarden och väljer först en version utan suffix, sedan tillämpas prioritet på förhandsversioner i omvänd alfabetisk ordning och behandlar punktnotationsnummer med numerisk ordning.

Not

Förhandsversionsnummer med punkt notation, som i 1.0.1-build.23, anses vara en del av SemVer 2.0.0 standard, och därför stöds endast med 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

Observera att 1.0.1-alpha10 är strikt sorterad i omvänd alfabetisk ordning, medan 1.0.1-rc.10 är högre prioritet än 1.0.1-rc.2.

Versionsintervall

När du refererar till paketberoenden stöder NuGet användning av intervall notation för att ange versionsintervall, sammanfattat på följande sätt:

Notation Tillämpad regel Beskrivning
1.0 x ≥ 1.0 Lägsta version, inklusive
[1.0,) x ≥ 1.0 Lägsta version, inklusive
(1.0,) x > 1.0 Lägsta version, exklusiv
[1.0] x == 1,0 Exakt versionsmatchning
(,1.0] x ≤ 1.0 Maximal version, inklusive
(,1.0) x < 1.0 Högsta version, exklusiv
[1.0,2.0] 1,0 ≤ x ≤ 2.0 Exakt intervall, inklusive
(1.0,2.0) 1.0 < x < 2.0 Exakt intervall, exklusivt
[1.0,2.0) 1.0 ≤ x < 2.0 Lägsta och exklusiv maxversion för mixed inclusive
(1.0) ogiltig ogiltig

Bästa praxis

Ange alltid ett versions- eller versionsintervall för paketberoenden i projektfiler, packages.config filer och .nuspec filer. Utan ett versions- eller versionsintervall garanteras inte konsekventa återställningsresultat när du löser ett beroende. Undvik att ange ett övre gränsvärde till versionsintervall till paket som du inte äger om du inte känner till ett kompatibilitetsproblem. De övre gränserna för versionsintervall skadar implementeringen, avråder konsumenterna från att få värdefulla uppdateringar av beroenden och kan i vissa fall leda till att de använder versioner av beroenden som inte stöds.

Referenser i projektfiler (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)" />

referenser i packages.config:

I packages.configvisas varje beroende med ett exakt version attribut som används vid återställning av paket. Attributet allowedVersions används endast under uppdateringsåtgärder för att begränsa de versioner som paketet kan uppdateras till.

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

referenser i .nuspec filer

Attributet version i ett <dependency>-element beskriver de intervallversioner som är acceptabla för ett beroende.

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

Normaliserade versionsnummer

Not

Det här är en icke-bakåtkompatibel ändring för NuGet 3.4+.

När du hämtar paket från en lagringsplats under installationen, ominstallationen eller återställningen behandlar NuGet 3.4+ versionsnummer på följande sätt:

  • Inledande nolla tas bort från versionsnummer:

    • 1,00 behandlas som 1,0
    • 1.01.1 behandlas som 1.1.1
    • 1.00.0.1 behandlas som 1.0.0.1

  • En nolla i den fjärde delen av versionsnumret utelämnas

    • 1.0.0.0 behandlas som 1.0.0
    • 1.0.01.0 behandlas som 1.0.1

  • SemVer 2.0.0-kompileringsmetadata tas bort

    • 1.0.7+r3456 behandlas som 1.0.7

pack och restore åtgärder normaliserar versioner när det är möjligt. För paket som redan har skapats påverkar den här normaliseringen inte versionsnumren i själva paketen. Det påverkar bara hur NuGet matchar versioner när du löser beroenden.

NuGet-paketlagringsplatser måste dock behandla dessa värden på samma sätt som NuGet för att förhindra paketversionsduplicering. Därför bör en lagringsplats som innehåller version 1.0 av ett paket inte också vara värd för version 1.0.0 som ett separat och annat paket.

Semantisk versionshantering 2.0.0

Vissa semantik för SemVer v2.0.0 stöds inte i äldre klienter. NuGet anser att en paketversion är SemVer v2.0.0 specifik om något av följande påståenden är sant:

  • Etiketten pre-release är punktavgränsad, till exempel 1.0.0-alpha.1
  • Versionen har build-metadata, till exempel 1.0.0+githash

För nuget.org definieras ett paket som ett SemVer v2.0.0-paket om något av följande uttryck är sant:

  • Paketets egen version är SemVer v2.0.0-kompatibel men inte SemVer v1.0.0-kompatibel enligt definitionen ovan.
  • Något av paketets beroendeversionsintervall har en lägsta eller högsta version som är SemVer v2.0.0-kompatibel men inte SemVer v1.0.0-kompatibel, definierad ovan; till exempel [1.0.0-alpha.1, ).

Om du laddar upp ett SemVer v2.0.0-specifikt paket till nuget.org är paketet osynligt för äldre klienter och är endast tillgängligt för följande NuGet-klienter:

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

Tredjepartsklienter:

  • JetBrains Rider
  • Paketversion 5.0+

Där NuGetVersion avviker från semantisk versionshantering

Om du vill använda NuGet-paketversioner programatiskt rekommenderar vi starkt att du använder paketet NuGet.Versionshantering. Den statiska metoden NuGetVersion.Parse(string) kan användas för att parsa versionssträngarna och VersionComparer kan användas för att sortera NuGetVersion instanser.

Om du implementerar NuGet-funktioner på ett språk som inte körs på .NET, här är den kända listan över skillnader mellan NuGetVersion och semantisk versionshantering och orsakerna till varför ett befintligt semantiskt versionsbibliotek kanske inte fungerar för paket som redan har publicerats på nuget.org.

  1. NuGetVersion stöder ett fjärde versionssegment, Revision, som ska vara kompatibelt med eller en supermängd av System.Version. Med undantag för förhandsversioner och metadataetiketter är därför en versionssträng Major.Minor.Patch.Revision. Enligt den versionsnormalisering som beskrivs ovan utelämnas den från den normaliserade versionssträngen om Revision är noll.
  2. NuGetVersion kräver bara att huvudsegmentet definieras. Alla andra är valfria och motsvarar noll. Det innebär att 1, 1.0, 1.0.0och 1.0.0.0 är alla accepterade och lika.
  3. NuGetVersion använder skiftlägesokänsliga strängjämförelser för förhandsversionskomponenter. Det innebär att 1.0.0-alpha och 1.0.0-Alpha är lika.