global.json översikt

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 den körningsversion som ett projekt riktar sig mot. .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 8.0.300 eller senare funktionsband eller patch för 8.0 som är installerat på datorn:

{
  "sdk": {
    "version": "8.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 det true standardvärdet.
• När du använder Visual Studio använder programmet den förhandsversionsstatus som har 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 >) är >standardvä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 senare 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:

paths

• Typ: Matris med string
• Tillgänglig sedan: .NET 10 Preview 3 SDK.

Anger de platser som ska beaktas när du söker efter en kompatibel .NET SDK. Sökvägar kan vara absoluta eller relativa i förhållande till filens global.json plats. Specialvärdet $host$ representerar platsen som motsvarar den körbara dotnet.

Dessa sökvägar genomsöks i den ordning de definieras och den första matchande SDK:en används.

Den här funktionen möjliggör användning av lokala SDK-installationer (till exempel SDK:er i förhållande till en lagringsplatsrot eller placeras i en anpassad mapp) som inte är installerade globalt i systemet.

Funktionen "sökvägar" fungerar bara när du använder kommandon som engagerar .NET SDK, till exempel dotnet run. Det påverkar INTE scenarier som att köra det inbyggda apphost-startprogrammet (app.exe), köra med dotnet app.dlleller köra med dotnet exec app.dll. Om du vill använda funktionen "sökvägar" måste du använda SDK-kommandon som dotnet run.

errorMessage

• Typ: string
• Tillgänglig sedan: .NET 10 Preview 3 SDK.

Anger ett anpassat felmeddelande som visas när SDK-matcharen inte kan hitta en kompatibel .NET SDK.

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.

test

• Typ: object

Specificerar information om tester.

runner

• Typ: string
• Tillgänglig sedan: .NET 10.0 SDK.

Testkörare att identifiera/köra tester med.

Kommentarer i global.json

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

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

Examples

I följande exempel visas hur du inte tillåter användning av 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 7.0.200 och tillåter 7.0.200 eller senare versioner, inklusive 8.0.xxx.

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

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

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.302 och tillåter 8.0.302 eller senare 8.0.xxx version, till exempel 8.0.303 eller 8.0.402.

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

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

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

I följande exempel visas hur du anger ytterligare SDK-sökvägar och ett anpassat felmeddelande:

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

I följande exempel visas hur du anger Microsoft.Testing.Platform som testkörare:

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

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

Matchningsregler

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 om global.json inte anger en SDK-version och inte anger något allowPrerelease värde, används den högsta installerade SDK-versionen (motsvarande 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örhandsversionsutgåvor.
  • När du använder Visual Studio använder programmet den förhandsversionsstatus som har 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örhandsversion beror på värdet allowPrerelease. 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 det patch som standardpolicy rollForward. Annars kontrollerar du varje värde och dess beteende i rollForward-avsnittet.
  • 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 använder en förhandsversion av .NET. Se: https://aka.ms/dotnet-support-policy

  .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) ingår kommandot dotnet ef 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.

Om du vill undvika att Visual Studio tar bort versioner av .NET SDK installerar du det fristående .NET SDK:et från nedladdningssidan. Men om du gör det får du inte automatiska uppdateringar av den versionen av .NET SDK längre via Visual Studio och kan vara i riskzonen för säkerhetsproblem.

Se även

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