panoramica di global.json

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 8.0.300 o qualsiasi banda di funzionalità o patch successiva per la versione 8.0 installata sul computer:

{
  "sdk": {
    "version": "8.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 del file 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 supporta i 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 sei in Visual Studio, il valore predefinito è true.
• Se si è in Visual Studio, viene usato lo stato di prerelease richiesto. 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 minore.
• z è la banda caratteristica.
• nn è la versione patch.

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

Percorsi

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

Specifica i percorsi da considerare durante la ricerca di un SDK .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 .

messaggio di errore

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

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

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 nel file 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": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Esempi

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."
  }
}

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 8.0.302 --roll-forward latestFeature

Regole di corrispondenza

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 prese in considerazione le versioni prerelease.
  • Se si è in Visual Studio, viene usato lo stato di prerelease richiesto. 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 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 usa una versione di anteprima di .NET. Vedere: https://aka.ms/dotnet-support-policy

  Le versioni di .NET SDK hanno una storia e un impegno nel mantenere uno standard di 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 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 potrebbe sussistere il rischio di problemi di sicurezza.

Vedi anche

• Come vengono risolti gli SDK di progetto