global.json översikt

Artikel
01/10/2024

Den här artikeln gäller för: ✔️ .NET Core 3.1 SDK och senare versioner

Med global.json-filen kan du definiera vilken .NET SDK-version som används när du kör .NET CLI-kommandon. Att välja .NET SDK-versionen är oberoende av att ange körningsversionen som ett projektmål. .NET SDK-versionen anger vilken version av .NET CLI som används. Den här artikeln beskriver hur du väljer SDK-versionen med hjälp av global.json.

Om du alltid vill använda den senaste SDK-versionen som är installerad på datorn behövs ingen global.json fil. I CI-scenarier (kontinuerlig integrering) vill du dock vanligtvis ange ett acceptabelt intervall för den SDK-version som används. Den global.json filen har en rollForward funktion som ger flexibla sätt att ange ett acceptabelt utbud av versioner. Följande global.json fil väljer till exempel 6.0.300 eller senare funktionsband eller korrigering för 6.0 som är installerad på datorn:

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

.NET SDK söker efter en global.json fil i den aktuella arbetskatalogen (som inte nödvändigtvis är samma som projektkatalogen) eller någon av dess överordnade kataloger.

Information om hur du anger körningsversionen i stället för SDK-versionen finns i Målramverk.

global.json schema

sdk

Typ: object

Anger information om .NET SDK som ska väljas.

version

Typ: string

Den version av .NET SDK som ska användas.

Det här fältet:

Har inte stöd för jokertecken. Du måste alltså ange det fullständiga versionsnumret.
Stöder inte versionsintervall.

allowPrerelease

Typ: boolean
Tillgänglig sedan: .NET Core 3.0 SDK.

Anger om SDK-matcharen ska överväga förhandsversioner när du väljer den SDK-version som ska användas.

Om du inte uttryckligen anger det här värdet beror standardvärdet på om du kör från Visual Studio:

Om du inte är i Visual Studio är truestandardvärdet .
Om du är i Visual Studio använder den status för förhandsversion som begärts. Om du använder en förhandsversion av Visual Studio eller om du ställer in alternativet Använd förhandsgranskningar av .NET SDK (under Verktygsalternativ>>Miljöförhandsgranskningsfunktioner>) är truestandardvärdet . Annars är falsestandardvärdet .

rollForward

Typ: string
Tillgänglig sedan: .NET Core 3.0 SDK.

Den roll-forward-princip som ska användas när du väljer en SDK-version, antingen som reserv när en specifik SDK-version saknas eller som ett direktiv för att använda en högre version. En version måste anges med ett rollForward värde, såvida du inte ställer in den på latestMajor. Standardbeteendet för framåtrullning bestäms av matchande regler.

För att förstå tillgängliga principer och deras beteende bör du överväga följande definitioner för en SDK-version i formatet x.y.znn:

x är huvudversionen.
y är den lägre versionen.
z är funktionsbandet.
nn är korrigeringsversionen.

I följande tabell visas möjliga värden för rollForward nyckeln:

Värde	Funktionssätt
`patch`	Använder den angivna versionen. Om det inte hittas rullar vidare till den senaste korrigeringsnivån. Om det inte hittas misslyckas. Det här värdet är det äldre beteendet från de tidigare versionerna av SDK.
`feature`	Använder den senaste korrigeringsnivån för det angivna huvud-, del- och funktionsbandet. Om det inte hittas rullar vidare till nästa högre funktionsband inom samma större/mindre och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas misslyckas.
`minor`	Använder den senaste korrigeringsnivån för det angivna huvud-, del- och funktionsbandet. Om det inte hittas rullar vidare till nästa högre funktionsband inom samma högre/lägre version och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas rullar vidare till nästa högre del- och funktionsband inom samma huvudnamn och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas misslyckas.
`major`	Använder den senaste korrigeringsnivån för det angivna huvud-, del- och funktionsbandet. Om det inte hittas rullar vidare till nästa högre funktionsband inom samma högre/lägre version och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas rullar vidare till nästa högre del- och funktionsband inom samma huvudnamn och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas rullar vidare till nästa högre huvud-, del- och funktionsband och använder den senaste korrigeringsnivån för det funktionsbandet. Om det inte hittas misslyckas.
`latestPatch`	Använder den senaste installerade korrigeringsnivån som matchar det begärda huvud-, del- och funktionsbandet med en korrigeringsnivå som är större än eller lika med det angivna värdet. Om det inte hittas misslyckas.
`latestFeature`	Använder det högsta installerade funktionsbandet och korrigeringsnivån som matchar den begärda huvudnivån och delnivån med ett funktionsband och en korrigeringsnivå som är större än eller lika med det angivna värdet. Om det inte hittas misslyckas.
`latestMinor`	Använder den högsta installerade nivån för mindre filer, funktionsband och korrigeringar som matchar den begärda majoren med en mindre, funktionsbands- och korrigeringsnivå som är större än eller lika med det angivna värdet. Om det inte hittas misslyckas.
`latestMajor`	Använder den högsta installerade .NET SDK med en version som är större än eller lika med det angivna värdet. Om det inte hittas misslyckas.
`disable`	Rullar inte framåt. En exakt matchning krävs.

msbuild-sdks

Typ: object

Gör att du kan styra projekt-SDK-versionen på ett ställe i stället för i varje enskilt projekt. Mer information finns i Så här löses projekt-SDK:er.

Kommentarer i global.json

Kommentarer i global.json filer stöds med javascript- eller C#-formatkommentarer. Till exempel:

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

Exempel

I följande exempel visas hur du inte använder förhandsversioner:

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

