overzicht van global.json

Artikel
01/10/2024

Dit artikel is van toepassing op: ✔️ .NET Core 3.1 SDK en latere versies

Met het global.json-bestand kunt u definiëren welke .NET SDK-versie wordt gebruikt wanneer u .NET CLI-opdrachten uitvoert. Het selecteren van de .NET SDK-versie is onafhankelijk van het opgeven van de runtimeversie van een projectdoelen. De .NET SDK-versie geeft aan welke versie van de .NET CLI wordt gebruikt. In dit artikel wordt uitgelegd hoe u de SDK-versie selecteert met behulp van global.json.

Als u altijd de nieuwste SDK-versie wilt gebruiken die op uw computer is geïnstalleerd, is er geen global.json bestand nodig. In CI-scenario's (continue integratie) wilt u echter meestal een acceptabel bereik opgeven voor de SDK-versie die wordt gebruikt. Het bestand global.json heeft een rollForward functie die flexibele manieren biedt om een acceptabel bereik van versies op te geven. Met het volgende global.json bestand selecteert u bijvoorbeeld 6.0.300 of een nieuwere functieband of patch voor 6.0 die op de computer is geïnstalleerd:

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

De .NET SDK zoekt naar een global.json-bestand in de huidige werkmap (dat niet noodzakelijkerwijs hetzelfde is als de projectmap) of een van de bovenliggende mappen.

Zie Target Frameworks voor informatie over het opgeven van de runtimeversie in plaats van de SDK-versie.

global.json schema

sdk

Type: object

Hiermee geeft u informatie over de .NET SDK te selecteren.

version

Type: string

De versie van de .NET SDK die moet worden gebruikt.

Dit veld:

Biedt geen ondersteuning voor jokertekens; Dat wil gezegd, u moet het volledige versienummer opgeven.
Biedt geen ondersteuning voor versiebereiken.

allowPrerelease

Type: boolean
Beschikbaar sinds: .NET Core 3.0 SDK.

Geeft aan of de SDK-resolver voorlopige versies moet overwegen bij het selecteren van de SDK-versie die moet worden gebruikt.

Als u deze waarde niet expliciet instelt, is de standaardwaarde afhankelijk van of u werkt vanuit Visual Studio:

Als u zich niet in Visual Studio bevindt, is truede standaardwaarde .
Als u zich in Visual Studio bevindt, wordt de aangevraagde voorlopige status gebruikt. Als u een preview-versie van Visual Studio gebruikt of als u de preview-versies van de .NET SDK-optie (onder Extra>Opties>omgevingsvoorbeeldsfuncties>) instelt, is truede standaardwaarde. Anders is falsede standaardwaarde .

rollForward

Type: string
Beschikbaar sinds: .NET Core 3.0 SDK.

Het roll-forward-beleid dat moet worden gebruikt bij het selecteren van een SDK-versie, hetzij als een terugval wanneer een specifieke SDK-versie ontbreekt of als richtlijn voor het gebruik van een hogere versie. Een versie moet worden opgegeven met een rollForward waarde, tenzij u deze instelt op latestMajor. Het standaardgedrag voor roll forward wordt bepaald door de overeenkomende regels.

Houd rekening met de volgende definities voor een SDK-versie in de indeling x.y.znnom inzicht te verkrijgen in het beschikbare beleid en hun gedrag:

x is de primaire versie.
y is de secundaire versie.
z is de functieband.
nn is de patchversie.

In de volgende tabel ziet u de mogelijke waarden voor de rollForward sleutel:

