Selezionare la versione di .NET da usare

Articolo
02/16/2024

Questo articolo illustra i criteri usati dagli strumenti, dall'SDK e dal runtime .NET per selezionare le versioni. Questi criteri consentono di bilanciare tra l'esecuzione di applicazioni con le versioni specificate e la possibilità di aggiornare i computer sia degli sviluppatori che degli utenti finali. Questi criteri abilitano:

Distribuzione facile e veloce di .NET, inclusi gli aggiornamenti della sicurezza e per l'affidabilità.
Utilizzo degli strumenti e dei comandi più recenti indipendentemente dal runtime di destinazione.

La selezione della versione si verifica nei seguenti casi:

Quando si esegue un comando SDK, l'SDK usa la versione installata più recente.
Quando si compila un assembly, i moniker del framework di destinazione definiscono le API della fase di compilazione.
Quando si esegue un'applicazione .NET, le app che dipendono dal framework di destinazione eseguono il roll forward.
Quando si pubblica un'applicazione autonoma, le distribuzioni autonome includono il runtime selezionato.

Il resto di questo documento esamina questi quattro scenari.

L'SDK usa la versione installata più recente

I comandi dell'SDK includono dotnet new e dotnet run. L'interfaccia della riga di comando di .NET deve scegliere una versione dell'SDK per ogni comando dotnet. Per impostazione predefinita, l'interfaccia della riga di comando usa l'SDK più recente installato nel computer, anche se:

Il progetto è destinato a una versione precedente del runtime .NET.
La versione più recente di .NET SDK è una versione di anteprima.

È possibile usufruire delle funzionalità e dei miglioramenti più recenti dell'SDK anche scegliendo come destinazione versioni meno recenti del runtime .NET. È possibile sviluppare per versioni diverse del runtime .NET usando gli stessi strumenti SDK.

In casi rari potrebbe essere necessario usare una versione meno recente dell'SDK. La versione deve essere specificata in un file global.json. I criteri "uso della versione più recente" indicano che si usa solo il file global.json per specificare una versione di .NET SDK precedente all'ultima installata.

Il file global.json può essere memorizzato in un punto qualsiasi della gerarchia di file. L'interfaccia della riga di comando cerca a ritroso il primo file global.json che trova partendo dalla directory di progetto. Si controlla a quali progetti si applica un determinato file global.json in base alla sua posizione nel file system. L'interfaccia della riga di comando .NET cerca ripetutamente un file global.json esplorando il percorso a ritroso partendo dalla directory di lavoro corrente. Il primo file global.json trovato specifica la versione usata. Se quella versione dell'SDK è installata, sarà questa a essere usata. Se l'SDK specificato in global.json non viene trovato, l'interfaccia della riga di comando di .NET usa le regole di corrispondenza per selezionare un SDK compatibile. Se non lo trova, si verifica un errore.

L'esempio seguente mostra la sintassi del file global.json:

{
  "sdk": {
    "version": "5.0.0"
  }
}

Il processo per la selezione di una versione dell'SDK è il seguente:

dotnet cerca ripetutamente un file global.json risalendo il percorso a partire dalla directory di lavoro corrente.
dotnet usa l'SDK specificato nel file global.json trovato.
dotnet usa l'SDK installato più recente se non viene trovato alcun file global.json.

Per altre informazioni sulla scelta della versione dell'SDK, vedere le sezioni Regole di corrispondenza e rollForward dell'articolo Panoramica di global.json.

Definizione delle API della fase di compilazione tramite i moniker framework di destinazione

Il progetto viene compilato con le API definite in un moniker framework di destinazione (TFM). Il framework di destinazione deve essere specificato nel file di progetto. Impostare l'elemento TargetFramework nel file di progetto come illustrato nell'esempio seguente:

<TargetFramework>net8.0</TargetFramework>