I följande exempel visas hur du använder den högsta installerade versionen som är större eller lika med den angivna versionen. JSON som visas tillåter inte någon SDK-version tidigare än 2.2.200 och tillåter 2.2.200 eller senare versioner, inklusive 3.0.xxx och 3.1.xxx.

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

I följande exempel visas hur du använder den exakta angivna versionen:

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

I följande exempel visas hur du använder det senaste funktionsbandet och korrigeringsversionen som är installerad av en specifik huvudversion och delversion. JSON som visas tillåter inte någon SDK-version tidigare än 3.1.102 och tillåter 3.1.102 eller senare 3.1.xxx version, till exempel 3.1.103 eller 3.1.200.

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

I följande exempel visas hur du använder den högsta korrigeringsversionen installerad av en viss version. Den JSON som visas tillåter inte någon SDK-version tidigare än 3.1.102 och tillåter 3.1.102 eller senare version 3.1.1xx, till exempel 3.1.103 eller 3.1.199.

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

global.json och .NET CLI

Om du vill ange en SDK-version i global.json-filen är det bra att veta vilka SDK-versioner som är installerade på datorn. Information om hur du gör det finns i Så här kontrollerar du att .NET redan är installerat.

Om du vill installera ytterligare .NET SDK-versioner på datorn går du till sidan Ladda ned .NET .

Du kan skapa en ny global.json fil i den aktuella katalogen genom att köra det nya dotnet-kommandot, ungefär som i följande exempel:

dotnet new globaljson --sdk-version 6.0.100

Matchningsregler

Kommentar

Matchningsreglerna styrs av dotnet.exe startpunkten, vilket är vanligt för alla installerade .NET-installerade körningar. Matchningsreglerna för den senaste installerade versionen av .NET Runtime används när du har flera körningskörningar installerade sida vid sida eller om du använder en global.json-fil .

Följande regler gäller när du avgör vilken version av SDK:et som ska användas:

Om ingen global.json fil hittas, eller global.json inte anger någon SDK-version eller ett allowPrerelease värde, används den högsta installerade SDK-versionen (motsvarar inställningen rollForward till latestMajor). Om förhandsversioner av SDK anses vara beroende av hur dotnet anropas:
- Om du inte är i Visual Studio beaktas förhandsversioner.
- Om du är i Visual Studio använder den status för förhandsversion som begärts. Om du använder en förhandsversion av Visual Studio eller om du ställer in alternativet Använd förhandsversioner av .NET SDK (under Verktygsalternativ>>Miljöförhandsgranskningsfunktioner>) beaktas förhandsversioner. Annars beaktas endast versionsversioner.
Om en global.json fil hittas som inte anger en SDK-version, men den anger ett allowPrerelease värde, används den högsta installerade SDK-versionen (motsvarar inställningen rollForward till latestMajor). Om den senaste SDK-versionen kan släppas eller förhandsversioner beror på värdet allowPrereleaseför . true anger att förhandsversioner beaktas. false anger att endast versionsversioner beaktas.
Om en global.json fil hittas och den anger en SDK-version:
- Om inget rollForward värde anges används latestPatch det som standardprincip rollForward . Annars kontrollerar du varje värde och deras beteende i avsnittet rollForward .
- Om förhandsversioner beaktas och vad som är standardbeteendet när allowPrerelease inte har angetts beskrivs i avsnittet allowPrerelease .

Felsöka byggvarningar

Följande varningar indikerar att projektet kompilerades med en förhandsversion av .NET SDK:

Du arbetar med en förhandsversion av .NET Core SDK. Du kan definiera SDK-versionen via en global.json fil i det aktuella projektet. Mer på https://go.microsoft.com/fwlink/?linkid=869452.

Du använder en förhandsversion av .NET. Se: https://aka.ms/dotnet-core-preview

.NET SDK-versioner har en historik och ett åtagande att vara av hög kvalitet. Men om du inte vill använda en förhandsversion kontrollerar du de olika strategier som du kan använda i avsnittet allowPrerelease . För datorer som aldrig har haft en .NET Core 3.0 eller högre körning eller SDK installerad måste du skapa en global.json fil och ange den exakta version som du vill använda.
Följande varning anger att projektet riktar in sig på EF Core 1.0 eller 1.1, vilket inte är kompatibelt med .NET Core 2.1 SDK och senare versioner:

Startprojektet {startupProject} riktar sig mot ramverket . NETCoreApp-version {targetFrameworkVersion}. Den här versionen av Entity Framework Core .NET-kommandoradsverktyg stöder endast version 2.0 eller senare. Information om hur du använder äldre versioner av verktygen finns i https://go.microsoft.com/fwlink/?linkid=871254.

Från och med .NET Core 2.1 SDK (version 2.1.300) dotnet ef ingår kommandot i SDK. Kompilera projektet genom att installera .NET Core 2.0 SDK (version 2.1.201) eller tidigare på datorn och definiera önskad SDK-version med hjälp av filen global.json . Mer information om kommandot finns i dotnet ef EF Core .NET-kommandoradsverktyg.
Om du använder global.json för att behålla en viss version av .NET SDK bör du tänka på att Visual Studio bara installerar en enda kopia av .NET SDK. Så om du uppgraderar Visual Studio-versionen, tar den bort den tidigare versionen av .NET SDK som den hade använt för att installera den nya versionen. Den tar bort den gamla versionen även om den är en annan större .NET-version.

För att undvika att Visual Studio tar bort versioner av .NET SDK måste du installera fristående .NET SDK från nedladdningssidan. Observera att om du gör det kommer du inte längre att få automatiska uppdateringar av den versionen av .NET SDK via Visual Studio och kan vara i riskzonen för säkerhetsproblem.

Se även

Så här löses projekt-SDK:er