Condividi tramite

Selezionare la versione di .NET da usare

  • Articolo

Questo articolo illustra i criteri usati dagli strumenti, dall'SDK e dal runtime di .NET per la selezione delle versioni. Questi criteri offrono un equilibrio tra le applicazioni in esecuzione usando le versioni specificate e semplificando l'aggiornamento di computer per sviluppatori e utenti finali. Questi criteri abilitano:

  • Distribuzione semplice ed efficiente di .NET, inclusi gli aggiornamenti della sicurezza e dell'affidabilità.
  • Usare gli strumenti e i comandi più recenti indipendentemente dal runtime di destinazione.

Si verifica la selezione della versione:

Il resto di questo documento esamina questi quattro scenari.

L'SDK usa la versione installata più recente

I comandi SDK includono dotnet new e dotnet run. La .NET CLI deve scegliere la versione dell'SDK per ogni comando dotnet. Usa l'SDK più recente installato nel computer per impostazione predefinita, anche se:

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

È possibile sfruttare le funzionalità e i miglioramenti più recenti dell'SDK, specificando le versioni precedenti del runtime .NET. È possibile usare versioni di runtime diverse di .NET usando gli stessi strumenti SDK.

In alcune circostanze, potrebbe essere necessario usare una versione specifica dell'SDK. Specificare tale versione in un file global.json.

global.json possono essere posizionati in qualsiasi punto della gerarchia di file. È possibile controllare i progetti a cui si applica un determinato global.json in base alla relativa posizione nel file system. L'interfaccia della riga di comando di .NET cerca un file global.json in modo iterativo passando verso l'alto dalla directory di lavoro corrente , che non corrisponde necessariamente alla directory del progetto. Il primo file global.json trovato specifica la versione usata. Se la versione dell'SDK è installata, viene usata tale versione. Se l'SDK specificato nel global.json non viene trovato, l'interfaccia della riga di comando di .NET usa regole di corrispondenza per selezionare un SDK compatibile o non riesce se non viene trovato alcuno.

L'esempio seguente illustra la sintassi global.json:

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

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

  1. dotnet cerca un file global.json navigando iterativamente all'indietro lungo il percorso dalla directory di lavoro corrente verso l'alto.
  2. dotnet usa l'SDK specificato nel primo global.json trovato.
  3. dotnet usa l'SDK installato più recente se non viene trovato alcun global.json.

Per ulteriori informazioni sulla selezione della versione dell'SDK, vedere le sezioni Regole di corrispondenza e rollForward dell'articolo di panoramica global.json.

Aggiornamento della versione dell'SDK

È importante eseguire regolarmente l'aggiornamento alla versione più recente dell'SDK per adottare le funzionalità, i miglioramenti delle prestazioni e le correzioni di bug più recenti. Per verificare facilmente la disponibilità di aggiornamenti dell'SDK, usare il comando dotnet sdk check. Inoltre, se si seleziona una versione specifica usando global.json, prendere in considerazione uno strumento come Dependabot per aggiornare automaticamente la versione fissata dell'SDK al rilascio di nuove versioni.

I moniker del framework di destinazione definiscono le API in fase di compilazione

Il progetto viene compilato in base alle API definite in un moniker del framework di destinazione (TFM). Specifichi il framework di destinazione 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 in più TFM. L'impostazione di più framework di destinazione è più comune per le librerie, ma può essere eseguita anche con le applicazioni. Si specifica 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>

Un SDK specifico supporta un set fisso di framework, limitato al framework di destinazione del runtime fornito con . Ad esempio, .NET 8 SDK include il runtime .NET 8, che è un'implementazione del framework di destinazione net8.0. .NET 8 SDK supporta net7.0, net6.0e net5.0, ma non net9.0 (o versione successiva). Installa il .NET 9 SDK per compilare per net9.0.

.NET Standard

.NET Standard è stato un modo per definire come destinazione una superficie API condivisa da diverse implementazioni di .NET. A partire dalla versione di .NET 5, che è uno standard API stesso, .NET Standard ha poca rilevanza, ad eccezione di uno scenario: .NET Standard è utile quando si vuole usare sia .NET che .NET Framework. .NET 5 implementa tutte le versioni di .NET Standard.

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

Aggiornamento 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 eseguibile dipendente dal framework con myapp.exe, l'eseguibile dotnet funge da host per l'applicazione.

L'host sceglie la versione della patch più recente installata nel computer. Ad esempio, se è 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.*. Ad esempio, se è stato specificato net5.0 e viene installato solo 5.1.0, l'applicazione viene eseguita usando il runtime di 5.1.0. Questo comportamento viene definito "roll-forward della versione minore". Anche le versioni inferiori non verranno considerate. Quando non viene installato alcun runtime accettabile, l'applicazione non verrà eseguita.

