panoramica di global.json

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

Il file global.json consente di definire quale versione .NET SDK viene 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 .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 diglobal.json seguente seleziona 10.0.100 o qualsiasi banda di funzionalità o patch successiva per 10.0 installata nel computer:

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

Per cercare un file global.json, fare affidamento su due componenti nell'SDK di .NET. Ogni componente inizia da una posizione diversa e cerca nelle directory predecessori:

• .NET SDK muxer gestisce i comandi dell'interfaccia a riga di comando dotnet. Inizia dalla directory di lavoro corrente, che non corrisponde necessariamente alla directory del progetto.
• .NET resolver SDK del progetto MSBuild risolve gli SDK di progetto durante le compilazioni. Viene avviato dalla directory che contiene un file di soluzione, se presente. Se non esiste alcun file di soluzione, viene avviato dalla directory che contiene il file di progetto corrente. Se nessun file esiste, usa la directory di lavoro corrente.

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

schema del file global.json

sdk

Tipo: object

Specifica le informazioni sull'SDK di .NET da selezionare.

version

• Tipo: string

Versione dell'SDK di .NET da usare.

Questo campo:

• Richiede il numero di versione completo, ad esempio 10.0.100.
• Non supporta numeri di versione come 10, 10.0 o 10.0.x.
• Non dispone del supporto con caratteri jolly.
• 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 si è not in Visual Studio, il valore predefinito è true.
• Se ci si trova in Visual Studio, usa lo stato di versione preliminare richiesto. Cioè, se si usa una versione di anteprima di Visual Studio o si imposta l'opzione Usare le anteprime dell'SDK .NET (in Tools>Options>Environment>Preview Features), 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 minore.
• z è la banda caratteristica.
• nn è la versione patch.

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

Value	Behavior
patch	Usa la versione specificata. Se non viene trovato, esegue il roll forward al livello di patch più recente. Se non viene trovato, fallisce. 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, passa alla successiva banda di funzionalità di livello superiore all'interno dello stesso livello principale/minore e utilizza il livello di patch più recente per quella specifica banda di funzionalità. Se non viene trovato, fallisce.
minor	Usa il livello di patch più recente per la banda principale, secondaria e di funzionalità specificata. Se non viene trovato, passa avanti al successivo gruppo di funzionalità superiore all'interno della stessa versione maggiore/minore e utilizza il livello di patch più recente per tale gruppo di funzionalità. Se non viene trovato, avanza al successivo livello minore e di funzionalità superiore all'interno della stessa versione principale e utilizza il livello di patch più recente per tale livello di funzionalità. Se non viene trovato, fallisce.
major	Usa il livello di patch più recente per la banda principale, secondaria e di funzionalità specificata. Se non viene trovato, passa avanti al successivo gruppo di funzionalità superiore all'interno della stessa versione maggiore/minore e utilizza il livello di patch più recente per tale gruppo di funzionalità. Se non viene trovato, avanza al successivo livello minore e di funzionalità superiore all'interno della stessa versione principale e utilizza il livello di patch più recente per tale livello di funzionalità. Se non viene trovato, passa alla banda successiva principale, secondaria e di funzionalità, e usa il livello di patch più recente per quella banda di funzionalità. Se non viene trovato, fallisce.
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, fallisce.
latestFeature	Usa la più alta banda di funzionalità e livello di patch installati che corrispondono alle versioni principale e secondaria richieste, con una banda di funzionalità e un livello di patch maggiori o uguali al valore specificato. Se non viene trovato, fallisce.
latestMinor	Usa il minor, la banda di funzionalità e il livello di patch installati più alti che corrispondono alla versione principale richiesta, con una banda di funzionalità e un livello di patch maggiore o uguale al valore specificato. Se non viene trovato, fallisce.
latestMajor	Usa l'SDK di .NET più installato con una versione maggiore o uguale al valore specificato. Se non viene trovato, fallisce.
disable	Non avanza. È necessaria una corrispondenza esatta.

paths

• Tipo: matrice di string
• Disponibile a partire da: .NET 10 SDK.

Specifica i percorsi da considerare durante la ricerca di un SDK di .NET compatibile. I percorsi possono essere assoluti o relativi al percorso del file global.json . Il valore $host$ speciale rappresenta il percorso corrispondente all'eseguibile in esecuzione dotnet .

Questi percorsi vengono cercati nell'ordine in cui sono definiti e viene usato il primo SDK corrispondente .

