Delen via

overzicht van global.json

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. 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"
  }
}

De .NET SDK zoekt naar een global.json-bestand in de huidige werkmap (die 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

Typ: object

Hiermee specificeert u de informatie om de juiste .NET SDK te selecteren.

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 vanuit Visual Studio:

  • Als u zich niet in Visual Studio bevindt, is truede standaardwaarde .
  • Als u zich in Visual Studio bevindt, wordt de aangevraagde prereleasestatus gebruikt. Als u een preview-versie van Visual Studio gebruikt of als u de optie Gebruik previews van de .NET SDK (onder Extra>Opties>Omgeving>Voorbeeldfuncties) instelt, is de standaardwaarde 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:

Value Behavior
patch Gebruikt de opgegeven versie.
Als dit niet wordt gevonden, rolt u door naar het nieuwste patchniveau.
Als deze niet wordt gevonden, mislukt de actie.

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 de actie.
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 het niet wordt gevonden, gaat het door naar de volgende hogere minor- en featureband binnen dezelfde major en wordt het laatste patchniveau voor die featureband gebruikt.
Als deze niet wordt gevonden, mislukt de actie.
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 het niet wordt gevonden, gaat het door naar de volgende hogere minor- en featureband binnen dezelfde major en wordt het laatste patchniveau voor die featureband 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 de actie.
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 de actie.
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 de actie.
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 de actie.
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 het niet wordt gevonden, mislukt het.
disable Gaat niet vooruit. Er is een exacte overeenkomst vereist.

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 commando's gebruikt die de .NET SDK gebruiken, 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"
    }
}

Het global.json-bestand 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 8.0.302 --roll-forward latestFeature

Matchingsregels

Note

De overeenkomende regels vallen onder het dotnet.exe toegangspunt, wat gebruikelijk is voor alle geïnstalleerde .NET-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 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 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 zich niet in Visual Studio bevindt, worden voorlopige versies overwogen.
    • Als u zich in Visual Studio bevindt, wordt de aangevraagde prereleasestatus gebruikt. Als u een preview-versie van Visual Studio gebruikt of als u de optie Optie voor het gebruik van previews van de .NET SDK instelt (onder Tools>Opties>Omgeving>Previewfuncties), 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 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 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 het 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 . Voor meer informatie over de dotnet ef opdracht, zie EF Core .NET opdrachtregelprogramma's.

  • 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, installeert u de zelfstandige .NET SDK vanaf de downloadpagina. 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

  • Last updated on