Alcuni esempi di utilizzo illustrano il comportamento, se la destinazione è 5.0:

  • ✔️ È specificato 5.0. 5.0.3 è la versione di patch più recente installata. Viene usata la versione 5.0.3.
  • "❌ 5.0 è specificato." Non sono installate versioni 5.0.* . 3.1.1 è il runtime più alto installato. Viene visualizzato un messaggio di errore.
  • ✔️ È specificato 5.0. Non sono installate versioni 5.0.* . 5.1.0 è la versione di runtime più recente installata. Viene usata la versione 5.1.0.
  • La versione ❌ 3.0 è specificata. Non sono installate versioni 3.x. 5.0.0 è il runtime più alto installato. Viene visualizzato un messaggio di errore.

L'avanzamento della versione secondaria ha un effetto collaterale che può influire sugli utenti finali. Si consideri lo scenario seguente:

  1. L'applicazione specifica che la versione 5.0 è obbligatoria.
  2. Quando viene eseguita, la versione 5.0.* non è installata, ma la versione 5.1.0 è. Verrà usata la versione 5.1.0.
  3. Successivamente, l'utente installa 5.0.3 ed esegue di nuovo l'applicazione, verrà usata la versione 5.0.3.

È possibile che la versione 5.0.3 e 5.1.0 si comportino in modo diverso, in particolare per scenari come la serializzazione dei dati binari.

Controllo del 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 per un'applicazione può essere configurato in quattro modi diversi:

  1. Impostazione a livello di progetto impostando la proprietà <RollForward>:

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

  2. Il file *.runtimeconfig.json.

    Questo file viene generato durante la compilazione dell'applicazione. Se la proprietà <RollForward> è stata impostata nel progetto, viene riprodotta nel file *.runtimeconfig.json come impostazione rollForward. Gli utenti possono modificare questo file per modificare il comportamento dell'applicazione.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. 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

  4. Variabile di ambiente DOTNET_ROLL_FORWARD.

Precedenza

Il comportamento di roll forward viene impostato in base all'ordine seguente quando l'app viene eseguita, gli elementi numerati più alti hanno la precedenza sugli elementi numerati inferiori:

  1. Viene innanzitutto valutato il file di configurazione *.runtimeconfig.json.
  2. Successivamente, la variabile di ambiente DOTNET_ROLL_FORWARD viene considerata, ignorando il controllo precedente.
  3. Infine, qualsiasi parametro --roll-forward passato all'applicazione in esecuzione esegue l'override di tutto il resto.

Valori

Tuttavia, qualunque sia l'impostazione di roll-forward, usa uno dei seguenti valori per definire il comportamento:

Valore Descrizione
Minor predefinito se non specificato.
Eseguire il roll forward alla versione secondaria più alta disponibile, se manca la versione secondaria richiesta. Se è presente la versione secondaria richiesta, viene usato il criterio di LatestPatch.
Major Eseguire il roll forward alla versione principale successiva disponibile e alla versione secondaria più bassa, se la versione principale richiesta è mancante. Se la versione principale richiesta è presente, viene usato il criterio di Minor.
LatestPatch Eseguire il roll forward alla versione della patch più recente. Questo valore disabilita il roll-forward della versione secondaria.
LatestMinor Eseguire il roll forward alla versione secondaria più alta, anche se è presente una versione secondaria richiesta.
LatestMajor Effettuare l'avanzamento alla versione maggiore e minore più alta, anche se è già presente la versione maggiore richiesta.
Disable Non eseguire il rollforward, ma eseguire il binding solo alla versione specificata. Questo criterio non è consigliato per l'uso generale perché disabilita la possibilità di eseguire il rollforward alle patch più recenti. Questo valore è consigliato solo per i test.

Le distribuzioni autonome includono il runtime selezionato

È possibile pubblicare un'applicazione come distribuzione autonoma . Questo approccio aggrega il runtime e le librerie .NET all'applicazione. Le distribuzioni autonome non hanno una dipendenza da ambienti di runtime. La selezione della versione di runtime viene eseguita in fase di pubblicazione, non in fase di esecuzione.

Il ripristino evento che si verifica durante la pubblicazione seleziona la versione patch più recente della famiglia di runtime specificata. Ad esempio, dotnet publish selezionerà .NET 5.0.3 se si tratta della versione più recente della patch nella famiglia di runtime .NET 5. Il framework di destinazione (incluse le patch di sicurezza installate più recenti) viene incluso nel pacchetto con l'applicazione.

Si verifica un errore se la versione minima specificata per un'applicazione non è soddisfatta. dotnet publish si collega all'ultima versione della patch di runtime (all'interno di una determinata famiglia della versione principale-secondaria). dotnet publish non supporta la semantica *roll-forward* di dotnet run. Per altre informazioni sulle patch e le distribuzioni autonome, vedere l'articolo sulla selezione delle patch di runtime nella distribuzione di applicazioni .NET.

Le distribuzioni autonome possono richiedere una versione di patch specifica. È possibile eseguire l'override della versione minima della patch di runtime (a versioni successive o precedenti) 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, il RuntimeFrameworkVersion specifica la versione esatta del framework di runtime. Per le applicazioni dipendenti dal framework, l'RuntimeFrameworkVersion specifica la versione minima richiesta del framework di runtime.

Vedere anche