Questa funzionalità consente di usare le installazioni dell'SDK locale ,ad esempio SDK relative a una radice del repository o inserite in una cartella personalizzata, che non sono installate a livello globale nel sistema.

La funzionalità "percorsi" funziona solo quando si usano comandi che usano .NET SDK, ad esempio dotnet run. Non influisce su scenari come l'esecuzione dell'utilità di avvio apphost nativa (app.exe), in esecuzione con dotnet app.dll o in esecuzione con dotnet exec app.dll. Per usare la funzionalità "percorsi", è necessario usare comandi SDK come dotnet run.

errorMessage

• Tipo: string
• Disponibile a partire da: .NET 10 SDK.

Specifica un messaggio di errore personalizzato visualizzato quando il resolver SDK non riesce a trovare un SDK compatibile .NET.

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.

test

• Tipo: object

Specifica informazioni sui test.

runner

• Tipo: string
• Disponibile a partire da: .NET 10.0 SDK.

Esecutore di test per individuare ed eseguire i test.

Commenti nel file global.json

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

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

Examples

L'esempio seguente illustra come impedire l'uso di 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 7.0.200 e consente la versione 7.0.200 o successiva, inclusa 8.0.xxx.

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

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

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.302 e consente la versione 8.0.302 o qualunque versione successiva 8.0.xxx, ad esempio 8.0.303 o 8.0.402.

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.102 e consente la versione 8.0.102 o qualunque versione successiva 8.0.1xx, ad esempio 8.0.103 o 8.0.199.

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

L'esempio seguente illustra come specificare percorsi di ricerca SDK aggiuntivi e un messaggio di errore personalizzato:

{
  "sdk": {
    "version": "10.0.100",
    "paths": [ ".dotnet", "$host$" ],
    "errorMessage": "The required .NET SDK wasn't found. Please run ./install.sh to install it."
  }
}

L'esempio seguente mostra che è stata indicata una versione non valida. L'output del comando dotnet --info mostra il messaggio di errore: "La versione '10.0' non è valida per il valore "sdk/version".

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

L'esempio seguente illustra come specificare Microsoft.Testing.Platform come test runner:

{
    "test": {
        "runner": "Microsoft.Testing.Platform"
    }
}

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 .NET SDK nel computer, visitare la pagina Download .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 8.0.302 --roll-forward latestFeature

Regole di corrispondenza

Note

Le regole di corrispondenza sono regolate dal punto di ingresso dotnet.exe, comune in tutti i runtime .NET installati. Le regole di corrispondenza per la versione installata più recente del runtime di .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 sei in Visual Studio, vengono considerate le versioni non definitive.
  • Se ci si trova in Visual Studio, usa lo stato di versione preliminare richiesto. Cioè, se si usa una versione di anteprima di Visual Studio o si imposta l'opzione Usare le anteprime dell'SDK .NET (in Tools>Options>Environment>Preview Features), le versioni non definitive sono considerate; 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 sia ufficiale o di prova 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 patch 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 non è impostato.

Gestire 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 usando una versione di anteprima di .NET. Vedere: https://aka.ms/dotnet-support-policy

  Le versioni del .NET SDK hanno una storia di impegno verso alta qualità. Tuttavia, se non si vuole usare una versione prerelease, 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:

  Il progetto di avvio '{startupProject}' ha come framework di destinazione '.NETCoreApp' versione '{targetFrameworkVersion}'. Questa versione degli strumenti da riga di comando di Entity Framework Core .NET supporta solo la versione 2.0 o successiva. 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 EF Core .NET Command-line Tools.

• Se si usa global.json per rimanere in una versione specifica dell'SDK di .NET, tenere presente che Visual Studio installa una sola copia dell'SDK di .NET. Quindi, se si aggiorna la versione Visual Studio, rimuove la versione precedente dell'SDK .NET usato per installare la nuova versione. Rimuove la versione precedente anche se si tratta di una versione principale diversa .NET.

Per evitare che Visual Studio rimuova le versioni di .NET SDK, installare lo SDK .NET autonomo dalla pagina download. Tuttavia, se si esegue questa operazione, non si otterranno più aggiornamenti automatici a tale versione di .NET SDK tramite Visual Studio e potrebbero essere a rischio di problemi di sicurezza.

Vedere anche

• Come vengono risolti gli SDK di progetto