Freigeben über

Paketversionsverwaltung

  • Artikel

Ein bestimmtes Paket wird immer mit seiner Paket-ID und einer genauen Versionsnummer bezeichnet. Beispielsweise verfügt Entity Framework auf nuget.org über mehrere Dutzend spezifische Pakete, von Version 4.1.10311 bis zur Version 6.1.3 (neueste stabile Version) und einer Vielzahl von Vorabversionen wie 6.2.0-Beta1.

Beim Erstellen eines Pakets weisen Sie eine bestimmte Versionsnummer mit einem optionalen Vorabversionstextsuffix zu. Bei der Verwendung von Paketen können Sie dagegen entweder eine genaue Versionsnummer oder einen Bereich akzeptabler Versionen angeben.

Das folgende Dokument folgt dem Semantikversionsverwaltung 2.0.0 Standard, unterstützt von NuGet 4.3.0+ und Visual Studio 2017, Version 15.3+. Bestimmte Semantik von SemVer v2.0.0 werden in älteren Clients nicht unterstützt.

In diesem Thema:

Grundlagen der Version

Eine bestimmte Versionsnummer befindet sich in der Form Major.Minor.Patch[-Suffix], wobei die Komponenten die folgenden Bedeutungen haben:

  • Haupt-: Grundlegende Änderungen
  • Neben-: Neue Features, aber abwärtskompatibel
  • Patch-: Nur abwärtskompatible Fehlerbehebungen
  • -Suffix (optional): ein Bindestrich gefolgt von einer Zeichenfolge, die eine Vorabversion angibt (nach der Konvention semantischen Versionsverwaltung oder SemVer).

Beispiele:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Wichtig

nuget.org lehnt alle Paketuploads ab, für die keine genaue Versionsnummer vorhanden ist. Die Version muss in der .nuspec- oder Projektdatei angegeben werden, die zum Erstellen des Pakets verwendet wird.

Vorabversionen

Technisch gesehen können Paketersteller eine beliebige Zeichenfolge als Suffix verwenden, um eine Vorabversion zu kennzeichnen, da NuGet jede solche Version wie Vorabversion behandelt und keine andere Interpretation vorgibt. Das heißt, NuGet zeigt die Vollversionszeichenfolge in jeder Benutzeroberfläche an, wodurch jede Interpretation der Bedeutung des Suffixes für den Verbraucher übrig bleibt.

Das heißt, Paketentwickler folgen allgemein anerkannten Benennungskonventionen:

  • -alpha: Alpha-Freigabe, die in der Regel für laufende Arbeit und Experimente verwendet wird.
  • -beta: Betaversion, in der Regel ein Feature, das für die nächste geplante Version abgeschlossen ist, aber bekannte Fehler enthalten kann.
  • -rc: Release candidate, in der Regel eine Version, die potenziell abgeschlossen (stabil) ist, es sei denn, es treten erhebliche Fehler auf.

Wenn Sie Versionen nach Rang sortieren, folgt NuGet dem SemVer-Standard und wählt zuerst eine Version ohne Suffix aus, und wendet dann Vorrang auf Vorabversionen in umgekehrter alphabetischer Reihenfolge an und behandelt Punktnotationsnummern mit numerischer Reihenfolge.

Anmerkung

Prärelease-Zahlen mit Punktnotation, wie in 1.0.1-build.23, werden als Teil des SemVer 2.0.0 Standard betrachtet und als solche nur mit NuGet 4.3.0+ unterstützt.

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

Beachten Sie, dass 1.0.1-alpha10 streng in umgekehrter alphabetischer Reihenfolge sortiert ist, während 1.0.1-rc.10 größer als 1.0.1-rc.2 ist.

Versionsbereiche

Wenn Sie auf Paketabhängigkeiten verweisen, unterstützt NuGet die Intervallnotation zum Angeben von Versionsbereichen, zusammengefasst wie folgt:

Notation Angewendete Regel Beschreibung
1.0 x ≥ 1,0 Mindestversion( einschließlich)
[1.0,) x ≥ 1,0 Mindestversion( einschließlich)
(1.0,) x > 1,0 Mindestversion, exklusiv
[1.0] x == 1,0 Genaue Versionsangabe
(,1.0] x ≤ 1.0 Maximale Version( einschließlich)
(,1.0) x < 1,0 Maximale Version, exklusiv
[1.0,2.0] 1,0 ≤ x ≤ 2,0 Exakter Bereich( einschließlich)
(1.0,2.0) 1,0 < x < 2,0 Exakter Bereich, exklusiv
[1.0,2.0) 1,0 ≤ x < 2,0 Mixed inclusive minimum and exclusive maximum version
(1.0) Ungültig Ungültig

Beste Praxis

Geben Sie immer eine Version oder einen Versionsbereich für Paketabhängigkeiten in Projektdateien, packages.config Dateien und .nuspec Dateien an. Ohne Version oder Versionsbereich werden beim Auflösen einer Abhängigkeit konsistente Wiederherstellungsergebnisse nicht garantiert. Vermeiden Sie die Angabe einer oberen Grenze an Versionsbereiche für Pakete, die Sie nicht besitzen, es sei denn, Sie wissen ein Kompatibilitätsproblem. Obere Grenzen für Versionsbereiche beeinträchtigen die Akzeptanz, verhindern, dass Verbraucher wertvolle Updates für Abhängigkeiten erhalten, und in einigen Fällen können sie dazu führen, nicht unterstützte Versionen von Abhängigkeiten zu verwenden.

