Delen via

Selecteer de .NET-versie die u wilt gebruiken

  • Artikel

In dit artikel worden de beleidsregels uitgelegd die worden gebruikt door de .NET-hulpprogramma's, SDK en runtime voor het selecteren van versies. Deze beleidsregels bieden een balans tussen het uitvoeren van toepassingen met behulp van de opgegeven versies en het inschakelen van een gemakkelijke upgrade van zowel ontwikkelaars- als eindgebruikerscomputers. Met deze beleidsregels kunt u het volgende inschakelen:

  • Eenvoudige en efficiënte implementatie van .NET, inclusief beveiligings- en betrouwbaarheidsupdates.
  • Gebruik de nieuwste hulpprogramma's en opdrachten onafhankelijk van de doelruntime.

Versieselectie vindt plaats:

In de rest van dit document worden deze vier scenario's onderzocht.

De SDK maakt gebruik van de meest recente geïnstalleerde versie

SDK-opdrachten bevatten dotnet new en dotnet run. De .NET CLI moet een SDK-versie kiezen voor elke dotnet opdracht. Deze maakt standaard gebruik van de nieuwste SDK die op de computer is geïnstalleerd, zelfs als:

  • Het project is gericht op een eerdere versie van de .NET-runtime.
  • De nieuwste versie van de .NET SDK is een preview-versie.

U kunt profiteren van de nieuwste SDK-functies en -verbeteringen terwijl u zich richt op eerdere .NET Runtime-versies. U kunt zich richten op verschillende runtimeversies van .NET met dezelfde SDK-hulpprogramma's.

In sommige gevallen moet u mogelijk een specifieke versie van de SDK gebruiken. U geeft die versie op in een global.json bestand.

global.json kan overal in de bestandshiërarchie worden geplaatst. U bepaalt op welke projecten een bepaalde global.json van toepassing is op de plaats ervan in het bestandssysteem. De .NET CLI zoekt naar een global.json bestand dat iteratief door het pad naar boven navigeert vanuit de huidige werkmap (dat niet noodzakelijkerwijs hetzelfde is als de projectmap). Het eerste global.json bestand dat is gevonden, geeft de gebruikte versie aan. Als die SDK-versie is geïnstalleerd, wordt die versie gebruikt. Als de SDK die is opgegeven in de global.json niet wordt gevonden, gebruikt de .NET CLI overeenkomende regels om een compatibele SDK te selecteren of mislukt als er geen is gevonden.

In het volgende voorbeeld ziet u de global.json syntaxis:

{
  "sdk": {
    "version": "5.0.0"
  }
}

Het proces voor het selecteren van een SDK-versie is:

  1. dotnet zoekt naar een global.json bestand door het pad iteratief omhoog te volgen vanaf de huidige werkmap.
  2. dotnet gebruikt de SDK die is opgegeven in de eerste gevonden global.json.
  3. dotnet de meest recente geïnstalleerde SDK gebruikt als er geen global.json wordt gevonden.

Zie de overeenkomende regels en rollForward secties van het global.json overzicht artikel voor meer informatie over het selecteren van SDK-versies.

De SDK-versie bijwerken

Het is belangrijk om regelmatig bij te werken naar de nieuwste versie van de SDK om de nieuwste functies, prestatieverbeteringen en oplossingen voor fouten te gebruiken. Gebruik de opdracht dotnet sdk checkom eenvoudig te controleren op updates voor de SDK. Als u bovendien een specifieke versie selecteert met behulp van global.json, kunt u een hulpprogramma zoals Dependabot overwegen om de vastgemaakte SDK-versie automatisch bij te werken wanneer er nieuwe versies beschikbaar komen.

Monikers van het doelframework definiëren buildtijd-API's

U bouwt uw project op basis van API's die zijn gedefinieerd in een target framework moniker (TFM). U bepaalt het doelframework in het projectbestand. Stel het element TargetFramework in het projectbestand in, zoals wordt weergegeven in het volgende voorbeeld:

<TargetFramework>net8.0</TargetFramework>

