panoramica di global.json

Articolo
01/10/2024

Questo articolo si applica a: ✔️ .NET Core 3.1 SDK e versioni successive

Il file global.json consente di definire la versione di .NET SDK usata quando si eseguono i comandi dell'interfaccia della riga di comando di .NET. La selezione della versione di .NET SDK è indipendente dalla specifica della versione di runtime di destinazione di un progetto. La versione di .NET SDK indica quale versione dell'interfaccia della riga di comando di .NET viene usata. Questo articolo illustra come selezionare la versione dell'SDK usando global.json.

Se si vuole usare sempre la versione più recente dell'SDK installata nel computer, non è necessario alcun file global.json. Negli scenari di CI (integrazione continua), tuttavia, in genere si vuole specificare un intervallo accettabile per la versione dell'SDK usata. Il file global.json include una funzionalità rollForward che offre modi flessibili per specificare un intervallo di versioni accettabile. Ad esempio, il file di global.json seguente seleziona 6.0.300 o qualsiasi banda di funzionalità o patch successiva per la versione 6.0 installata nel computer:

{
  "sdk": {
    "version": "6.0.300",
    "rollForward": "latestFeature"
  }
}

.NET SDK cerca un file global.json nella directory di lavoro corrente (che non corrisponde necessariamente alla directory del progetto) o a una delle directory padre.

Per informazioni su come specificare la versione di runtime anziché la versione dell'SDK, vedere Framework di destinazione.

schema global.json

SDK

Tipo: object

Specifica le informazioni su .NET SDK da selezionare.

Versione

Tipo: string

Versione di .NET SDK da utilizzare.

Questo campo:

Non dispone del supporto con caratteri jolly; vale a dire, è necessario specificare il numero di versione completo.
Non supporta gli intervalli di versione.

allowPrerelease

Tipo: boolean
Disponibile a partire da: .NET Core 3.0 SDK.

Indica se il resolver SDK deve prendere in considerazione le versioni non definitive quando si seleziona la versione dell'SDK da usare.

Se non si imposta questo valore in modo esplicito, il valore predefinito dipende dal fatto che si esegua da Visual Studio:

Se non si è in Visual Studio, il valore predefinito è true.
Se si usa Visual Studio, viene usato lo stato di versione non definitiva richiesta. Ciò significa che se si usa una versione di anteprima di Visual Studio o si imposta l'opzione Usare le anteprime dell'opzione .NET SDK (in Tools>Opzioni>Ambiente>Anteprima funzionalità), il valore predefinito è true. In caso contrario, il valore predefinito è false.

rollForward

Tipo: string
Disponibile a partire da: .NET Core 3.0 SDK.

I criteri di roll forward da usare quando si seleziona una versione dell'SDK, sia come fallback quando manca una versione specifica dell'SDK sia come direttiva per usare una versione successiva. È necessario specificare una versione con un valore rollForward, a meno che non venga impostata su latestMajor. Il comportamento di roll forward predefinito è determinato dalle regole di corrispondenza.

Per comprendere i criteri disponibili e il relativo comportamento, prendere in considerazione le definizioni seguenti per una versione dell'SDK nel formato x.y.znn:

x è la versione principale.
y è la versione secondaria.
z è la banda caratteristica.
nn è la versione patch.

La tabella seguente illustra i valori possibili per la chiave rollForward:

