Controllo delle versioni dei pacchetti

  • Articolo

A un pacchetto specifico viene sempre fatto riferimento usando l'identificatore del pacchetto e un numero di versione esatto. Per Entity Framework su nuget.org, ad esempio, sono disponibili alcune decine di pacchetti specifici, compresi tra la versione 4.1.10311 e la versione 6.1.3 (la versione stabile più recente) e svariate versioni non definitive come 6.2.0-beta1.

Quando si crea un pacchetto, si assegna un numero di versione specifico con un suffisso di testo per la versione non definitiva facoltativo. Quando si utilizzano i pacchetti, invece, è possibile specificare un numero di versione esatto o un intervallo di versioni accettabili.

Il documento seguente segue lo standard Semantic Versioning 2.0.0 , supportato da NuGet 4.3.0+ e Visual Studio 2017 versione 15.3+. Alcune semantiche di SemVer v2.0.0 non sono supportate nei client meno recenti.

Contenuto dell'argomento:

Nozioni di base sulle versioni

Un numero di versione specifico è nel formato Principale.Secondaria.Patch[-Suffisso], dove i singoli componenti hanno i significati seguenti:

  • Principale: modifiche di rilievo
  • Secondaria: nuove funzionalità, ma compatibili con le versioni precedenti
  • Patch: correzioni di bug compatibili con le versioni precedenti solo
  • -Suffisso (facoltativo): un trattino seguito da una stringa che indica una versione non definitiva (seguendo la convenzione Semantic Versioning o SemVer ).

Esempi:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Importante

nuget.org rifiuta il caricamento di un pacchetto senza un numero di versione esatto. La versione deve essere specificata nel file .nuspec o nel file di progetto usato per creare il pacchetto.

Versioni non definitive

Dal punto di vista tecnico, i creatori di pacchetti possono usare qualsiasi stringa come suffisso per indicare una versione non definitiva, perché NuGet considera una versione con questa caratteristica non definitiva senza altre interpretazioni. In altre parole, NuGet visualizza la stringa di versione completa in qualsiasi interfaccia utente, lasciando l'interpretazione del significato del suffisso all'utente.

Ciò premesso, gli sviluppatori di pacchetti seguono generalmente convenzioni di denominazione riconosciute:

  • -alpha: versione alfa, in genere usata per il lavoro in corso e la sperimentazione.
  • -beta: versione beta, in genere completa dal punto di vista funzionale per il successivo rilascio pianificato, ma può contenere bug noti.
  • -rc: versione finale candidata, in genere potenzialmente finale (stabile) se non emergono bug significativi.

Quando si ordinano le versioni in base alla precedenza, NuGet segue lo standard SemVer e sceglie prima una versione senza suffisso, quindi applica la precedenza alle versioni non definitive in ordine alfabetico inverso e tratta numeri di notazione punto con ordine numerico.

Nota

I numeri di versione non definitiva con notazione punto, come nella versione 1.0.1-build.23, sono considerati parte dello standard SemVer 2.0.0 e di conseguenza sono supportati solo con 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

Si noti che 1.0.1-alpha10 è ordinato rigorosamente in ordine alfabetico inverso, mentre 1.0.1-rc.10 è maggiore della precedenza di 1.0.1-rc.2.

Intervalli di versioni

Quando si fa riferimento alle dipendenze dei pacchetti, NuGet supporta l'uso della notazione con intervallo per specificare gli intervalli di versione, riepilogati come segue:

Notazione Regola applicata Descrizione
1.0 x ≥ 1.0 Versione minima, inclusiva
[1.0,) x ≥ 1.0 Versione minima, inclusiva
(1.0,) x > 1.0 Versione minima, esclusiva
[1.0] x == 1.0 Corrispondenza esatta della versione
(,1.0] x ≤ 1.0 Versione massima, inclusiva
(,1.0) x < 1.0 Versione massima, esclusiva
[1.0,2.0] 1.0 ≤ x ≤ 2.0 Intervallo esatto, inclusivo
(1.0,2.0) 1.0 < x < 2.0 Intervallo esatto, esclusivo
[1.0,2.0) 1.0 ≤ x < 2.0 Versione minima inclusiva e massima esclusiva mista
(1.0) non valido non valido

Esempi

Specificare sempre una versione o un intervallo di versioni per le dipendenze dei pacchetti nei file di progetto, nei file packages.config e nei file .nuspec. Senza una versione o un intervallo di versioni, NuGet 2.8.x e versioni precedenti scelgono la versione più recente del pacchetto disponibile durante la risoluzione di una dipendenza, mentre NuGet 3.x e versioni successive scelgono la versione del pacchetto più bassa. La specifica di una versione o di un intervallo di versioni evita questa incertezza.