È possibile compilare il progetto usando più TFM. L'impostazione di più framework di destinazione è una pratica più comune per le librerie, ma può essere usata anche con le applicazioni. Occorre specificare una proprietà TargetFrameworks (plurale di TargetFramework). I framework di destinazione sono delimitati da punto e virgola come illustrato nell'esempio seguente:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Una determinata versione di SDK supporta un set fisso di framework, inclusivo del framework di destinazione del runtime con cui viene offerto. .NET 8 SDK, ad esempio, include il runtime .NET 8, che è un'implementazione del framework di destinazione net8.0. .NET 8 SDK supporta net7.0, net6.0 e net5.0, ma non net9.0 (o versione superiore). Per la compilazione di net9.0, installare .NET 9 SDK.

.NET Standard

.NET Standard era un modo per definire come destinazione una superficie API condivisa da diverse implementazioni di .NET. A partire dal rilascio di .NET 5, che è uno standard API, .NET Standard ha poca rilevanza, tranne che per uno scenario: .NET Standard è utile quando si vuole specificare come destinazione sia .NET che .NET Framework. .NET 5 implementa tutte le versioni di .NET Standard.

Per altre informazioni, vedere .NET 5 e .NET Standard.

Roll forward delle app dipendenti dal framework

Quando si esegue un'applicazione dall'origine con dotnet run, da una distribuzione dipendente dal framework con dotnet myapp.dll o da un file eseguibile dipendente dal framework con myapp.exe, il file eseguibile dotnet è l'host dell'applicazione.

L'host sceglie la versione di patch più recente installata nel computer. Se ad esempio è stato specificato net5.0 nel file di progetto e 5.0.2 è il runtime .NET più recente installato, viene usato il runtime 5.0.2.

Se non viene trovata alcuna versione 5.0.* accettabile, viene usata una nuova versione 5.*. Se ad esempio è stato specificato net5.0 ed è installata solo la versione 5.1.0, l'applicazione viene eseguita usando il runtime 5.1.0. Questo comportamento è detto "roll forward della versione secondaria". Le versioni minori non verranno prese in considerazione. Se non è installato alcun runtime accettabile, l'applicazione non viene eseguita.

Alcuni esempi d'uso dimostrano il comportamento quando la destinazione è 5.0:

✔️ È specificata la versione 5.0. 5.0.3 è la versione di patch più recente installata. Viene usata la versione 5.0.3.
❌ È specificata la versione 5.0. Non è installata alcuna versione 5.0.*. 3.1.1 è il runtime più recente installato. Viene visualizzato un messaggio di errore.
✔️ È specificata la versione 5.0. Non è installata alcuna versione 5.0.*. 5.1.0 è la versione del runtime più recente installata. Viene usata la versione 5.1.0.
❌ È specificata la versione 3.0. Non è installata alcuna versione 3.x. 5.0.0 è il runtime più recente installato. Viene visualizzato un messaggio di errore.

Il roll forward della versione secondaria presenta un effetto collaterale che può interessare gli utenti finali. Prendi in considerazione lo scenario seguente:

L'applicazione specifica che è necessaria la versione 5.0.
Al momento dell'esecuzione non è installata la versione 5.0.* ma la versione 5.1.0. Verrà usata la versione 5.1.0.
In un secondo momento, l'utente installerà la versione 5.0.3 ed eseguirà nuovamente l'applicazione, dopodiché verrà usata la versione 5.0.3.

È possibile che le versioni 5.0.3 e 5.1.0 si comportino diversamente, in particolare per gli scenari come la serializzazione dei dati binari.

Controllare il comportamento di roll forward

Prima di eseguire l'override del comportamento di roll forward predefinito, acquisire familiarità con il livello di compatibilità del runtime .NET.

Il comportamento di roll forward di un'applicazione può essere configurato in quattro modi diversi:

A livello di progetto, configurando la proprietà <RollForward>:

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Tramite il file *.runtimeconfig.json.

