global.json – přehled

Tento článek se vztahuje na: ✔️ .NET Core 3.1 SDK a novější verze

Soubor global.json umožňuje definovat, která verze sady .NET SDK se používá při spouštění příkazů rozhraní příkazového řádku .NET. Výběr verze sady .NET SDK je nezávislý na určení verze modulu runtime, na které projekt cílí. Verze sady .NET SDK označuje, která verze rozhraní příkazového řádku .NET CLI se používá. Tento článek vysvětluje, jak vybrat verzi sady SDK pomocí global.json.

Pokud chcete vždy používat nejnovější verzi sady SDK nainstalovanou na vašem počítači, není potřeba žádný global.json soubor. Ve scénářích CI (kontinuální integrace) ale obvykle chcete zadat přijatelný rozsah pro používanou verzi sady SDK. Soubor global.json má rollForward funkci, která poskytuje flexibilní způsoby určení přijatelného rozsahu verzí. Například následující soubor global.json vybere verzi 10.0.100 nebo jakýkoli novější feature band nebo opravu pro verzi 10.0, která je nainstalovaná na počítači:

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

Sada .NET SDK hledá souborglobal.json v aktuálním pracovním adresáři (který nemusí být nutně stejný jako adresář projektu) nebo jeden z jeho nadřazených adresářů.

Informace o určení verze modulu runtime místo verze sady SDK naleznete v tématu Cílové architektury.

schéma global.json

sdk

Typ: object

Určuje informace o výběru sady .NET SDK.

version

• Typ: string

Verze sady .NET SDK, která se má použít.

Toto pole:

• Vyžaduje úplné číslo verze, například 10.0.100.
• Nepodporuje čísla verzí jako 10, 10.0 nebo 10.0.x.
• Nepodporuje zástupné kóty.
• Nepodporuje rozsahy verzí.

allowPrerelease

• Typ: boolean
• K dispozici od: .NET Core 3.0 SDK.

Určuje, jestli má překladač sady SDK zvážit předběžné verze při výběru verze sady SDK, která se má použít.

Pokud tuto hodnotu explicitně nenastavíte, výchozí hodnota závisí na tom, jestli používáte Visual Studio:

• Pokud nejste ve Visual Studio, výchozí hodnota je true.
• Pokud jste v Visual Studio, využije stav předběžného vydání, který je požadován. To znamená, že pokud používáte verzi Preview sady Visual Studio, nebo nastavíte možnost Použít verze Preview sady .NET SDK (v části Nástroje>Možnosti>Prostředí>Funkce náhledu), výchozí hodnota je true. V opačném případě je falsevýchozí hodnota .

rollForward

• Typ: string
• K dispozici od: .NET Core 3.0 SDK.

Politika přechodu na novější verzi při výběru verze sady SDK, buď jako náhradní možnost, když chybí konkrétní verze sady SDK, nebo jako pokyn k použití novější verze. Musí být zadána verze s rollForward hodnotou, pokud ji nenastavíte na latestMajorhodnotu . Standardní chování při přechodu na novější verzi je určeno odpovídajícími pravidly shody.

Pokud chcete porozumět dostupným zásadám a jejich chování, zvažte následující definice verze sady SDK ve formátu x.y.znn:

• x je hlavní verze.
• y je menší verze.
• z je hlavní kapela.
• nn je opravená verze.

V následující tabulce jsou uvedeny možné hodnoty klíče rollForward :

Value	Behavior
patch	Používá zadanou verzi. Pokud se nenajde, přejde na nejnovější úroveň opravy. Pokud se nenajde, nepodaří se. Tato hodnota představuje původní chování z předchozích verzí sady SDK.
feature	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud se nenajde, přejde do další vyšší úrovně funkcí ve stejné hlavní/vedlejší úrovni a použije nejnovější úroveň opravy pro tuto úroveň funkcí. Pokud se nenajde, nepodaří se.
minor	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud ho nenajdete, pokračuje dál do vyšší úrovně funkcí v rámci stejné hlavní/minor verze a použije nejnovější úroveň záplat pro tuto úroveň funkcí. Pokud není nalezen, přejde na další vyšší vedlejší a funkční pásmo v rámci stejného hlavního rozsahu a použije nejnovější úroveň opravy pro toto funkční pásmo. Pokud se nenajde, nepodaří se.
major	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud ho nenajdete, pokračuje dál do vyšší úrovně funkcí v rámci stejné hlavní/minor verze a použije nejnovější úroveň záplat pro tuto úroveň funkcí. Pokud není nalezen, přejde na další vyšší vedlejší a funkční pásmo v rámci stejného hlavního rozsahu a použije nejnovější úroveň opravy pro toto funkční pásmo. Pokud ho nenajdete, vrátí se k dalšímu vyššímu hlavnímu, vedlejšímu a funkčnímu pásmu a použije nejnovější úroveň opravy pro tuto skupinu funkcí. Pokud se nenajde, nepodaří se.
latestPatch	Používá nejnovější nainstalovanou úroveň opravy, která odpovídá požadovanému hlavnímu, vedlejšímu a funkčnímu pásmu s úrovní opravy, která je větší nebo rovna zadané hodnotě. Pokud se nenajde, nepodaří se.
latestFeature	Používá nejvyšší nainstalovanou verzní úroveň a úroveň opravy, které odpovídají požadované hlavní a vedlejší verzi s verzní úrovní a úrovní opravy, které jsou větší nebo rovny zadané hodnotě. Pokud se nenajde, nepodaří se.
latestMinor	Používá nejvyšší nainstalovanou podverzi, úroveň funkcí a úroveň oprav, které odpovídají požadované hlavní verzi s podverzí, úrovní funkcí a úrovní oprav, které jsou větší nebo rovny zadané hodnotě. Pokud se nenajde, nepodaří se.
latestMajor	Používá nejvyšší nainstalovanou sadu .NET SDK s verzí, která je větší nebo rovna zadané hodnotě. Pokud ho nenajdete, nezdaří se.
disable	Nepohybuje se dopředu. Vyžaduje se přesná shoda.

