global.json – přehled

Článek
01/10/2024

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 6.0.300 nebo jakýkoli novější pás nebo opravu funkcí pro verzi 6.0, která je nainstalovaná na počítači:

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

Sada .NET SDK hledá soubor global.json v aktuálním pracovním adresáři (který nemusí být nutně stejný jako adresář projektu) nebo v jednom z 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 sadě .NET SDK, které chcete vybrat.

version

Typ: string

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

Toto pole:

Nemá podporu zástupných znaků; to znamená, že musíte zadat celé číslo verze.
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 v sadě Visual Studio, výchozí hodnota je true.
Pokud jste v sadě Visual Studio, použije požadovaný stav předběžné verze. 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í>Preview), 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.

Postupná zásada, která se má použít při výběru verze sady SDK, buď jako záložní, pokud chybí konkrétní verze sady SDK, nebo jako direktiva pro použití vyšší verze. Musí být zadána verze s rollForward hodnotou, pokud ji nenastavíte na latestMajorhodnotu . Výchozí chování při předávání je určeno odpovídajícími pravidly.

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 podverze.
z je celovečerní skupina.
nn je verze opravy.

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

Hodnota	Chování
`patch`	Používá zadanou verzi. Pokud se nenajde, přepošli se na nejnovější úroveň opravy. Pokud se nenajde, nezdaří se. Tato hodnota je starší verze chování ze starších verzí sady SDK.
`feature`	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud ho nenajdete, přepošlete se do dalšího vyššího pásma funkcí ve stejném hlavním/vedlejším pásmu a použijete nejnovější úroveň opravy pro tuto skupinu funkcí. Pokud se nenajde, nezdaří se.
`minor`	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud ho nenajdete, vrátí se do dalšího vyššího pásma funkcí ve stejné hlavní/podverze a použije nejnovější úroveň opravy pro tuto skupinu funkcí. Pokud ho nenajdete, vrátí se k dalšímu vyššímu vedlejšímu pásmu a pásu funkcí v rámci stejného hlavního rozsahu a použije nejnovější úroveň opravy pro tuto skupinu funkcí. Pokud se nenajde, nezdaří se.
`major`	Použije nejnovější úroveň opravy pro zadaný hlavní, vedlejší a funkční pruh. Pokud ho nenajdete, vrátí se do dalšího vyššího pásma funkcí ve stejné hlavní/podverze a použije nejnovější úroveň opravy pro tuto skupinu funkcí. Pokud ho nenajdete, vrátí se k dalšímu vyššímu vedlejšímu pásmu a pásu funkcí v rámci stejného hlavního rozsahu a použije nejnovější úroveň opravy pro tuto skupinu funkcí. 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, nezdaří 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, nezdaří se.
`latestFeature`	Používá nejvyšší nainstalovanou úroveň funkcí a úroveň oprav, která odpovídá požadované hlavní a vedlejší úrovni se znaménkem a úrovní oprav, která je větší nebo rovna zadané hodnotě. Pokud se nenajde, nezdaří se.
`latestMinor`	Používá nejvyšší nainstalovanou úroveň podverze, pásma funkcí a úrovně oprav, která odpovídá požadované hlavní hodnotě s podverze, pásmem funkcí a úrovní oprav, která je větší nebo rovna zadané hodnotě. Pokud se nenajde, nezdaří 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`	Nevrácené dopředu. Vyžaduje se přesná shoda.

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 Řešení sad SDK projektu.

Komentáře v global.json

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

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

Příklady

Následující příklad ukazuje, jak nepoužívat 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ž 2.2.200 a povolí verzi 2.2.200 nebo jakoukoli novější, včetně 3.0.xxx a 3.1.xxx.

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

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

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

Následující příklad ukazuje, jak používat nejnovější verzi a verzi opravy funkcí nainstalovanou pro konkrétní hlavní a podverzi. Zobrazený kód JSON zakáže jakoukoli verzi sady SDK starší než 3.1.102 a povolí verzi 3.1.102 nebo novější 3.1.xxx, například 3.1.103 nebo 3.1.200.

{
  "sdk": {
    "version": "3.1.102",
    "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ž 3.1.102 a povolí verzi 3.1.102 nebo novější verze 3.1.1xx, například 3.1.103 nebo 3.1.199.

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

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 6.0.100

Pravidla párování

Poznámka:

Odpovídající pravidla se řídí vstupním dotnet.exe bodem, který je společný pro všechny nainstalované moduly runtime .NET. 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 nebyl nalezen žádný soubor global.json nebo global.json nezadá verzi sady SDK ani 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 v sadě Visual Studio, zvažte předběžné verze.
- Pokud jste v sadě Visual Studio, použije požadovaný stav předběžné verze. To znamená, že pokud používáte verzi Preview sady Visual Studio nebo nastavíte náhledy možnosti Použít sadu .NET SDK (v části Nástroje>Možnosti>prostředí>preview funkcí), zvažují se předběžné verze. V opačném případě se považují pouze verze 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 považují předběžné verze; false označuje, že se považují pouze verze vydané verze.
Pokud se soubor global.json najde a určuje verzi sady SDK:
- Pokud není nastavená žádná rollForward hodnota, použije latestPatch se jako výchozí rollForward zásada. V opačném případě zkontrolujte každou hodnotu a jejich chování v části 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í potíží s upozorněními sestavení

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

Pracujete s verzí Preview sady .NET Core SDK. Verzi sady SDK můžete definovat prostřednictvím souboru global.json v aktuálním projektu. Více na https://go.microsoft.com/fwlink/?linkid=869452adrese .

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

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:

Spouštěcí projekt {startupProject} cílí na architekturu . VERZE NETCoreApp {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 naleznete v tématu NÁSTROJE příkazového dotnet ef řá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 se chcete sadě Visual Studio vyhnout odebrání verzí sady .NET SDK, budete muset nainstalovat samostatnou sadu .NET SDK ze stránky pro stahování. Mějte na paměti, že pokud to uděláte, nebudete už prostřednictvím sady Visual Studio dostávat automatické aktualizace této verze sady .NET SDK a mohou být ohroženy problémy se zabezpečením.

Viz také

Jak se řeší sady SDK projektu