Controllo delle versioni dei pacchetti

Viene sempre fatto riferimento a un pacchetto specifico usando l'identificatore del pacchetto e un numero di versione esatto. Ad esempio, Entity Framework in nuget.org include diverse decine di pacchetti specifici disponibili, dalla versione 4.1.1.1031 1 alla versione 6.1.3 (la versione stabile più recente) e da diverse 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 facoltativo non rilasciato. Quando si utilizzano pacchetti, invece, è possibile specificare un numero di versione esatto o un intervallo di versioni accettabili.

Il documento seguente segue lo standard versione semantica 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.

In questo argomento:

• nozioni di base sulla versione inclusi i suffissi di versione non definitiva.
• Intervalli di versioni
• numeri di versione normalizzati
• controllo delle versioni semantiche 2.0.0

Nozioni di base sulla versione

Un numero di versione specifico è nel formato Major.Minor.Patch[-Suffix], dove i componenti hanno i significati seguenti:

• principali: modifiche di rilievo
• secondaria: nuove funzionalità, ma compatibili con le versioni precedenti
• Patch: correzioni di bug compatibili con le versioni precedenti
• -Suffisso (facoltativo): trattino seguito da una stringa che indica una versione non definitiva (seguendo la convenzione di semantica versioning o SemVer).

esempi di :

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta.1

Importante

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

Versioni non definitive

Tecnicamente, gli autori di pacchetti possono usare qualsiasi stringa come suffisso per indicare una versione non definitiva, in quanto NuGet considera qualsiasi versione come una versione non definitiva e non esegue altre interpretazioni. Ovvero, NuGet visualizza la stringa di versione completa in qualsiasi interfaccia utente coinvolta, lasciando qualsiasi interpretazione del significato del suffisso al consumer.

Detto questo, gli sviluppatori di pacchetti seguono in genere convenzioni di denominazione riconosciute:

• -alpha: versione alfa, in genere usata per la sperimentazione e il lavoro in corso.
• -beta: versione beta, in genere una funzionalità completa per la versione pianificata successiva, ma può contenere bug noti.
• -rc: versione candidata, in genere una versione potenzialmente finale (stabile) a meno che 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 preliminare con notazione punto, come in 1.0.1-build.23, sono considerati parte del SemVer 2.0.0 standard 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.

1.0.1
1.0.1-zzz
1.0.1-open
1.0.1-beta05
1.0.1-beta02
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

Si noti che le versioni come 1.0.1-rc.10 e 1.0.1-rc.2 non sono analizzabili dalle versioni precedenti del client e tali pacchetti con tali versioni non saranno disponibili per il download con tali client.

Se si usano suffissi numerici con tag di versione non definitive che potrebbero usare numeri a due cifre (o più), usare zere iniziali come in beta01 e beta05 per assicurarsi che vengano ordinati correttamente quando i numeri aumentano. Questa raccomandazione applica solo questo schema.

Nonostante l'ordinamento illustrato in precedenza, NuGet non considera sempre sia i pacchetti stabili & versioni non definitive durante la risoluzione delle dipendenze. Queste regole sono descritte in dettaglio in risoluzione delle dipendenze.

Intervalli di versioni

Quando si fa riferimento alle dipendenze dei pacchetti, NuGet supporta l'uso della notazione intervallo per specificare gli intervalli di versioni, 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 mista ed esclusiva massima
(1.0)	Non valido	Non valido

Procedura consigliata

Specificare sempre un intervallo di versione o di versione per le dipendenze dei pacchetti nei file di progetto, nei file di packages.config e nei file di .nuspec. Senza una versione o un intervallo di versioni, quando si risolve una dipendenza, i risultati di ripristino coerenti non sono garantiti. Evitare di specificare un limite superiore agli intervalli di versioni per i pacchetti di cui non si è proprietari, a meno che non si conosca un problema di compatibilità. I limiti superiori agli intervalli di versioni danneggiano l'adozione, scoraggiano gli utenti a ottenere aggiornamenti importanti alle dipendenze e in alcuni casi possono causare l'uso di versioni non supportate delle dipendenze.

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.configogni dipendenza viene elencata con un attributo version esatto usato per il ripristino dei pacchetti. L'attributo allowedVersions viene usato solo durante le operazioni di aggiornamento per vincolare le versioni a cui potrebbe essere aggiornato il 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 dell'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+ considera i numeri di versione come segue:

• Gli zere 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

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

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

Controllo delle versioni semantiche 2.0.0

Alcune semantiche di SemVer v2.0.0 non sono supportate nei client meno recenti. NuGet considera una versione del pacchetto come SemVer v2.0.0 specifica se una delle istruzioni seguenti è vera:

• L'etichetta non rilasciata è delimitata 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 v2.0.0 se una delle istruzioni seguenti è vera:

• La versione del pacchetto è conforme a SemVer v2.0.0, ma non è conforme a SemVer v1.0.0, come definito in precedenza.
• Qualsiasi intervallo di versioni delle dipendenze del pacchetto ha una versione minima o massima conforme a SemVer v2.0.0, ma non conforme a SemVer v1.0.0, definita in precedenza; ad esempio [1.0.0-alpha.1, ).

Se si carica un pacchetto specifico di SemVer v2.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

Per usare a livello di codice le versioni dei pacchetti NuGet, è consigliabile usare pacchetto NuGet.Versioning. Il metodo statico NuGetVersion.Parse(string) può essere usato per analizzare le stringhe di versione e VersionComparer può essere usato per ordinare NuGetVersion 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 e 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. Come descritto 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 rilasciati. Ciò significa che 1.0.0-alpha e 1.0.0-Alpha sono uguali.