paths

• Typ: Pole string
• K dispozici od: .NET 10 SDK.

Určuje místa, která je třeba zvážit při hledání kompatibilního .NET SDK. Cesty můžou být absolutní nebo relativní vzhledem k umístění souboruglobal.json . Speciální hodnota $host$ představuje umístění odpovídající spuštěnému programu dotnet.

Tyto cesty se prohledávají v pořadí, v jakém jsou definovány, a použije se první odpovídající sada SDK.

Tato funkce umožňuje používat místní instalace sady SDK (například sady SDK vzhledem ke kořenovému adresáři úložiště nebo umístěné ve vlastní složce), které nejsou v systému nainstalované globálně.

Funkce "cesty" funguje pouze při použití příkazů, které zapojují sadu .NET SDK, například dotnet run. Nemá vliv na scénáře, jako je spuštění nativního spouštěče apphost (app.exe), spuštění s dotnet app.dllnebo spuštění s dotnet exec app.dll. Chcete-li použít funkci "cesty", musíte použít příkazy sady SDK, jako je dotnet run.

errorMessage

• Typ: string
• K dispozici od: .NET 10 SDK.

Určuje vlastní chybovou zprávu, která se zobrazí, když překladač sady SDK nemůže najít kompatibilní sadu .NET SDK.

msbuild-sdks

Typ: object

Umožňuje řídit verzi sady SDK projektu na jednom místě, nikoli v každém jednotlivém projektu. Další informace naleznete v tématu Jak se řeší sady projektových SDK.

test

• Typ: object

Určuje informace o testech.

runner

• Typ: string
• K dispozici od: .NET 10.0 SDK.

Spouštěč testů pro detekci a spuštění testů.

Komentáře v global.json

Komentáře v global.json souborech se podporují pomocí komentářů ve stylu JavaScriptu nebo C#. Například:

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

Examples

Následující příklad ukazuje, jak zakázat použití předběžné verze:

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

Následující příklad ukazuje, jak použít nejvyšší nainstalovanou verzi, která je větší nebo rovna zadané verzi. Zobrazený kód JSON zakáže všechny verze sady SDK starší než 7.0.200 a povolí verzi 7.0.200 nebo jakoukoli novější, včetně 8.0.xxx.

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

Následující příklad ukazuje, jak použít přesnou zadanou verzi:

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

Následující příklad ukazuje, jak používat nejnovější funkční pásmo a opravenou verzi nainstalované konkrétní hlavní a vedlejší verze. Zobrazený kód JSON zakáže všechny verze sady SDK starší než 8.0.302 a povolí verzi 8.0.302 nebo novější 8.0.xxx, například 8.0.303 nebo 8.0.402.

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

Následující příklad ukazuje, jak použít nejvyšší verzi opravy nainstalovanou konkrétní verzi. Zobrazený kód JSON zakáže všechny verze sady SDK starší než 8.0.102 a povolí verzi 8.0.102 nebo novější verze 8.0.1xx, například 8.0.103 nebo 8.0.199.

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

Následující příklad ukazuje, jak zadat další cesty hledání sady SDK a vlastní chybovou zprávu:

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

Následující příklad ukazuje zadanou neplatnou verzi. Ve výstupu příkazu dotnet --info se zobrazí chybová zpráva verze 10.0 není platná pro hodnotu sdk/version.

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

Následující příklad ukazuje, jak určit Microsoft.Testing.Platform jako spouštěč testů:

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

global.json a rozhraní příkazového řádku .NET

Pokud chcete nastavit verzi sady SDK v souboru global.json , je užitečné vědět, které verze sady SDK jsou na vašem počítači nainstalované. Informace o tom, jak to udělat, naleznete v tématu Jak zkontrolovat, zda je .NET již nainstalován.

Pokud chcete na počítač nainstalovat další verze sady .NET SDK, přejděte na stránku Stáhnout .NET .

