overzicht van global.json

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

Met het bestand global.json 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. Het volgende global.json bestand selecteert bijvoorbeeld 10.0.100 of een nieuwere functieband of patch voor 10.0 die op de computer is geïnstalleerd:

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

U bent afhankelijk van twee onderdelen in de .NET SDK om te zoeken naar een global.json-bestand. Elk onderdeel begint vanaf een andere locatie en zoekt naar bovengelegen directories.

• .NET SDK muxer verwerkt dotnet CLI-opdrachten. Het begint met de huidige werkmap, die niet noodzakelijkerwijs hetzelfde is als de projectmap.
• .NET MSBuild project SDK-resolver lost project-SDK's op tijdens het bouwen. Het begint vanuit de map die een oplossingsbestand bevat, als er een bestaat. Als er geen oplossingsbestand bestaat, wordt het gestart vanuit de map die het huidige projectbestand bevat. Als geen van beide bestanden bestaat, wordt de huidige werkmap gebruikt.

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

global.json schema

sdk

Typ: object

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

version

• Typ: string

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

Dit veld:

• Vereist het volledige versienummer, zoals 10.0.100.
• Biedt geen ondersteuning voor versienummers zoals 10, 10.0 of 10.0.x.
• Er is geen ondersteuning voor jokertekens.
• Biedt geen ondersteuning voor versiebereiken.

allowPrerelease

• Typ: 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 vanaf Visual Studio:

• Als u not in Visual Studio bent, is de standaardwaarde true.
• Als u zich in Visual Studio bevindt, wordt de aangevraagde voorlopige status gebruikt. Dat wil gezegd, als u een preview-versie van Visual Studio gebruikt of als u de optie Voorbeelden van de .NET SDK instelt (onder Tools>Options>Omgeving>Preview-functies), de standaardwaarde is true. Anders is falsede standaardwaarde .

rollForward

• Typ: 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 latere 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 kleine versie.
• z is de kenmerkband.
• nn is de patch-versie.

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

paths

• Type: Matrix van string
• Beschikbaar sinds: .NET 10 SDK.

Hiermee geeft u de locaties op die moeten worden overwogen bij het zoeken naar een compatibele .NET SDK. Paden kunnen absoluut of relatief zijn ten opzichte van de locatie van het global.json-bestand . De speciale waarde $host$ vertegenwoordigt de locatie die overeenkomt met het actieve dotnet uitvoerbare bestand.

Deze paden worden doorzocht in de volgorde waarin ze zijn gedefinieerd en de eerste overeenkomende SDK wordt gebruikt.

Met deze functie kunt u lokale SDK-installaties (zoals SDK's ten opzichte van de hoofdmap van een opslagplaats of in een aangepaste map) gebruiken die niet globaal op het systeem zijn geïnstalleerd.

De functie Paden werkt alleen wanneer u opdrachten gebruikt die de .NET SDK inschakelen, zoals dotnet run. Het heeft geen invloed op scenario's zoals het uitvoeren van het systeemeigen startprogramma voor apphost (app.exe), uitvoeren met dotnet app.dllof uitvoeren met dotnet exec app.dll. Als u de functie "paden" wilt gebruiken, moet u SDK-opdrachten zoals dotnet run.

errorMessage

• Typ: string
• Beschikbaar sinds: .NET 10 SDK.

Hiermee geeft u een aangepast foutbericht op dat wordt weergegeven wanneer de SDK-resolver geen compatibele .NET SDK kan vinden.

msbuild-sdks

Typ: object

Hiermee kunt u de versie van de project-SDK op één plaats beheren in plaats van in elk afzonderlijk project. Voor meer informatie, zie Hoe project-SDK's worden opgelost.

test

• Typ: object

Geeft informatie over tests.

runner

• Typ: string
• Beschikbaar sinds: .NET 10.0 SDK.

De testloper waarmee tests kunnen worden opgespoord/uitgevoerd.

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": "8.0.300" /* This is comment 2*/
  /* This is a
  multiline comment.*/
  }
}

Examples

In het volgende voorbeeld ziet u hoe u het gebruik van voorlopige versies kunt weigeren:

{
  "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 7.0.200 en staat 7.0.200 of een latere versie toe, inclusief 8.0.xxx.

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

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

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.302 en staat 8.0.302 of een latere 8.0.xxx versie toe, zoals 8.0.303 of 8.0.402.

{
  "sdk": {
    "version": "8.0.302",
    "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 8.0.102 en staat 8.0.102 of een latere versie van 8.0.1xx toe, zoals 8.0.103 of 8.0.199.

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

In het volgende voorbeeld ziet u hoe u aanvullende SDK-zoekpaden en een aangepast foutbericht opgeeft:

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

In het volgende voorbeeld wordt een ongeldige opgegeven versie getoond. In de uitvoer van de opdracht dotnet --info wordt het foutbericht weergegeven: 'Versie 10.0 is niet geldig voor de waarde sdk/versie'.

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

In het volgende voorbeeld ziet u hoe u Microsoft.Testing.Platform als testrunner specificeert:

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

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 Het controleren of .NET al is geïnstalleerd voor meer informatie over hoe u dit doet.

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

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

Matchingsregels

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 global.json geeft geen SDK-versie en geen allowPrerelease-waarde op, wordt de hoogste geïnstalleerde SDK-versie gebruikt (gelijk aan het instellen van rollForward op latestMajor). Of prerelease-SDK-versies worden overwogen, is afhankelijk van hoe dotnet wordt aangeroepen:

  • Als u niet in Visual Studio bent, worden voorlopige versies in overweging genomen.
  • Als u zich in Visual Studio bevindt, wordt de aangevraagde voorlopige status gebruikt. Dat wil gezegd, als u een preview-versie van Visual Studio gebruikt of als u de optie Voorbeelden van de .NET SDK instelt (onder Tools>Options>Omgeving>Preview-functies), prereleaseversies worden overwogen; anders worden alleen releaseversies overwogen.

• Als er een global.json-bestand wordt gevonden dat geen SDK-versie opgeeft, maar wel een allowPrerelease waarde beschikt, wordt de hoogste geïnstalleerde SDK-versie gebruikt (equivalent aan rollForward instellen op 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 patch als standaard rollForward beleid gebruikt. Anders controleert u elke waarde en het gedrag ervan in de sectie rollForward .
  • Of voorlopige versies in beschouwing worden genomen en wat het standaardgedrag is wanneer allowPrerelease niet is ingesteld, wordt beschreven in de allowPrerelease-sectie.

Waarschuwingen bij build oplossen

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

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

  .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 bestand global.json 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 het framework '.NETCoreApp' versie {targetFrameworkVersion}. Deze versie van de 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 opdracht dotnet ef 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 bestand global.json. Raadpleeg EF Core .NET Opdrachtregelhulpprogramma's voor meer informatie over de opdracht dotnet ef.

• Als u global.json gebruikt om een specifieke versie van de .NET SDK te 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. De oude versie wordt verwijderd, zelfs als deze een andere primaire .NET versie is.

Installeer de zelfstandige .NET SDK van de downloadpagina om te voorkomen dat Visual Studio versies van de .NET SDK verwijdert. Als u dit doet, ontvangt u echter geen automatische updates meer voor die versie van de .NET SDK via Visual Studio en loopt u mogelijk risico op beveiligingsproblemen.

Zie ook

• Hoe project-SDK's worden bepaald