global.json áttekintése

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 melyik .NET SDK-verziót használja .NET PARANCSSOR-parancsok futtatásakor. 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 10.0.100-as vagy annál újabb, a számítógépre telepített 10.0-hoz tartozó funkciósávot vagy javítást választja ki:

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

A .NET SDK két összetevőjére támaszkodva kereshet egy global.json fájlt. Minden összetevő egy másik helyről indul, és az őskönyvtárakon keresztül keres:

• .NET SDK muxer kezeli a dotnet CLI parancsokat. Az aktuális munkakönyvtárból indul ki, amely nem feltétlenül ugyanaz, mint a projektkönyvtár.
• .NET MSBuild project SDK resolver a buildek során feloldja a projekt SDK-jait. A megoldásfájlt tartalmazó könyvtárból indul, ha létezik ilyen. Ha nincs megoldásfájl, az az aktuális projektfájlt tartalmazó könyvtárból indul ki. Ha egyik fájl sem létezik, az aktuális munkakönyvtárat használja.

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

A kijelölendő .NET SDK-val kapcsolatos információkat adja meg.

version

• Típus: string

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

Ez a mező:

• A teljes verziószámot( például 10.0.100) igényli.
• Nem támogatja az olyan verziószámokat, mint a 10, a 10.0 vagy a 10.0.x.
• Nem támogatja a helyettesítő karaktereket.
• 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 Studio fut-e:

• Ha nem vagy a Visual Studio-ban, az alapértelmezett érték true.
• Ha a Visual Studio-t használja, az a kért előzetes állapotot használja. Vagyis: ha a Visual Studio előzetes verzióját használja, vagy beállítja a .NET SDK előzetes verziójának használata lehetőséget (az Eszközök>Beállítások>Környezet>Előzetes Funkciók alatt), az alapértelmezett érték 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 későbbi verzió használatára. Egy verziót meg kell adni egy rollForward értékkel, kivéve, ha azt az értéket állítja be latestMajor. Az alapértelmezett továbbgörgetési magatartá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 a kisebb verzió.
• z a jellemző sáv.
• nn a javítás verziója.

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

Value	Behavior
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ó, előrelép a következő, magasabb szintű fő-, al- és funkciósávra, é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.

paths

• Típus: Tömb elemekből string
• Azóta elérhető: .NET 10 SDK.

Megadja azokat a helyeket, amelyeket figyelembe kell venni egy kompatibilis .NET SDK keresésekor. Az elérési utak lehetnek abszolútak vagy a global.json fájl helyéhez viszonyítva. A speciális érték $host$ a futtatható dotnet végrehajtható fájlnak megfelelő helyet jelöli.

Ezeket az elérési utakat a definiált sorrendben keresik meg, és az első egyező SDK-t használják.

Ez a funkció lehetővé teszi a helyi SDK-telepítéseket (például az adattár gyökeréhez képest vagy egyéni mappába helyezett SDK-k használatát), amelyek nincsenek globálisan telepítve a rendszeren.

Az "elérési utak" funkció csak akkor működik, ha olyan parancsokat használ, amelyek a .NET SDK-t használják, például dotnet run. EZ NEM érinti az olyan helyzeteket, mint például a natív apphost programindító (app.exe), a futtatás dotnet app.dll vagy a vele dotnet exec app.dll való futtatás. Az "elérési utak" funkció használatához olyan SDK-parancsokat kell használnia, mint a dotnet run.

errorMessage

• Típus: string
• Azóta elérhető: .NET 10 SDK.

Egyéni hibaüzenetet ad meg, amely akkor jelenik meg, ha az SDK-feloldó nem talál kompatibilis .NET SDK-t.

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.

test

• Típus: object

A tesztekkel kapcsolatos információkat adja meg.

runner

• Típus: string
• Azóta elérhető: .NET 10.0 SDK.

A tesztfuttató, amellyel felderítheti/futtathatja a teszteket.

Megjegyzések a "global.json" fájlba

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

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

Examples

Az alábbi példa bemutatja, hogyan tilthatja le a prerelease-verziók használatát:

{
  "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 letiltja a 7.0.200-nál korábbi SDK-verziókat, és engedélyezi a 7.0.200-es vagy újabb verziót, beleértve a 8.0.xxx.

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

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

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.302-nél korábbi SDK-verziókat, és engedélyezi a 8.0.302-es vagy újabb 8.0.xxx verziót, például a 8.0.303-as vagy a 8.0.402-es verziót.

{
  "sdk": {
    "version": "8.0.302",
    "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 letiltja a 8.0.102-nél korábbi SDK-verziókat, és engedélyezi a 8.0.102-es vagy újabb 8.0.1xx verziót, például a 8.0.103-as vagy a 8.0.199-es verziót.

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

Az alábbi példa bemutatja, hogyan adhat meg további SDK-keresési útvonalakat és egy egyéni hibaüzenetet:

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

Az alábbi példában egy érvénytelen verzió van megadva. A parancs dotnet --info kimenete a következő hibaüzenetet jeleníti meg: "A 10.0-s verzió nem érvényes az "sdk/version" értékre."

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

Az alábbi példa bemutatja, hogyan adható meg Microsoft.Testing.Platform tesztfuttatóként:

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

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 a Hogyan ellenőrizheti, hogy a .NET már telepítve van.

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

Egyezési szabályok

Note

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álhatók, 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 a global.json nem határoz meg SDK-verziót és nem ad meg egy allowPrerelease értéket, akkor a legmagasabb telepített SDK-verzió kerül felhasználásra (ami egyenértékű azzal, hogy beállítjuk rollForward-et latestMajor-re). Az, hogy az előzetes SDK-verziók mérlegelésre kerülnek-e, attól függ, hogyan hívják meg a dotnet-t.

  • Ha nem a Visual Studio-ban van, az előzetes verziókat is figyelembe vesszük.
  • Ha a Visual Studio-t használja, az a kért előzetes állapotot használja. Vagyis: ha a Visual Studio előzetes verzióját használja, vagy beállítja az .NET SDK előnézeti verzióinak használata lehetőséget (az Eszközök>Beállítások>Környezet>Előzetes funkciók alatt), akkor az előzetes verziókat veszik figyelembe; ellenkező esetben csak a kiadási verziókat veszik figyelembe.

• 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 érték beállítva, az alapértelmezett patch szabályzatot használjarollForward. Ellenkező esetben ellenőrizze az egyes értékeket és azok viselkedését a rollForward szakaszban.
  • Az allowPrereleaseallowPrerelease, hogy a rendszer figyelembe veszi-e az előzetes verziókat, és hogy mi az alapértelmezett viselkedés, ha 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 előzetes verzióját használja. Lásd: https://aka.ms/dotnet-support-policy

  A .NET SDK-verziók történelme és elkötelezettsége a kiváló minőség mellett áll. 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. Olyan gépek esetében, amelyeken még 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 .NET Core 2.1 SDK-val és újabb verzióival:

  A(z) '{startupProject}' indítási projekt a '.NETCoreApp' keretrendszer '{targetFrameworkVersion}' verzióját célozza. A Entity Framework Core .NET parancssori eszközök ezen 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észe. 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 dotnet ef parancsról további információt a EF Core .NET Parancssori eszközök című témakörben talál.

• Ha global.json használatával marad a .NET SDK egy adott verzióján, vegye figyelembe, hogy Visual Studio csak a .NET SDK egyetlen példányát telepíti. Ha tehát frissíti a Visual Studio verzióját, az eltávolítja az új verzió telepítéséhez használt .NET SDK előző verzióját. Akkor is eltávolítja a régi verziót, ha az egy másik fő .NET verzió.

A Visual Studio .NET SDK verzióinak eltávolításának elkerülése érdekében telepítse a különálló .NET SDK-t a letöltési oldalról. Ha azonban így tesz, a .NET SDK ezen verziójának automatikus frissítése már nem fog megjelenni a Visual Studio keresztül, és biztonsági problémákat is veszélyeztethet.

Lásd még

• A projekt SDK-k megoldása