Weergegeven als	Gedrag
`patch`	Gebruikt de opgegeven versie. Als dit niet wordt gevonden, rolt u door naar het nieuwste patchniveau. Als deze niet wordt gevonden, mislukt het. Deze waarde is het verouderde gedrag van de eerdere versies van de SDK.
`feature`	Gebruikt het meest recente patchniveau voor de opgegeven primaire, secundaire en functieband. Als dit niet wordt gevonden, rolt u door naar de volgende hogere functieband binnen dezelfde primaire/secundaire band en gebruikt u het nieuwste patchniveau voor die functieband. Als deze niet wordt gevonden, mislukt het.
`minor`	Gebruikt het meest recente patchniveau voor de opgegeven primaire, secundaire en functieband. Als dit niet wordt gevonden, rolt u door naar de volgende hogere functieband binnen dezelfde primaire/secundaire versie en gebruikt u het nieuwste patchniveau voor die functieband. Als dit niet wordt gevonden, rolt u door naar de volgende hogere secundaire en functieband binnen dezelfde primaire en wordt het meest recente patchniveau voor die functieband gebruikt. Als deze niet wordt gevonden, mislukt het.
`major`	Gebruikt het meest recente patchniveau voor de opgegeven primaire, secundaire en functieband. Als dit niet wordt gevonden, rolt u door naar de volgende hogere functieband binnen dezelfde primaire/secundaire versie en gebruikt u het nieuwste patchniveau voor die functieband. Als dit niet wordt gevonden, rolt u door naar de volgende hogere secundaire en functieband binnen dezelfde primaire en wordt het meest recente patchniveau voor die functieband gebruikt. Als dit niet wordt gevonden, rolt u door naar de volgende hogere primaire, secundaire en functieband en gebruikt u het nieuwste patchniveau voor die functieband. Als deze niet wordt gevonden, mislukt het.
`latestPatch`	Gebruikt het meest recente geïnstalleerde patchniveau dat overeenkomt met de aangevraagde primaire, secundaire en functieband met een patchniveau dat groter is dan of gelijk is aan de opgegeven waarde. Als deze niet wordt gevonden, mislukt het.
`latestFeature`	Maakt gebruik van het hoogste geïnstalleerde functieband- en patchniveau dat overeenkomt met de aangevraagde primaire en secundaire waarde met een functieband en patchniveau dat groter is dan of gelijk is aan de opgegeven waarde. Als deze niet wordt gevonden, mislukt het.
`latestMinor`	Maakt gebruik van het hoogste geïnstalleerde secundaire, functieband- en patchniveau dat overeenkomt met het aangevraagde primaire niveau met een secundair, functieband en patchniveau dat groter is dan of gelijk is aan de opgegeven waarde. Als deze niet wordt gevonden, mislukt het.
`latestMajor`	Maakt gebruik van de hoogst geïnstalleerde .NET SDK met een versie die groter is dan of gelijk is aan de opgegeven waarde. Als dit niet is gevonden, mislukt u.
`disable`	Gaat niet vooruit. Er is een exacte overeenkomst vereist.

msbuild-sdks

Type: object

Hiermee kunt u de versie van de project-SDK op één plaats beheren in plaats van in elk afzonderlijk project. Zie Hoe project-SDK's worden omgezet voor meer informatie.

Opmerkingen in global.json

Opmerkingen in global.json bestanden worden ondersteund met behulp van JavaScript- of C#-stijlopmerkingen. Voorbeeld:

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

Voorbeelden

In het volgende voorbeeld ziet u hoe u geen voorlopige versies gebruikt:

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

In het volgende voorbeeld ziet u hoe u de hoogste versie gebruikt die groter of gelijk is aan de opgegeven versie. De weergegeven JSON staat geen SDK-versie toe die ouder is dan 2.2.200 en staat 2.2.200 of een latere versie toe, inclusief 3.0.xxx en 3.1.xxx.

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

In het volgende voorbeeld ziet u hoe u de exacte opgegeven versie gebruikt:

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

In het volgende voorbeeld ziet u hoe u de nieuwste functieband- en patchversie gebruikt die is geïnstalleerd op een specifieke primaire en secundaire versie. De weergegeven JSON staat geen SDK-versie toe die ouder is dan 3.1.102 en staat 3.1.102 of een latere 3.1.xxx versie toe, zoals 3.1.103 of 3.1.200.

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

In het volgende voorbeeld ziet u hoe u de hoogste patchversie gebruikt die is geïnstalleerd op een specifieke versie. De weergegeven JSON staat geen SDK-versie toe die ouder is dan 3.1.102 en staat 3.1.102 of een latere versie van 3.1.1xx toe, zoals 3.1.103 of 3.1.199.

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

global.json en de .NET CLI

Als u een SDK-versie in het global.json-bestand wilt instellen, is het handig om te weten welke SDK-versies op uw computer zijn geïnstalleerd. Zie Hoe u controleert of .NET al is geïnstalleerd voor informatie over hoe u dit doet.

Als u extra .NET SDK-versies op uw computer wilt installeren, gaat u naar de pagina .NET downloaden.

U kunt een nieuw global.json-bestand maken in de huidige map door de nieuwe dotnet-opdracht uit te voeren, vergelijkbaar met het volgende voorbeeld:

dotnet new globaljson --sdk-version 6.0.100

Overeenkomstregels

Notitie

De overeenkomende regels worden bepaald door het dotnet.exe toegangspunt, wat gebruikelijk is voor alle geïnstalleerde .NET-geïnstalleerde runtimes. De overeenkomende regels voor de meest recente geïnstalleerde versie van .NET Runtime worden gebruikt wanneer u meerdere runtimes naast elkaar hebt geïnstalleerd of als of u een global.json bestand gebruikt.

