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á .NET verze sady SDK se používá při spuš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 .NET rozhraní příkazového řádku 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"
  }
}

K vyhledání souboru global.json spoléháte na dvě komponenty v sadě .NET SDK. Každá součást začíná z jiného umístění a prohledává adresáře předků.

• .NET SDK muxer zpracovává CLI příkazy dotnet. Začíná z aktuálního pracovního adresáře, který nemusí být nutně stejný jako adresář projektu.
• .NET překladač sady MSBuild project SDK řeší sady SDK projektu během sestavení. Začíná z adresáře, který obsahuje soubor řešení, pokud existuje. Pokud neexistuje žádný soubor řešení, začíná z adresáře, který obsahuje aktuální soubor projektu. Pokud žádný soubor neexistuje, použije aktuální pracovní 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 .NET SDK, které chcete vybrat.

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 nenastavíte explicitně, 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, použije požadovaný stav předběžné verze. To znamená, že pokud používáte verzi Preview Visual Studia nebo nastavíte možnost Použití preview verzí .NET SDK (v části Nástroje>Možnosti>Prostředí>Preview funkce), 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 .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 umístění, která by se měla zvážit při hledání kompatibilní sady .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í .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, najdete v tématu Pokud zkontrolujte, jestli už je .NET nainstalovaný.

Pokud chcete na počítač nainstalovat další verze sady .NET SDK, přejděte na stránku Stah .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 bodem dotnet.exe, který je společný pro všechny nainstalované moduly runtime .NET. Odpovídající pravidla pro nejnovější nainstalovanou verzi modulu .NET Runtime 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á:

  • Pokud nejste ve Visual Studio, zvažují se předběžné verze.
  • Pokud jste v Visual Studio, použije požadovaný stav předběžné verze. To znamená, pokud používáte Preview verzi Visual Studio nebo nastavíte Použití verzí Preview sady .NET SDK (v části Nástroje>Možnosti>Prostředí>Předběžné Funkce), se zvažují předběžné verze; v opačném případě 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

  .NET verze sady 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 .NET Core 3.0 nebo vyšší, 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 SDK .NET Core 2.1 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 .NET Core 2.1 SDK (verze 2.1.300) je příkaz dotnet ef součástí sady SDK. Pokud chcete zkompilovat projekt, nainstalujte na počítač .NET Core 2.0 SDK (verze 2.1.201) nebo starší a definujte požadovanou verzi sady SDK pomocí souboru global.json. Další informace o příkazu dotnet ef najdete v tématu EF Core .NET Nástroje příkazového řádku.

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

Pokud se chcete vyhnout Visual Studio odebrání verzí sady .NET SDK, nainstalujte samostatnou sadu SDK .NET ze stránky download. Pokud to ale uděláte, už nebudete prostřednictvím Visual Studio dostávat automatické aktualizace této verze .NET SDK a můžete být ohroženi bezpečnostními problémy.

Viz také

• Jak se vyřeší projektová SDK