U kunt uw project ontwikkelen voor meerdere TFM's. Het instellen van meerdere doelframeworks is gebruikelijker voor bibliotheken, maar kan ook worden uitgevoerd met toepassingen. U geeft een TargetFrameworks eigenschap op (meervoud van TargetFramework). De doelframeworks zijn door puntkomma's gescheiden, zoals wordt weergegeven in het volgende voorbeeld:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Een bepaalde SDK ondersteunt een vaste set frameworks, beperkt tot het doelframework van de runtime waarmee deze wordt geleverd. De .NET 8 SDK bevat bijvoorbeeld de .NET 8-runtime. Dit is een implementatie van het net8.0-doelframework. De .NET 8 SDK ondersteunt net7.0, net6.0en net5.0, maar niet net9.0 (of hoger). U installeert de .NET 9 SDK om te bouwen voor net9.0.

.NET Standard

.NET Standard was een manier om een API-oppervlak te richten dat wordt gedeeld door verschillende implementaties van .NET. Vanaf de release van .NET 5, een API-standaard zelf, heeft .NET Standard weinig relevantie, met uitzondering van één scenario: .NET Standard is handig als u zowel .NET als .NET Framework wilt targeten. .NET 5 implementeert alle .NET Standard-versies.

Zie .NET 5 en .NET Standardvoor meer informatie.

Framework-afhankelijke apps voortschrijden

Wanneer u een applicatie uitvoert vanuit de bron met dotnet run, vanuit een frameworkafhankelijke implementatie met dotnet myapp.dll, of vanuit een frameworkafhankelijk uitvoerbaar bestand met myapp.exe, is het dotnet uitvoerbare bestand de host voor de applicatie.

De host kiest de meest recente patchversie die op de computer is geïnstalleerd. Als u bijvoorbeeld net5.0 hebt opgegeven in uw projectbestand en 5.0.2 de meest recente .NET-runtime is geïnstalleerd, wordt de 5.0.2 runtime gebruikt.

Als er geen acceptabele 5.0.* versie wordt gevonden, wordt een nieuwe 5.* versie gebruikt. Als u bijvoorbeeld net5.0 hebt opgegeven en alleen 5.1.0 is geïnstalleerd, wordt de toepassing uitgevoerd met behulp van de 5.1.0 runtime. Dit gedrag wordt 'secundaire versie roll-forward' genoemd. Lagere versies worden ook niet meegenomen. Wanneer er geen acceptabele runtime is geïnstalleerd, wordt de toepassing niet uitgevoerd.

Enkele gebruiksvoorbeelden laten het gedrag zien als u zich richt op 5.0:

  • ✔️ 5.0 is opgegeven. 5.0.3 is de hoogste patchversie geïnstalleerd. 5.0.3 wordt gebruikt.
  • ❌ 5.0 is opgegeven. Er zijn geen 5.0.* versies geïnstalleerd. 3.1.1 is de hoogste runtime geïnstalleerd. Er wordt een foutbericht weergegeven.
  • ✔️ 5.0 is opgegeven. Er zijn geen 5.0.* versies geïnstalleerd. 5.1.0 is de hoogste runtimeversie geïnstalleerd. 5.1.0 wordt gebruikt.
  • ❌ 3.0 is opgegeven. Er zijn geen 3.x-versies geïnstalleerd. 5.0.0 is de hoogste runtime geïnstalleerd. Er wordt een foutbericht weergegeven.

De roll-forward van een kleinere versie heeft één neveneffect dat invloed kan hebben op eindgebruikers. Houd rekening met het volgende scenario:

  1. De toepassing geeft aan dat 5.0 vereist is.
  2. Wanneer het programma wordt uitgevoerd, is versie 5.0.* niet geïnstalleerd, maar 5.1.0 wel. Versie 5.1.0 wordt gebruikt.
  3. Later installeert de gebruiker 5.0.3 en wordt de toepassing opnieuw uitgevoerd. 5.0.3 wordt nu gebruikt.

Het is mogelijk dat 5.0.3 en 5.1.0 zich anders gedragen, met name voor scenario's zoals het serialiseren van binaire gegevens.

Beheer van vooruitrolgedrag

Voordat u het standaardgedrag van de roll-forward overschrijft, moet u vertrouwd raken met het niveau van .NET Runtime-compatibiliteit.

