Controllo delle versioni

Una libreria software è raramente completa nella versione 1.0. Le librerie valide si evolvono nel tempo, aggiungendo funzionalità, correggendo i bug e migliorando le prestazioni. È importante rilasciare nuove versioni di una libreria .NET senza interrompere gli utenti esistenti.

Modifiche che rompono la compatibilità

Per informazioni sulla gestione delle modifiche che interrompono la compatibilità tra le versioni, vedere Modifiche che interrompono la compatibilità.

Numeri di versione

Una libreria .NET offre molti modi per specificare una versione. Queste versioni sono le più importanti:

• versione del pacchetto NuGet
• Versione assemblaggio
• versione del file assembly
• versione informativa dell'assembly

Versione del pacchetto NuGet

La versione del pacchetto NuGet viene visualizzata in NuGet.org e nella gestione pacchetti NuGet di Visual Studio e viene aggiunta al codice sorgente quando viene usato il pacchetto. La versione del pacchetto NuGet è il numero di versione comunemente usato dagli utenti e a cui fanno riferimento quando parlano della versione di una libreria in uso. La versione del pacchetto NuGet viene usata da NuGet e non ha alcun effetto sul comportamento di runtime.

<PackageVersion>1.0.0-alpha1</PackageVersion>

L'identificatore del pacchetto NuGet combinato con la versione del pacchetto NuGet viene usato per identificare un pacchetto in NuGet. Ad esempio, Newtonsoft.Json + 11.0.2. Un pacchetto con un suffisso è un pacchetto non definitivo e possiede un comportamento speciale che lo rende ideale per i test. Per ulteriori informazioni, vedere i pacchetti prerilasciati.

Poiché la versione del pacchetto NuGet è la versione più visibile per gli sviluppatori, è consigliabile aggiornarla usando SemVer (Semantic Versioning). SemVer indica il significato delle modifiche tra le versioni e aiuta gli sviluppatori a prendere una decisione informata quando si sceglie quale versione usare. Ad esempio, passando da 1.0 a 2.0 indica che sono state apportate modifiche potenzialmente di rilievo.

✔️ È consigliabile usare SemVer 2.0.0 per la versione del pacchetto NuGet.

✔️ Usare la versione del pacchetto NuGet nella documentazione pubblica perché è il numero di versione comunemente visualizzato dagli utenti.

✔️ DO include un suffisso di versione preliminare quando si rilascia un pacchetto non stabile. Per ulteriori informazioni sul contrassegno delle API come anteprima o sperimentale, consultare Preview APIs.

Gli utenti devono dare il loro consenso esplicito per ottenere pacchetti in versione prerelease, per comprendere che il pacchetto non è completo.

Versione dell'assembly

La versione dell'assembly è quella usata da CLR in fase di esecuzione per selezionare la versione di un assembly da caricare. La selezione di un assembly tramite il controllo delle versioni si applica solo agli assembly con un nome sicuro.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

Il CLR di .NET Framework richiede una corrispondenza esatta per caricare un assembly fortemente nominato. Ad esempio, Library1, Version=1.0.0.0 è stato compilato con un riferimento a Newtonsoft.Json, Version=11.0.0.0. .NET Framework caricherà solo la versione esatta 11.0.0.0. Per caricare una versione diversa in fase di esecuzione, è necessario aggiungere un reindirizzamento dell'associazione al file di configurazione dell'applicazione .NET.

La denominazione avanzata combinata con la versione dell'assembly consente caricamento rigoroso della versione dell'assembly. Anche se la forte denominazione di una libreria offre numerosi vantaggi, spesso genera eccezioni in fase di esecuzione in cui non è possibile trovare un assembly e richiede reindirizzamenti di binding in app.config o web.config per essere risolti. In .NET (Core) il caricamento degli assembly è più flessibile. Il runtime di .NET (Core) carica automaticamente gli assembly con una versione successiva in fase di esecuzione.

✔️ CONSIDERARE di includere solo una versione principale in "AssemblyVersion".

Ad esempio, la Libreria 1.0 e la Libreria 1.0.1 hanno entrambe un AssemblyVersion di 1.0.0.0, mentre la Libreria 2.0 ha AssemblyVersion di 2.0.0.0. Quando la versione dell'assembly cambia meno spesso, riduce i reindirizzamenti di collegamento.

✔️ CONSIDERARE la sincronizzazione del numero di versione principale di AssemblyVersion e della versione del pacchetto NuGet.

L'AssemblyVersion è inclusa in alcuni messaggi informativi mostrati all'utente, ad esempio il nome dell'assembly e i nomi dei tipi qualificati dell'assembly nei messaggi di eccezione. La gestione di una relazione tra le versioni fornisce altre informazioni agli sviluppatori sulla versione in uso.

❌ NON hanno una AssemblyVersion fissa.

Anche se una AssemblyVersion non modificabile evita la necessità di reindirizzamenti di binding, significa che solo una singola versione dell'assembly può essere installata nella Global Assembly Cache (GAC). Inoltre, se un'altra applicazione aggiorna l'assembly GAC con modifiche che interrompono la compatibilità, le applicazioni che fanno riferimento all'assembly nella GAC si interromperanno.

Versione del file di assemblaggio

La versione del file di assembly viene usata per visualizzare una versione del file in Windows e non ha alcun effetto sul comportamento in fase di esecuzione. L'impostazione di questa versione è facoltativa. È visibile nella finestra di dialogo Proprietà file in Esplora risorse:

<FileVersion>11.0.2.21924</FileVersion>

✔️ PRENDERE IN CONSIDERAZIONE l'inclusione di un numero di build di integrazione continua come revisione di AssemblyFileVersion.

Ad esempio, si sta compilando la versione 1.0.0 del progetto e il numero di build di integrazione continua è 99 in modo che AssemblyFileVersion sia 1.0.0.99.

✔️ Usare il formato Major.Minor.Build.Revision per la versione del file.

Anche se la versione del file non viene mai usata da .NET, Windows prevede che la versione del file sia nel formato Major.Minor.Build.Revision. Se la versione non segue questo formato, viene generato un avviso.

Versione informativa dell'assembly

La versione informativa dell'assembly viene usata per registrare informazioni aggiuntive sulla versione e non ha alcun effetto sul comportamento di runtime. L'impostazione di questa versione è facoltativa. Se si utilizza Source Link, questa versione verrà impostata durante la compilazione con la versione del pacchetto NuGet più una versione del controllo del codice sorgente. Ad esempio, 1.0.0-beta1+204ff0a include l'hash di commit del codice sorgente da cui è stato compilato l'assembly. Per ulteriori informazioni, vedere il link alla fonte .

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

❌ EVITARE di impostare manualmente la versione informativa dell'assembly.

Consenti a SourceLink di generare automaticamente la versione contenente i metadati del controllo del codice sorgente e NuGet.