Riferimenti nei file di progetto (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)" />

Riferimenti in packages.config:

In packages.config ogni dipendenza viene elencata con un attributo version esatto usato durante il ripristino dei pacchetti. L'attributo allowedVersions viene usato solo durante le operazioni di aggiornamento per vincolare le versioni per l'aggiornamento del pacchetto.

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

Riferimenti nei file .nuspec

L'attributo version in un elemento <dependency> descrive le versioni di intervallo accettabili per una dipendenza.

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

Numeri di versione normalizzati

Nota

Si tratta di una modifica che causa un'interruzione per NuGet 3.4+.

Quando si ottengono pacchetti da un repository durante le operazioni di installazione, reinstallazione o ripristino, NuGet 3.4+ gestisce i numeri di versione come segue:

  • Gli zeri iniziali vengono rimossi dai numeri di versione:

    • 1.00 viene considerato come 1.0
    • 1.01.1 viene considerato come 1.1.1
    • 1.00.0.1 viene considerato come 1.0.0.1

  • uno zero nella quarta parte del numero di versione verrà omesso

    • 1.0.0.0 viene considerato come 1.0.0
    • 1.0.01.0 viene considerato come 1.0.1

  • I metadati di compilazione semVer 2.0.0 vengono rimossi

    • 1.0.7+r3456 viene considerato come 1.0.7

Le operazioni pack e restore normalizzano le versioni quando possibile. Per i pacchetti già compilati, la normalizzazione non influisce sui numeri di versione dei pacchetti stessi, ma influisce solo sul modo in cui NuGet abbina le versioni durante la risoluzione delle dipendenze.

Tuttavia, i repository di pacchetti NuGet devono gestire questi valori nello stesso modo di NuGet per evitare la duplicazione della versione del pacchetto. Un repository che contiene la versione 1.0 di un pacchetto non deve inoltre ospitare la versione 1.0.0 come pacchetto separato e diverso.

Versionamento Semantico 2.0.0

Certe regole semantiche di SemVer 2.0.0 non sono supportate nei client meno recenti. NuGet considera la versione di un pacchetto come specifica di SemVer 2.0.0 se una delle affermazioni seguenti è vera:

  • L'etichetta della versione non definitiva è separata da punti, ad esempio 1.0.0-alpha.1
  • La versione include metadati di compilazione, ad esempio 1.0.0+githash

Per nuget.org, un pacchetto viene definito come pacchetto SemVer 2.0.0 se una delle affermazioni seguenti è vera:

  • La versione del pacchetto è conforme a SemVer 2.0.0 ma non è conforme a SemVer 1.0.0, come definito sopra.
  • Uno degli intervalli di versioni delle dipendenze del pacchetto ha una versione minima o massima conforme a SemVer 2.0.0 ma non conforme a SemVer 1.0.0, definita in precedenza. Ad esempio, [1.0.0-alpha.1, ).

Se si carica un pacchetto specifico di SemVer 2.0.0 in nuget.org, il pacchetto è invisibile ai client meno recenti e disponibile solo per i client NuGet seguenti:

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

Client di terze parti:

  • JetBrains Rider
  • Paket versione 5.0 +

Dove NuGetVersion si differenzia dal controllo delle versioni semantiche

Se si desidera usare a livello di codice le versioni dei pacchetti NuGet, è consigliabile usare il pacchetto NuGet.Versioning. Il metodo NuGetVersion.Parse(string) statico può essere usato per analizzare le stringhe di versione e VersionComparer può essere usato per ordinare NuGetVersion le istanze.

Se si implementa la funzionalità NuGet in un linguaggio che non viene eseguito in .NET, di seguito è riportato l'elenco noto delle differenze tra NuGetVersion il controllo delle versioni semantiche e i motivi per cui una libreria di controllo delle versioni semantica esistente potrebbe non funzionare per i pacchetti già pubblicati in nuget.org.

  1. NuGetVersion supporta un quarto segmento di versione, Revision, per essere compatibile con o un superset di , System.Version. Pertanto, escludendo le etichette di versione preliminare e di metadati, una stringa di versione è Major.Minor.Patch.Revision. In base alla normalizzazione della versione descritta in precedenza, se Revision è zero, viene omesso dalla stringa di versione normalizzata.
  2. NuGetVersion richiede solo la definizione del segmento principale. Tutti gli altri sono facoltativi e sono equivalenti a zero. Ciò significa che 1, 1.0, 1.0.0e 1.0.0.0 sono tutti accettati e uguali.
  3. NuGetVersion usa confronti di stringhe senza distinzione tra maiuscole e minuscole per i componenti non definitive. Ciò significa che 1.0.0-alpha e 1.0.0-Alpha sono uguali.