Het roll-forward-gedrag voor een toepassing kan op vier verschillende manieren worden geconfigureerd:

  1. Instelling op projectniveau via de eigenschap <RollForward>:

    <PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

  2. Het bestand *.runtimeconfig.json.

    Dit bestand wordt geproduceerd wanneer u uw toepassing compileert. Als de eigenschap <RollForward> is ingesteld in het project, wordt deze in het *.runtimeconfig.json-bestand gereproduceerd als de rollForward instelling. Gebruikers kunnen dit bestand bewerken om het gedrag van uw toepassing te wijzigen.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. De eigenschap --roll-forward <value> van de dotnet opdracht.

    Wanneer u een toepassing uitvoert, kunt u het gedrag van de roll-forward beheren via de opdrachtregel:

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. De omgevingsvariabele DOTNET_ROLL_FORWARD.

Voorrang

Gedrag voor doorsturen wordt ingesteld op de volgende volgorde wanneer uw app wordt uitgevoerd, hogere genummerde items hebben voorrang op lagere genummerde items:

  1. Eerst wordt het *.runtimeconfig.json configuratiebestand geëvalueerd.
  2. Vervolgens wordt de omgevingsvariabele DOTNET_ROLL_FORWARD overwogen, waardoor de vorige controle teniet wordt gedaan.
  3. Ten slotte overschrijft elke --roll-forward parameter die wordt doorgegeven aan de actieve toepassing alles.

Waarden

Hoe u ook de roll-forward-instelling instelt, gebruik een van de volgende waarden om het gedrag te bepalen:

Waarde Beschrijving
Minor standaard indien niet opgegeven.
Roll-forward naar de laagste hogere secundaire versie, als de aangevraagde secundaire versie ontbreekt. Als de aangevraagde secundaire versie aanwezig is, wordt het LatestPatch-beleid gebruikt.
Major Roll-forward naar de volgende beschikbare hogere hoofdversie en laagste subversie, als de aangevraagde hoofdversie ontbreekt. Als de aangevraagde primaire versie aanwezig is, wordt het Minor-beleid gebruikt.
LatestPatch Doorsturen naar de hoogste patchversie. Met deze waarde wordt het terugdraaien van secundaire versies uitgeschakeld.
LatestMinor Doorsturen naar de hoogste secundaire versie, zelfs als de aangevraagde secundaire versie aanwezig is.
LatestMajor Update naar de hoogste hoofd- en ondergeschikte versie, zelfs als de aangevraagde hoofdlijn al aanwezig is.
Disable Niet voortuitrollen, maar alleen binden aan de opgegeven versie. Dit beleid wordt niet aanbevolen voor algemeen gebruik, omdat hiermee de mogelijkheid om door te schakelen naar de nieuwste patches wordt uitgeschakeld. Deze waarde wordt alleen aanbevolen voor testen.

Zelfstandige implementaties omvatten de geselecteerde runtime

U kunt een toepassing publiceren als een zelfstandige distributie. Met deze benadering worden de .NET-runtime en -bibliotheken gebundeld met uw toepassing. Zelfstandige implementaties hebben geen afhankelijkheid van runtime-omgevingen. Runtimeversieselectie vindt plaats tijdens het publiceren, niet tijdens de uitvoering.

De herstel gebeurtenis die optreedt wanneer er wordt gepubliceerd, selecteert de meest recente patchversie van de opgegeven runtimefamilie. dotnet publish selecteert bijvoorbeeld .NET 5.0.3 als dit de meest recente patchversie in de .NET 5 Runtime-serie is. Het doelframework (inclusief de meest recente geïnstalleerde beveiligingspatches) is verpakt met de toepassing.

Er treedt een fout op als niet wordt voldaan aan de minimale versie die is opgegeven voor een toepassing. dotnet publish wordt gebonden aan de nieuwste runtime-patchversie (binnen een bepaalde major.minor-versiefamilie). dotnet publish biedt geen ondersteuning voor de roll-forward semantiek van dotnet run. Bekijk het artikel over runtime patchselectie bij het implementeren van .NET-toepassingen voor meer informatie over patches en zelfstandige implementaties.

Voor zelfstandige implementaties is mogelijk een specifieke patchversie vereist. U kunt de minimale runtimepatchversie (naar hogere of lagere versies) in het projectbestand overschrijven, zoals wordt weergegeven in het volgende voorbeeld:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Het RuntimeFrameworkVersion-element overschrijft het standaardversiebeleid. Voor zelfstandige implementaties geeft de RuntimeFrameworkVersion de exacte versie van runtimeframework op. Voor frameworkafhankelijke toepassingen geeft de RuntimeFrameworkVersion de minimale vereiste runtime-frameworkversie op.

Zie ook