De volgende regels zijn van toepassing bij het bepalen welke versie van de SDK moet worden gebruikt:

Als er geen global.json bestand wordt gevonden of als global.json geen SDK-versie of een allowPrerelease waarde opgeeft, wordt de hoogste geïnstalleerde SDK-versie gebruikt (gelijk aan instellingrollForward).latestMajor Of prerelease-SDK-versies worden overwogen, is afhankelijk van hoe dotnet wordt aangeroepen:
- Als u zich niet in Visual Studio bevindt, worden voorlopige versies overwogen.
- Als u zich in Visual Studio bevindt, wordt de aangevraagde voorlopige status gebruikt. Als u een preview-versie van Visual Studio gebruikt of als u de preview-versies van de .NET SDK-optie gebruiken instelt (onder Functies>voor de preview-versie> van extra opties>), worden voorlopige versies overwogen. Anders worden alleen releaseversies overwogen.
Als er een global.json-bestand wordt gevonden dat geen SDK-versie opgeeft, maar wel een allowPrerelease waarde opgeeft, wordt de hoogste geïnstalleerde SDK-versie gebruikt (equivalent aan instellingrollForward).latestMajor Of de nieuwste SDK-versie release of voorlopige versie kan zijn, is afhankelijk van de waarde van allowPrerelease. true geeft aan dat voorlopige versies worden overwogen; false geeft aan dat alleen releaseversies worden overwogen.
Als er een global.json-bestand wordt gevonden en er een SDK-versie wordt opgegeven:
- Als er geen rollForward waarde is ingesteld, wordt deze gebruikt latestPatch als het standaardbeleid rollForward . Anders controleert u elke waarde en het gedrag ervan in de sectie rollForward .
- Of voorlopige versies worden overwogen en wat het standaardgedrag is wanneer allowPrerelease deze niet is ingesteld, wordt beschreven in de sectie allowPrerelease .

Problemen met buildwaarschuwingen oplossen

De volgende waarschuwingen geven aan dat uw project is gecompileerd met behulp van een voorlopige versie van de .NET SDK:

U werkt met een preview-versie van de .NET Core SDK. U kunt de SDK-versie definiëren via een global.json-bestand in het huidige project. Meer op https://go.microsoft.com/fwlink/?linkid=869452.

U gebruikt een preview-versie van .NET. Zie: https://aka.ms/dotnet-core-preview

.NET SDK-versies hebben een geschiedenis en toezegging van hoge kwaliteit. Als u echter geen voorlopige versie wilt gebruiken, controleert u de verschillende strategieën die u kunt gebruiken in de sectie allowPrerelease . Voor computers waarop nog nooit een .NET Core 3.0 of hoger runtime of SDK is geïnstalleerd, moet u een global.json-bestand maken en de exacte versie opgeven die u wilt gebruiken.
De volgende waarschuwing geeft aan dat uw project is gericht op EF Core 1.0 of 1.1, wat niet compatibel is met .NET Core 2.1 SDK en latere versies:

Opstartproject {startupProject} is gericht op framework '. NETCoreApp-versie {targetFrameworkVersion}. Deze versie van Entity Framework Core .NET-opdrachtregelprogramma's ondersteunt alleen versie 2.0 of hoger. Zie voor meer informatie over het gebruik van oudere versies van de hulpprogramma's https://go.microsoft.com/fwlink/?linkid=871254.

Vanaf .NET Core 2.1 SDK (versie 2.1.300) wordt de dotnet ef opdracht geleverd in de SDK. Als u uw project wilt compileren, installeert u .NET Core 2.0 SDK (versie 2.1.201) of eerder op uw computer en definieert u de gewenste SDK-versie met behulp van het global.json-bestand . Zie EF Core .NET-opdrachtregelprogramma's voor meer informatie over de dotnet ef opdracht.
Als u global.json gebruikt om een specifieke versie van de .NET SDK te blijven gebruiken, moet u er rekening mee houden dat Visual Studio slechts één exemplaar van de .NET SDK installeert. Dus als u uw Visual Studio-versie bijwerken, wordt de vorige versie van de .NET SDK verwijderd die is gebruikt om de nieuwe versie te installeren. Hiermee wordt de oude versie verwijderd, zelfs als het een andere primaire .NET-versie is.

Als u wilt voorkomen dat Visual Studio versies van de .NET SDK verwijdert, moet u de zelfstandige .NET SDK installeren vanaf de downloadpagina. Houd er rekening mee dat als u dat wel doet, u geen automatische updates meer ontvangt voor die versie van de .NET SDK via Visual Studio en mogelijk risico loopt op beveiligingsproblemen.

Zie ook

Hoe project-SDK's worden omgezet