Questo file viene generato quando si compila l'applicazione. Se nel progetto è stata impostata la proprietà <RollForward>, viene riprodotta nel file *.runtimeconfig.json come impostazione rollForward. Gli utenti possono modificare questo file per cambiare il comportamento dell'applicazione.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Tramite la proprietà --roll-forward <value> del comando dotnet.

Quando si esegue un'applicazione, è possibile controllare il comportamento di roll forward tramite la riga di comando:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Tramite la variabile di ambiente DOTNET_ROLL_FORWARD.

Precedenza

Il comportamento di roll forward viene impostato in base all'ordine seguente al momento dell'esecuzione dell'app. Gli elementi con numeri più alti hanno la precedenza su quelli con numeri più bassi:

Prima di tutto, viene valutato il file di configurazione *.runtimeconfig.json.
Successivamente viene considerata la variabile di ambiente DOTNET_ROLL_FORWARD, eseguendo l'override del controllo precedente.
Infine, qualsiasi parametro --roll-forward passato all'applicazione in esecuzione esegue l'override di qualsiasi altro elemento.

Valori

Comunque si configuri l'impostazione di roll forward, usare uno dei valori seguenti per impostare il comportamento:

Valore	Descrizione
`Minor`	Impostazione predefinita se non specificato. Esegue il roll forward alla versione secondaria successiva minima, se la versione secondaria richiesta non esiste. Se la versione secondaria richiesta è presente, viene usato il criterio `LatestPatch`.
`Major`	Esegue il roll forward alla versione principale successiva disponibile e alla versione secondaria minima, se la versione principale richiesta non esiste. Se la versione principale richiesta è presente, viene usato il criterio `Minor`.
`LatestPatch`	Esegue il roll forward alla versione di patch più recente. Questo valore disabilita il roll forward della versione secondaria.
`LatestMinor`	Esegue il roll forward alla versione secondaria più recente, anche se la versione secondaria richiesta è presente.
`LatestMajor`	Esegue il roll forward alla versione principale e secondaria più recente, anche se la versione principale richiesta è presente.
`Disable`	Non eseguire il roll forward, associa solo alla versione specificata. Non è consigliato usare questo criterio per scopi generali poiché disabilita la possibilità di eseguire il roll forward alle patch più recenti. Questo valore è consigliato solo a scopo di test.

Distribuzioni autonome con runtime selezionato

È possibile pubblicare un'applicazione come distribuzione autonoma. Questo approccio raggruppa il runtime e le librerie .NET con l'applicazione. Le distribuzioni autonome non hanno dipendenze dagli ambienti di runtime. La scelta della versione di runtime avviene al momento della pubblicazione non in base di esecuzione.

L'evento restore che si verifica al momento della pubblicazione seleziona la versione di patch più recente della famiglia di runtime specificata. Il comando dotnet publish ad esempio selezionerà .NET 5.0.3 se è la versione di patch più recente nella famiglia di runtime .NET 5. Il framework di destinazione (incluse le patch di sicurezza più recenti) viene fornito con l'applicazione.

Se la versione minima specificata per un'applicazione non viene soddisfatta, si verifica un errore. dotnet publish esegue l'associazione alla versione di patch di runtime più recente (nella famiglia di versioni principale.secondaria specificata). dotnet publish non supporta la semantica del roll forward di dotnet run. Per altre informazioni su patch e distribuzioni autonome, vedere l'articolo sulla selezione della patch di runtime nella distribuzione di applicazioni .NET.

Le distribuzioni autonome potrebbero richiedere una versione di patch specifica. È possibile sostituire la versione di patch di runtime minima (per versioni superiori o inferiori) nel file di progetto, come illustrato nell'esempio seguente:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

L'elemento RuntimeFrameworkVersion sostituisce i criteri di versione predefiniti. Per le distribuzioni autonome, l'elemento RuntimeFrameworkVersion specifica l'esatta versione del framework di runtime. Per le applicazioni dipendenti dal framework, l'elemento RuntimeFrameworkVersion specifica la versione di framework di runtime minima richiesta.