V aktuálním adresáři můžete vytvořit nový soubor global.json spuštěním nového příkazu dotnet, podobně jako v následujícím příkladu:

dotnet new globaljson --sdk-version 8.0.302 --roll-forward latestFeature

Pravidla párování

Note

Odpovídající pravidla se řídí vstupním dotnet.exe bodem, který je společný pro všechna nainstalovaná .NET runtime prostředí. Odpovídající pravidla pro nejnovější nainstalovanou verzi modulu runtime .NET se používají, pokud máte nainstalovaných více modulů runtime vedle sebe nebo pokud používáte soubor global.json .

Při určování verze sady SDK, která se má použít, platí následující pravidla:

• Pokud se nenajde žádný soubor global.json nebo global.json nezadá verzi sady SDK a nezadá allowPrerelease hodnotu, použije se nejvyšší nainstalovaná verze sady SDK (ekvivalentní nastavení rollForwardlatestMajor). To, jestli se považují předběžné verze sady SDK, závisí na tom, jak dotnet se vyvolává:

  • Jestliže nepoužíváte Visual Studio, jsou zohledněny předběžné verze.
  • Pokud jste v Visual Studio, využije stav předběžného vydání, který je požadován. To znamená, že pokud používáte verzi Preview sady Visual Studio nebo nastavíte předvolbu 'Použít náhledy sady .NET SDK' (v části Nástroje > Možnosti > Prostředí > Náhled na funkce), zvažují se předběžné verze; jinak se zvažují pouze vydané verze.

• Pokud se zjistí soubor global.json, který nezadá verzi sady SDK, ale určuje allowPrerelease hodnotu, použije se nejvyšší nainstalovaná verze sady SDK (ekvivalentní nastavení rollForwardlatestMajor). Jestli je možné vydat nejnovější verzi sady SDK nebo předběžnou verzi, závisí na hodnotě allowPrerelease. true označuje, že se berou v úvahu předběžné verze; false označuje, že se berou v úvahu pouze vydané verze.

• Pokud se soubor global.json najde a určuje verzi sady SDK:

  • Pokud není nastavená žádná rollForward hodnota, použije patch se jako výchozí rollForward zásada. V opačném případě zkontrolujte každou hodnotu a její chování v oddílu RollForward.
  • Jestli se předběžné verze považují za výchozí a jaké je výchozí chování, pokud allowPrerelease není nastavená, je popsáno v části allowPrerelease .

Řešení problémů s výstrahami při sestavování

• Následující upozornění ukazují, že váš projekt byl zkompilován pomocí předběžné verze sady .NET SDK:

  Používáte verzi Preview .NET. Viz: https://aka.ms/dotnet-support-policy

  Verze sady .NET SDK mají historii a závazek vysoké kvality. Pokud ale nechcete používat předběžnou verzi, zkontrolujte různé strategie, které můžete použít v části allowPrerelease . Pro počítače, které nikdy neměly nainstalovaný modul runtime nebo sadu SDK pro .NET Core 3.0 nebo novější, musíte vytvořit soubor global.json a zadat přesnou verzi, kterou chcete použít.

• Následující upozornění znamená, že váš projekt cílí na EF Core 1.0 nebo 1.1, což není kompatibilní se sadou .NET Core 2.1 SDK a novějšími verzemi:

  Startovní projekt '{startupProject}' zaměřuje se na platformu '.NETCoreApp' verze '{targetFrameworkVersion}'. Tato verze nástrojů příkazového řádku Entity Framework Core .NET podporuje pouze verzi 2.0 nebo vyšší. Informace o používání starších verzí nástrojů naleznete v tématu https://go.microsoft.com/fwlink/?linkid=871254.

  Počínaje sadou .NET Core 2.1 SDK (verze 2.1.300) dotnet ef je příkaz součástí sady SDK. Pokud chcete zkompilovat projekt, nainstalujte na počítač sadu .NET Core 2.0 SDK (verze 2.1.201) nebo starší a pomocí souboru global.json definujte požadovanou verzi sady SDK. Další informace o příkazu dotnet ef naleznete v tématu Nástroje příkazového řádku EF Core .NET.

• Pokud používáte global.json zůstat v konkrétní verzi sady .NET SDK, mějte na paměti, že Visual Studio vždy nainstaluje jenom jednu kopii sady .NET SDK. Pokud tedy upgradujete verzi sady Visual Studio, odebere předchozí verzi sady .NET SDK, kterou použil k instalaci nové verze. Odebere starou verzi, i když se jedná o jinou hlavní verzi .NET.

Pokud chcete zabránit Visual Studiu v odebrání verzí sady .NET SDK, nainstalujte samostatnou sadu .NET SDK ze stránky pro stažení. Pokud to ale uděláte, už nebudete prostřednictvím aplikace Visual Studio dostávat automatické aktualizace této verze sady .NET SDK a můžete být vystaveni bezpečnostním rizikům.

Viz také

• Jak se vyřeší projektová SDK