Verweise in Projektdateien (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)" />

Verweise in packages.config:

In packages.configwird jede Abhängigkeit mit einem genauen version Attribut aufgeführt, das beim Wiederherstellen von Paketen verwendet wird. Das attribut allowedVersions wird nur während Aktualisierungsvorgängen verwendet, um die Versionen einzuschränken, auf die das Paket aktualisiert werden kann.

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

Verweise in .nuspec Dateien

Das version-Attribut in einem <dependency>-Element beschreibt die Bereichsversionen, die für eine Abhängigkeit akzeptabel sind.

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

Normalisierte Versionsnummern

Anmerkung

Dies ist eine bahnbrechende Änderung für NuGet 3.4+.

Beim Abrufen von Paketen aus einem Repository während der Installation, erneuten Installation oder Wiederherstellungsvorgänge behandelt NuGet 3.4+ Versionsnummern wie folgt:

  • Führende Nullen werden aus Versionsnummern entfernt:

    • 1.00 wird als 1.0 behandelt
    • 1.01.1 wird als 1.1.1 behandelt
    • 1.00.0.1 wird als 1.0.0.1 behandelt.

  • Im vierten Teil der Versionsnummer wird eine Null weggelassen.

    • 1.0.0.0 wird als 1.0.0.0 behandelt
    • 1.0.01.0 wird als 1.0.1 behandelt

  • SemVer 2.0.0-Buildmetadaten werden entfernt.

    • 1.0.7+r3456 wird als 1.0.7 behandelt

pack und restore Vorgänge normalisieren Versionen nach Möglichkeit. Bei bereits erstellten Paketen wirkt sich diese Normalisierung nicht auf die Versionsnummern in den Paketen selbst aus. Es wirkt sich nur auf die Übereinstimmung von NuGet-Versionen beim Auflösen von Abhängigkeiten aus.

NuGet-Paketrepositorys müssen diese Werte jedoch auf die gleiche Weise behandeln wie NuGet, um die Paketversionsduplizierung zu verhindern. Daher sollte ein Repository, das Version 1.0 eines Pakets enthält, nicht auch die Version 1.0.0 als separates und anderes Paket hosten.

Semantische Versionsverwaltung 2.0.0

Bestimmte Semantik von SemVer v2.0.0 werden in älteren Clients nicht unterstützt. NuGet betrachtet eine Paketversion als SemVer v2.0.0-spezifisch, wenn eine der folgenden Anweisungen wahr ist:

  • Die Vorversionsbezeichnung ist punkttrennt, z. B. 1.0.0-alpha.1
  • Die Version verfügt über Buildmetadaten, z. B. 1.0.0+githash

Für nuget.org wird ein Paket als SemVer v2.0.0-Paket definiert, wenn eine der folgenden Anweisungen zutrifft:

  • Die eigene Version des Pakets ist SemVer v2.0.0-kompatibel, jedoch nicht semVer v1.0.0 kompatibel, wie oben definiert.
  • Jeder der Abhängigkeitsversionsbereiche des Pakets weist eine mindest- oder maximal zulässige Version auf, die SemVer v2.0.0 kompatibel, aber nicht semVer v1.0.0 kompatibel ist, die oben definiert ist; beispiel: [1.0.0-alpha.1, ).

Wenn Sie ein SemVer v2.0.0-spezifisches Paket auf nuget.org hochladen, ist das Paket für ältere Clients unsichtbar und nur für die folgenden NuGet-Clients verfügbar:

  • NuGet 4.3.0+
  • Visual Studio 2017, Version 15.3+
  • Visual Studio 2015 mit NuGet VSIX v3.6.0
  • .NET SDK 2.0.0+

Clients von Drittanbietern:

  • JetBrains Rider
  • Paketversion 5.0+

Wo NuGetVersion von der semantischen Versionsverwaltung abweicht

Wenn Sie NuGet-Paketversionen programmgesteuert verwenden möchten, wird dringend empfohlen, das Paket NuGet.Versioningzu verwenden. Die statische Methode NuGetVersion.Parse(string) kann verwendet werden, um die Versionszeichenfolgen zu analysieren, und VersionComparer können zum Sortieren NuGetVersion Instanzen verwendet werden.

Wenn Sie NuGet-Funktionen in einer Sprache implementieren, die nicht auf .NET ausgeführt wird, sind hier die bekannte Liste der Unterschiede zwischen NuGetVersion und semantischer Versionsverwaltung und die Gründe, warum eine vorhandene semantische Versionsverwaltungsbibliothek möglicherweise nicht für Pakete funktioniert, die bereits auf nuget.org veröffentlicht wurden.

  1. NuGetVersion unterstützt ein 4. Versionssegment, Revision, das mit einer Obermenge von System.Versionkompatibel ist. Daher wird eine Versionszeichenfolge Major.Minor.Patch.Revision, ausgenommen Vorabversionen und Metadatenbeschriftungen. Wie in der oben beschriebenen Versionsnormalisierung, wenn Revision null ist, wird sie aus der normalisierten Versionszeichenfolge weggelassen.
  2. NuGetVersion erfordert nur die Definition des Hauptsegments. Alle anderen sind optional und entsprechen null. Dies bedeutet, dass 1, 1.0, 1.0.0und 1.0.0.0 alle akzeptiert und gleich sind.
  3. NuGetVersion verwendet Zeichenfolgenvergleiche für Vorabversionskomponenten zwischen Groß- und Kleinschreibung. Dies bedeutet, dass 1.0.0-alpha und 1.0.0-Alpha gleich sind.