global.json áttekintése

Cikk
01/10/2024

Ez a cikk a következőre vonatkozik: ✔️ .NET Core 3.1 SDK és újabb verziók

A global.json fájl lehetővé teszi annak meghatározását, hogy a .NET CLI-parancsok futtatásakor melyik .NET SDK-verziót használja a rendszer. A .NET SDK-verzió kiválasztása független a projektcélok futtatókörnyezeti verziójának megadásától. A .NET SDK-verzió azt jelzi, hogy a .NET CLI melyik verzióját használja a rendszer. Ez a cikk azt ismerteti, hogyan választhatja ki az SDK-verziót global.json használatával.

Ha mindig a számítógépre telepített legújabb SDK-verziót szeretné használni, nincs szükség global.json fájlra. A CI (folyamatos integrációs) forgatókönyvekben azonban általában egy elfogadható tartományt szeretne megadni a használt SDK-verzióhoz. A global.json fájl olyan rollForward funkcióval rendelkezik, amely rugalmas módot biztosít egy elfogadható verziótartomány megadására. Az alábbi global.json fájl például a 6.0.300-at vagy a 6.0-s verzió bármely újabb funkciósávját vagy javítását választja ki, amely telepítve van a gépen:

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

A .NET SDK egy global.json fájlt keres az aktuális munkakönyvtárban (amely nem feltétlenül ugyanaz, mint a projektkönyvtár), vagy annak egyik szülőkönyvtárát.

Az SDK-verzió helyett a futtatókörnyezeti verzió megadásáról további információt a Cél-keretrendszerek című témakörben talál.

global.json séma

sdk

Típus: object

Megadja a kijelölendő .NET SDK-val kapcsolatos információkat.

Verzió

Típus: string

A használni kívánt .NET SDK verziója.

Ez a mező:

Nem támogatja a helyettesítő karaktereket; vagyis meg kell adnia a teljes verziószámot.
Nem támogatja a verziótartományokat.

allowPrerelease

Típus: boolean
Azóta elérhető: .NET Core 3.0 SDK.

Azt jelzi, hogy az SDK-feloldónak fontolóra kell-e vennie az előzetes verziókat a használni kívánt SDK-verzió kiválasztásakor.

Ha nem állítja be explicit módon ezt az értéket, az alapértelmezett érték attól függ, hogy a Visual Studióból fut-e:

Ha nem a Visual Studióban van, az alapértelmezett érték az true.
Ha a Visual Studióban van, az a kért előzetes állapotot használja. Ez azt jelzi, hogy ha a Visual Studio előzetes verzióját használja, vagy a .NET SDK -ban beállította a Use previews (Az Eszközök>beállításai>környezet>előzetes verziójú funkciói) lehetőséget, az alapértelmezett érték a .true Ellenkező esetben az alapértelmezett érték a következő false.

rollForward

Típus: string
Azóta elérhető: .NET Core 3.0 SDK.

Az SDK-verzió kiválasztásakor használandó roll-forward szabályzat tartalékként, ha egy adott SDK-verzió hiányzik, vagy irányelvként egy magasabb verziót használ. Egy verziót meg kell adni egy rollForward értékkel, kivéve, ha azt állítja be latestMajor. Az alapértelmezett visszaállítási viselkedést az egyező szabályok határozzák meg.

Az elérhető szabályzatok és azok viselkedésének megértéséhez vegye figyelembe az SDK-verziók következő definícióit a formátumban x.y.znn:

x a főverzió.
y az alverzió.
z a funkciósáv.
nn a javítás verziója.

Az alábbi táblázat a kulcs lehetséges értékeit rollForward mutatja be:

Érték	Működés
`patch`	A megadott verziót használja. Ha nem található, a legújabb javításszintre lép. Ha nem található, sikertelen lesz. Ez az érték az SDK korábbi verzióinak örökölt viselkedése.
`feature`	A legújabb javításszintet használja a megadott fő-, al- és funkciósávhoz. Ha nem található, a következő magasabb funkciósávra lép ugyanazon a fő-/alverzión belül, és a legújabb javításszintet használja az adott funkciósávhoz. Ha nem található, sikertelen lesz.
`minor`	A legújabb javításszintet használja a megadott fő-, al- és funkciósávhoz. Ha nem található, a következő magasabb szolgáltatási sávra lép ugyanazon a fő-/alverzión belül, és a legújabb javításszintet használja az adott funkciósávhoz. Ha nem található, a következő nagyobb al- és funkciósávra lép át ugyanazon a főverzión belül, és a legújabb javításszintet használja az adott funkciósávhoz. Ha nem található, sikertelen lesz.
`major`	A legújabb javításszintet használja a megadott fő-, al- és funkciósávhoz. Ha nem található, a következő magasabb szolgáltatási sávra lép ugyanazon a fő-/alverzión belül, és a legújabb javításszintet használja az adott funkciósávhoz. Ha nem található, a következő nagyobb al- és funkciósávra lép át ugyanazon a főverzión belül, és a legújabb javításszintet használja az adott funkciósávhoz. Ha nem található, a következő nagyobb, alverziós és funkciósávra lép, és a legújabb javításszintet használja a funkciósávhoz. Ha nem található, sikertelen lesz.
`latestPatch`	A legújabb telepített javításszintet használja, amely megfelel a kért fő-, al- és funkciósávnak a megadott értéknél nagyobb vagy egyenlő javításszinttel. Ha nem található, sikertelen lesz.
`latestFeature`	A legmagasabb telepített funkciósávot és javításszintet használja, amely megfelel a kért fő- és alverziónak, valamint egy olyan funkciósávot és javításszintet, amely nagyobb vagy egyenlő a megadott értéknél. Ha nem található, sikertelen lesz.
`latestMinor`	A legmagasabb telepített alverziót, funkciósávot és javításszintet használja, amely megfelel a kért főverziónak egy al-, funkciósáv- és javításszinttel, amely nagyobb vagy egyenlő a megadott értéknél. Ha nem található, sikertelen lesz.
`latestMajor`	A legmagasabb telepített .NET SDK-t használja a megadott értéknél nagyobb vagy egyenlő verzióval. Ha nem található, sikertelen.
`disable`	Nem lép előre. Pontos egyezésre van szükség.

msbuild-sdks

Típus: object

Lehetővé teszi a projekt SDK-verziójának vezérlését egy helyen, nem pedig az egyes projektekben. További információ: A projekt SDK-k feloldása.

Megjegyzések a global.json

A global.json fájlok megjegyzései JavaScript- vagy C#-stílusú megjegyzések használatával támogatottak. Példa:

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

Példák

Az alábbi példa bemutatja, hogyan lehet nem használni a prerelease-verziókat:

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

Az alábbi példa bemutatja, hogyan használhatja a legmagasabb telepített verziót, amely nagyobb vagy egyenlő a megadott verziónál. A megjelenített JSON nem engedélyezi a 2.2.200-nál korábbi SDK-verziókat, és engedélyezi a 2.2.200-es vagy újabb verziót, beleértve a 3.0.xxx és a 3.1.xxx.

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

Az alábbi példa bemutatja, hogyan használhatja a pontos megadott verziót:

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

Az alábbi példa bemutatja, hogyan használhatja egy adott fő- és alverzió legújabb funkciósávját és javításverzióját. A megjelenített JSON letiltja a 3.1.102-nél korábbi SDK-verziókat, és engedélyezi a 3.1.102-es vagy újabb 3.1.xxx verziót, például a 3.1.103-as vagy a 3.1.200-as verziót.

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

Az alábbi példa bemutatja, hogyan használhatja az adott verzióra telepített legmagasabb javításverziót. A megjelenített JSON nem engedélyezi a 3.1.102-nél korábbi SDK-verziókat, és engedélyezi a 3.1.102-es vagy újabb 3.1.1xx verziót, például a 3.1.103-as vagy a 3.1.199-es verziót.

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

global.json és a .NET parancssori felület

Ha SDK-verziót szeretne beállítani a global.json fájlban, hasznos tudni, hogy mely SDK-verziók vannak telepítve a gépen. Ennek módjáról további információt a .NET telepítésének ellenőrzése című témakörben talál.

Ha további .NET SDK-verziókat szeretne telepíteni a gépére, látogasson el a Letöltés .NET oldalra.

Az alábbi példához hasonlóan létrehozhat egy új global.json fájlt az aktuális könyvtárban a dotnet új parancsának végrehajtásával:

dotnet new globaljson --sdk-version 6.0.100

Egyezési szabályok

Feljegyzés

Az egyező szabályokat a dotnet.exe belépési pont szabályozza, amely az összes telepített .NET-futtatókörnyezetben gyakori. A .NET-futtatókörnyezet legújabb telepített verziójára vonatkozó szabályok akkor használatosak, ha több futtatókörnyezet van egymás mellett telepítve, vagy ha global.json fájlt használ.

Az SDK melyik verziójának meghatározására a következő szabályok vonatkoznak:

Ha nem található global.json fájl, vagy global.json nem ad meg SDK-verziót allowPrerelease vagy értéket, a rendszer a legmagasabb telepített SDK-verziót használja (a beállítással rollForwardlatestMajoregyenértékű). Az előzetes SDK-verziók a meghívás módjától dotnet függnek:
- Ha nem a Visual Studióban van, a rendszer előzetes verziókat is figyelembe veszi.
- Ha a Visual Studióban van, az a kért előzetes állapotot használja. Ez azt jelzi, hogy ha a Visual Studio előzetes verzióját használja, vagy a .NET SDK -ban (az Eszközök>beállításai>környezet>előzetes verziójú funkciói területen) beállította a Használat előzetes verziót, ellenkező esetben csak a kiadási verziók tekinthetők meg.
Ha olyan global.json fájl található, amely nem ad meg SDK-verziótallowPrerelease, de értéket ad meg, a rendszer a legmagasabb telepített SDK-verziót használja (a beállítással rollForwardlatestMajoregyenértékű). Az, hogy a legújabb SDK-verzió lehet-e kiadás vagy előzetes verzió, az értéktől allowPrereleasefügg. true azt jelzi, hogy az előzetes verziókat figyelembe veszik; false azt jelzi, hogy a rendszer csak a kiadási verziókat veszi figyelembe.
Ha global.json fájl található, és az SDK-verziót adja meg:
- Ha nincs rollForward beállítva érték, az alapértelmezett rollForward szabályzatot használjalatestPatch. Ellenkező esetben ellenőrizze az egyes értékeket és azok viselkedését a rollForward szakaszban.
- Az allowPrerelease szakaszban ismertetjük, hogy a rendszer figyelembe veszi-e az előzetes verziókat, és hogy mi az alapértelmezett viselkedés, ha allowPrerelease nincs beállítva.

Összeállítási figyelmeztetések hibaelhárítása

Az alábbi figyelmeztetések azt jelzik, hogy a projekt a .NET SDK előzetes verziójával lett lefordítva:

A .NET Core SDK előzetes verziójával dolgozik. Az SDK-verziót egy global.json fájllal határozhatja meg az aktuális projektben. További információ: https://go.microsoft.com/fwlink/?linkid=869452.

A .NET előzetes verzióját használja. Lásd: https://aka.ms/dotnet-core-preview

A .NET SDK-verziók előzményei és elkötelezettsége, hogy kiváló minőségűek legyenek. Ha azonban nem szeretne előzetes verziót használni, ellenőrizze a különböző stratégiákat, amelyeket az AllowPrerelease szakaszban használhat. Azok a gépek, amelyeken még soha nem volt telepítve .NET Core 3.0 vagy újabb futtatókörnyezet vagy SDK, létre kell hoznia egy global.json fájlt, és meg kell adnia a használni kívánt verziót.
Az alábbi figyelmeztetés azt jelzi, hogy a projekt az EF Core 1.0-s vagy 1.1-es verzióját célozza, amely nem kompatibilis a .NET Core 2.1 SDK-val és újabb verzióival:

A(z) {startupProject} indítási projekt a keretrendszert célozza. NETCoreApp-verzió: "{targetFrameworkVersion}". Az Entity Framework Core .NET parancssori eszközeinek ez a verziója csak a 2.0-s vagy újabb verziót támogatja. További információ az eszközök régebbi verzióinak használatáról: https://go.microsoft.com/fwlink/?linkid=871254.

A .NET Core 2.1 SDK -tól kezdve (2.1.300-es verzió) a dotnet ef parancs az SDK részét képezi. A projekt fordításához telepítse a .NET Core 2.0 SDK-t (2.1.201-es verzió) vagy korábbi verzióját a gépére, és határozza meg a kívánt SDK-verziót a global.json fájl használatával. A parancsról további információt az dotnet ef EF Core .NET parancssori eszközeiben talál.
Ha global.json használ a .NET SDK egy adott verziójának használatához, vegye figyelembe, hogy a Visual Studio csak a .NET SDK egyetlen példányát telepíti. Ha tehát frissíti a Visual Studio-verziót, az eltávolítja annak a .NET SDK-nak az előző verzióját, amelyet az új verzió telepítéséhez használt. Akkor is eltávolítja a régi verziót, ha az egy másik fő .NET-verzió.

Annak érdekében, hogy a Visual Studio ne távolítsa el a .NET SDK verzióit, telepítenie kell a különálló .NET SDK-t a letöltési oldalról. Vegye figyelembe, hogy ha igen, akkor a .NET SDK ezen verziójának automatikus frissítése már nem fog megjelenni a Visual Studióban, és biztonsági problémák léphetnek fel.

Lásd még

A projekt SDK-k megoldása