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 zijn onder andere dotnet new en dotnet run. De .NET CLI moet voor elke dotnet opdracht een SDK-versie kiezen. 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 zeldzame gevallen moet u mogelijk een eerdere versie van de SDK gebruiken. U geeft die versie op in een global.json-bestand. Het beleid 'nieuwste gebruik' betekent dat u alleen global.json gebruikt om een .NET SDK-versie op te geven die ouder is dan de meest recente geïnstalleerde versie.

global.json kan overal in de bestandshiërarchie worden geplaatst. De CLI zoekt omhoog vanuit de projectmap naar de eerste global.json die wordt gevonden. U bepaalt op welke projecten een bepaalde global.json van toepassing is op de plaats in het bestandssysteem. De .NET CLI zoekt naar een global.json bestand dat iteratief door het pad naar boven navigeert vanuit de huidige werkmap. Het eerste global.json bestand dat wordt 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 iteratief om het pad naar boven te navigeren vanuit de huidige werkmap.
  2. dotnet gebruikt de SDK die is opgegeven in de eerste global.json gevonden.
  3. dotnet gebruikt de meest recente geïnstalleerde SDK als er geen global.json wordt gevonden.

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

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

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

<TargetFramework>net8.0</TargetFramework>

U kunt uw project bouwen op basis van 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 , maar net5.0niet net9.0 (of hoger). U installeert de .NET 9 SDK om voor net9.0te bouwen.

.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 Standard voor meer informatie.

Frameworkafhankelijke apps roll-forward

Wanneer u een toepassing uitvoert vanuit een bron metdotnet run, van een frameworkafhankelijke implementatie met dotnet myapp.dllof van een frameworkafhankelijk uitvoerbaar bestand metmyapp.exe, is het uitvoerbare bestand de dotnethost voor de toepassing.

De host kiest de meest recente patchversie die op de computer is geïnstalleerd. Als u bijvoorbeeld hebt opgegeven net5.0 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 hebt opgegeven net5.0 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 secundaire versie heeft één neveneffect dat van invloed kan zijn op eindgebruikers. Bekijk het volgende scenario:

  1. De toepassing geeft aan dat 5.0 vereist is.
  2. Wanneer deze wordt uitgevoerd, is versie 5.0.* niet geïnstalleerd, maar 5.1.0 is. 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.

Gedrag voor het doorsturen van besturingselementen

Voordat u het standaardgedrag voor roll-forward overschrijft, moet u vertrouwd raken met het niveau van .NET-runtimecompatibiliteit.

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

  1. Instelling op projectniveau door de eigenschap in te <RollForward> stellen:

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

  2. Het *.runtimeconfig.json bestand.

    Dit bestand wordt geproduceerd wanneer u uw toepassing compileert. Als de <RollForward> eigenschap 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 van --roll-forward <value> 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 DOTNET_ROLL_FORWARD omgevingsvariabele.

Prioriteit

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 DOTNET_ROLL_FORWARD omgevingsvariabele overwogen, waarbij de vorige controle wordt overschreven.
  3. Ten slotte overschrijft elke --roll-forward parameter die wordt doorgegeven aan de actieve toepassing alles.

Waarden

Gebruik echter een van de volgende waarden om het gedrag in te stellen:

Weergegeven als 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 primaire versie en laagste secundaire versie, als de aangevraagde primaire versie 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 Roll-forward naar de hoogste primaire en hoogste secundaire versie, zelfs als de aangevraagde primaire is aanwezig.
Disable Roll-forward niet, 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 runtime.

De herstel gebeurtenis die optreedt bij het publiceren, selecteert de meest recente patchversie van de opgegeven runtimefamilie. Selecteer bijvoorbeeld dotnet publish .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 semantiek van roll-forward van dotnet run. Zie het artikel over runtimepatchselectie 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 u RuntimeFrameworkVersion de exacte versie van het runtime-framework op. Voor frameworkafhankelijke toepassingen geeft u de RuntimeFrameworkVersionminimaal vereiste runtime-frameworkversie op.

Zie ook