Valore	Comportamento
`patch`	Usa la versione specificata. Se non viene trovato, esegue il roll forward al livello di patch più recente. Se non viene trovato, ha esito negativo. Questo valore è il comportamento legacy delle versioni precedenti dell'SDK.
`feature`	Usa il livello di patch più recente per la banda principale, secondaria e di funzionalità specificata. Se non viene trovato, esegue il roll forward alla successiva banda di funzionalità superiore all'interno dello stesso livello principale/secondario e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, ha esito negativo.
`minor`	Usa il livello di patch più recente per la banda principale, secondaria e di funzionalità specificata. Se non viene trovato, esegue il roll forward alla successiva banda di funzionalità superiore all'interno della stessa versione principale/secondaria e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, esegue il roll forward alla successiva banda secondaria e di funzionalità superiore all'interno della stessa major e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, ha esito negativo.
`major`	Usa il livello di patch più recente per la banda principale, secondaria e di funzionalità specificata. Se non viene trovato, esegue il roll forward alla successiva banda di funzionalità superiore all'interno della stessa versione principale/secondaria e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, esegue il roll forward alla successiva banda secondaria e di funzionalità superiore all'interno della stessa major e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, esegue il roll forward alla successiva banda principale, secondaria e di funzionalità superiore, e usa il livello di patch più recente per tale banda di funzionalità. Se non viene trovato, ha esito negativo.
`latestPatch`	Usa il livello di patch installato più recente che corrisponde alla banda principale, secondaria e di funzionalità richiesta con un livello di patch maggiore o uguale al valore specificato. Se non viene trovato, ha esito negativo.
`latestFeature`	Usa il livello di banda di funzionalità e patch installato più alto che corrisponde alle versioni principale e secondaria richiesta con una banda di funzionalità e un livello di patch maggiore o uguale al valore specificato. Se non viene trovato, ha esito negativo.
`latestMinor`	Usa il livello secondario, di banda di funzionalità e patch installato più alto che corrisponde alle versioni principale e secondaria richiesta con una banda di funzionalità e un livello di patch maggiore o uguale al valore specificato. Se non viene trovato, ha esito negativo.
`latestMajor`	Usa l'SDK .NET più installato con una versione maggiore o uguale al valore specificato. Se non viene trovato, ha esito negativo.
`disable`	Non esegue il roll forward. È necessaria una corrispondenza esatta.

msbuild-sdks

Tipo: object

Consente di controllare la versione dell'SDK del progetto in un'unica posizione anziché in ogni singolo progetto. Per altre informazioni, vedere Come vengono risolti gli SDK del progetto.

Commenti in global.json

I commenti nei file global.json sono supportati usando commenti in stile JavaScript o C#. Ad esempio:

{
   // This is a comment.
  "sdk": {
    "version": "7.0.100" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Esempi

L'esempio seguente illustra come non usare le versioni non definitive:

{
  "sdk": {
    "allowPrerelease": false
  }
}

Nell'esempio seguente viene illustrato come usare la versione più recente installata maggiore o uguale alla versione specificata. Il codice JSON mostrato non consente alcuna versione dell'SDK precedente alla 2.2.200 e consente la versione 2.2.200 o successiva, inclusi 3.0.xxx e 3.1.xxx.

{
  "sdk": {
    "version": "2.2.200",
    "rollForward": "latestMajor"
  }
}

L'esempio seguente illustra come usare la versione specificata esatta:

{
  "sdk": {
    "version": "3.1.100",
    "rollForward": "disable"
  }
}

L'esempio seguente illustra come usare la versione più recente del gruppo di funzionalità e della patch installata di una versione principale e secondaria specifica. Il codice JSON mostrato non consente alcuna versione dell'SDK precedente alla 3.1.102 e consente la versione 3.1.102 o successiva 3.1.xxx, ad esempio 3.1.103 o 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestFeature"
  }
}

Nell'esempio seguente viene illustrato come usare la versione della patch più recente installata di una versione specifica. Il codice JSON mostrato non consente alcuna versione dell'SDK precedente alla 3.1.102 e consente la versione 3.1.102 o successiva 3.1.1xx, ad esempio 3.1.103 o 3.1.199.

{
  "sdk": {
    "version": "3.1.102",
    "rollForward": "latestPatch"
  }
}

global.json e l'interfaccia della riga di comando di .NET

Per impostare una versione dell'SDK nel file global.json, è utile sapere quali versioni dell'SDK sono installate nel computer. Per informazioni su come eseguire questa operazione, vedere Come verificare che .NET sia già installato.

Per installare altre versioni di .NET SDK nel computer, visitare la pagina Scaricare .NET.

È possibile creare un nuovo file global.json nella directory corrente eseguendo il comando dotnet new, simile all'esempio seguente:

dotnet new globaljson --sdk-version 6.0.100

Regole di corrispondenza

Nota

Le regole di corrispondenza sono regolate dal punto di ingresso dotnet.exe, comune in tutti i runtime di .NET installati. Le regole di corrispondenza per la versione installata più recente del runtime .NET vengono usate quando sono installati più runtime side-by-side o se si usa un file global.json.

Quando si determina quale versione dell'SDK usare, si applicano le regole seguenti:

Se non viene trovato alcun file global.json o global.json non specifica una versione SDK né un valore allowPrerelease, viene usata la versione più alta dell'SDK installata (equivalente all'impostazione di rollForward su latestMajor). L'eventuale presa in considerazione delle versioni non definitive dell'SDK dipende dal modo in cui viene richiamato dotnet:
- Se non si è in Visual Studio, vengono considerate le versioni non definitive.
- Se si usa Visual Studio, viene usato lo stato di versione non definitiva richiesta. Ciò significa che se si usa una versione di anteprima di Visual Studio o si imposta l'opzione Usa anteprime di .NET SDK (in Strumenti>Opzioni>Ambiente>Funzionalità di anteprima), vengono considerate le versioni non definitive. In caso contrario, vengono considerate solo le versioni di rilascio.
Se viene trovato un file global.json che non specifica una versione dell'SDK ma specifica un valore allowPrerelease, viene usata la versione più recente dell'SDK installata (equivalente all'impostazione di rollForward su latestMajor). Che la versione più recente dell'SDK possa essere rilasciata o non definitiva dipende dal valore di allowPrerelease. true indica che vengono considerate le versioni non definitive; false indica che vengono considerate solo le versioni di rilascio.
Se viene trovato un file global.json e viene specificata una versione dell'SDK:
- Se non viene impostato alcun valore rollForward, usa latestPatch come criterio di rollForward predefinito. In caso contrario, controllare ogni valore e il relativo comportamento nella sezione rollForward.
- La sezione allowPrerelease descrive se le versioni non definitive vengono considerate e qual è il comportamento predefinito quando allowPrerelease non è impostato.

Risolvere i problemi relativi agli avvisi di compilazione

Gli avvisi seguenti indicano che il progetto è stato compilato usando una versione non definitiva di .NET SDK:

Si sta lavorando con una versione di anteprima di .NET Core SDK. È possibile definire la versione SDK tramite un file global.json nel progetto corrente. Per altre informazioni, vedere https://go.microsoft.com/fwlink/?linkid=869452.

Si usa una versione di anteprima di .NET. Vedere: https://aka.ms/dotnet-core-preview

Le versioni di .NET SDK hanno una cronologia e un impegno di qualità elevata. Tuttavia, se non si vuole usare una versione non definitiva, controllare le diverse strategie che è possibile usare nella sezione allowPrerelease. Per i computer che non hanno mai installato un runtime o un SDK di .NET Core 3.0 o versione successiva, è necessario creare un file global.json e specificare la versione esatta da usare.
L'avviso seguente indica che il progetto è destinato a EF Core 1.0 o 1.1, che non è compatibile con .NET Core 2.1 SDK e versioni successive:

Progetto di avvio '{startupProject}' framework di destinazione '.NETCoreApp' versione '{targetFrameworkVersion}'. Questa versione degli strumenti della riga di comando di Entity Framework Core .NET supporta solo la versione 2.0 o successive. Per informazioni sull'uso di versioni precedenti degli strumenti, vedere https://go.microsoft.com/fwlink/?linkid=871254.

A partire da .NET Core 2.1 SDK (versione 2.1.300), il comando dotnet ef è incluso nell'SDK. Per compilare il progetto, installare .NET Core 2.0 SDK (versione 2.1.201) o versioni precedenti nel computer e definire la versione dell'SDK desiderata usando il file global.json. Per altre informazioni sul comando dotnet ef, vedere Strumenti da riga di comando di EF Core .NET.
Se si usa global.json per rimanere in una versione specifica di .NET SDK, si noti che Visual Studio installa una sola copia di .NET SDK. Pertanto, se si aggiorna la versione di Visual Studio, viene rimossa la versione precedente di .NET SDK usata per installare la nuova versione. Rimuove la versione precedente anche se si tratta di una versione principale diversa di .NET.

Per evitare la rimozione di versioni di .NET SDK da Visual Studio, è necessario installare .NET SDK autonomo dalla pagina di download. Si noti che, in questo caso, non si otterranno più aggiornamenti automatici a tale versione di .NET SDK tramite Visual Studio e potrebbero essere a rischio di problemi di sicurezza.

Vedi anche

Come vengono risolti gli SDK di progetto