Välj den .NET-version som ska användas

Artikel
03/05/2024

I den här artikeln beskrivs de principer som används av .NET-verktyg, SDK och körning för att välja versioner. Dessa principer ger en balans mellan att köra program med hjälp av de angivna versionerna och att göra det enkelt att uppgradera både utvecklar- och slutanvändardatorer. Dessa principer aktiverar:

Enkel och effektiv distribution av .NET, inklusive säkerhets- och tillförlitlighetsuppdateringar.
Använd de senaste verktygen och kommandona oberoende av målkörning.

Versionsval sker:

När du kör ett SDK-kommando använder SDK:et den senaste installerade versionen.
När du skapar en sammansättning definierar målramverksmonikers API:er för byggtid.
När du kör ett .NET-program rullar målramverksberoende appar framåt.
När du publicerar ett fristående program inkluderar fristående distributioner den valda körningen.

Resten av det här dokumentet undersöker dessa fyra scenarier.

SDK använder den senaste installerade versionen

SDK-kommandona inkluderar dotnet new och dotnet run. .NET CLI måste välja en SDK-version för varje dotnet kommando. Den använder den senaste SDK:t som är installerad på datorn som standard, även om:

Projektet riktar sig mot en tidigare version av .NET-körningen.
Den senaste versionen av .NET SDK är en förhandsversion.

Du kan dra nytta av de senaste SDK-funktionerna och förbättringarna när du riktar in dig på tidigare .NET-körningsversioner. Du kan rikta in dig på olika körningsversioner av .NET med samma SDK-verktyg.

I sällsynta fall kan du behöva använda en tidigare version av SDK:et. Du anger den versionen i en global.json fil. Principen "Använd senaste" innebär att du bara använder global.json för att ange en tidigare .NET SDK-version än den senaste installerade versionen.

global.json kan placeras var som helst i filhierarkin. CLI söker uppåt från projektkatalogen efter den första global.json den hittar. Du styr vilka projekt som en viss global.json gäller för genom dess plats i filsystemet. .NET CLI söker efter en global.json fil som iterativt navigerar sökvägen uppåt från den aktuella arbetskatalogen. Den första global.json filen som hittades anger vilken version som används. Om SDK-versionen är installerad används den versionen. Om SDK:t som anges i global.json inte hittas använder .NET CLI matchande regler för att välja ett kompatibelt SDK eller misslyckas om inget hittas.

I följande exempel visas global.json syntax:

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

Processen för att välja en SDK-version är:

dotnet söker efter en global.json fil som iterativt omvänt navigerar sökvägen uppåt från den aktuella arbetskatalogen.
dotnet använder det SDK som angavs i den första global.json hittades.
dotnet använder den senaste installerade SDK:n om ingen global.json hittas.

Mer information om val av SDK-version finns i avsnittet Matchningsregler och rollForward i artikeln global.json översikt .

Målramverksmonikers definierar API:er för byggtid

Du skapar projektet mot API:er som definierats i en målramverksmoniker (TFM). Du anger målramverket i projektfilen. Ange elementet TargetFramework i projektfilen enligt följande exempel:

<TargetFramework>net8.0</TargetFramework>

Du kan skapa projektet mot flera TFM:er. Det är vanligare att ange flera målramverk för bibliotek, men det kan även göras med program. Du anger en TargetFrameworks egenskap (plural av TargetFramework). Målramverken är semikolonavgränsade enligt följande exempel:

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

En viss SDK stöder en fast uppsättning ramverk som är begränsade till målramverket för den körning som det levereras med. Till exempel innehåller .NET 8 SDK .NET 8-körningen, som är en implementering av net8.0 målramverket. .NET 8 SDK stöder net7.0, net6.0och net5.0, men inte net9.0 (eller högre). Du installerar .NET 9 SDK för att skapa för net9.0.

.NET Standard

.NET Standard var ett sätt att rikta in sig på en API-yta som delas av olika implementeringar av .NET. Från och med lanseringen av .NET 5, som är en API-standard, har .NET Standard liten relevans, förutom ett scenario: .NET Standard är användbart när du vill rikta in dig på både .NET och .NET Framework. .NET 5 implementerar alla .NET Standard-versioner.

Mer information finns i .NET 5 och .NET Standard.

Roll-forward för ramverksberoende appar

När du kör ett program från källan med dotnet run, från en ramverksberoende distribution med dotnet myapp.dlleller från en ramverksberoende körbar fil med myapp.exe, är den dotnet körbara filen värd för programmet.

Värden väljer den senaste korrigeringsversionen som är installerad på datorn. Om du till exempel har angett net5.0 i projektfilen och 5.0.2 är den senaste .NET-körningen installerad används körningen 5.0.2 .

Om ingen godtagbar 5.0.* version hittas används en ny 5.* version. Om du till exempel har angett net5.0 och endast 5.1.0 är installerad körs programmet med hjälp av körningen 5.1.0 . Det här beteendet kallas för "delversionsdistribution". Lägre versioner kommer inte heller att beaktas. När ingen acceptabel körning har installerats körs inte programmet.

Några användningsexempel visar beteendet om du riktar in dig på 5.0:

✔️ 5.0 har angetts. 5.0.3 är den högsta installerade korrigeringsversionen. 5.0.3 används.
❌ 5.0 har angetts. Inga 5.0.*-versioner är installerade. 3.1.1 är den högsta körningen som installerats. Ett felmeddelande visas.
✔️ 5.0 har angetts. Inga 5.0.*-versioner är installerade. 5.1.0 är den högsta körningsversionen installerad. 5.1.0 används.
❌ 3.0 har angetts. Inga 3.x-versioner är installerade. 5.0.0 är den högsta körningen som installerats. Ett felmeddelande visas.

Distribution av delversioner har en bieffekt som kan påverka slutanvändarna. Föreställ dig följande scenario:

Programmet anger att 5.0 krävs.
Vid körning är version 5.0.* inte installerad, men 5.1.0 är det. Version 5.1.0 används.
Senare installerar användaren 5.0.3 och kör programmet igen, 5.0.3 används nu.

Det är möjligt att 5.0.3 och 5.1.0 fungerar annorlunda, särskilt för scenarier som serialisering av binära data.

Kontrollera roll-forward-beteende

Innan du överskrider standardbeteendet för roll-forward kan du bekanta dig med nivån för .NET-körningskompatibilitet.

Roll-forward-beteendet för ett program kan konfigureras på fyra olika sätt:

Inställning på projektnivå genom att ange egenskapen <RollForward> :

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

Filen *.runtimeconfig.json .

Den här filen skapas när du kompilerar programmet. Om egenskapen <RollForward> har angetts i projektet återskapas den *.runtimeconfig.json i filen som rollForward inställning. Användare kan redigera den här filen för att ändra programmets beteende.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Kommandots dotnet--roll-forward <value> egenskap.

När du kör ett program kan du styra roll-forward-beteendet via kommandoraden:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Miljövariabeln DOTNET_ROLL_FORWARD .

Prioritet

Beteendet för vidarebefordran anges i följande ordning när appen körs, och högre numrerade objekt har företräde framför lägre numrerade objekt:

Först utvärderas *.runtimeconfig.json konfigurationsfilen.
DOTNET_ROLL_FORWARD Därefter beaktas miljövariabeln, vilket överskrider den föregående kontrollen.
Slutligen åsidosätter alla parametrar som --roll-forward skickas till det program som körs allt annat.

Värden

Men du ställer in inställningen för framåtrullning med något av följande värden för att ange beteendet:

Värde	beskrivning
`Minor`	Standard om det inte anges. Rulla vidare till den lägsta högre delversionen om den begärda delversionen saknas. Om den begärda delversionen finns `LatestPatch` används principen.
`Major`	Rulla vidare till nästa tillgängliga högre huvudversion och lägsta delversion om den begärda huvudversionen saknas. Om den begärda huvudversionen finns `Minor` används principen.
`LatestPatch`	Rulla vidare till den högsta korrigeringsversionen. Det här värdet inaktiverar delversionsdistribution.
`LatestMinor`	Rulla vidare till högsta delversion, även om den begärda delversionen finns.
`LatestMajor`	Rulla vidare till högsta högre och högsta delversion, även om den begärda huvudversionen finns.
`Disable`	Rulla inte vidare, bind bara till den angivna versionen. Den här principen rekommenderas inte för allmän användning eftersom den inaktiverar möjligheten att rulla vidare till de senaste korrigeringarna. Det här värdet rekommenderas endast för testning.

Fristående distributioner inkluderar den valda körningen

Du kan publicera ett program som en fristående distribution. Den här metoden paketerar .NET-körningen och biblioteken med ditt program. Fristående distributioner är inte beroende av körningsmiljöer. Val av körningsversion sker vid publiceringstid, inte körningstid.

Återställningshändelsen som inträffar när publiceringen väljer den senaste korrigeringsversionen av den angivna körningsfamiljen. Till exempel dotnet publish väljer du .NET 5.0.3 om det är den senaste korrigeringsversionen i .NET 5-körningsfamiljen. Målramverket (inklusive de senaste installerade säkerhetskorrigeringarna) paketeras med programmet.

Ett fel uppstår om den lägsta version som angetts för ett program inte uppfylls. dotnet publish binder till den senaste körningskorrigeringsversionen (inom en viss major.minor-version). dotnet publish stöder inte roll-forward-semantiken dotnet runför . Mer information om korrigeringar och fristående distributioner finns i artikeln om val av körningskorrigering i distribution av .NET-program.

Fristående distributioner kan kräva en specifik korrigeringsversion. Du kan åsidosätta den lägsta versionen av körningskorrigeringen (till högre eller lägre versioner) i projektfilen, som du ser i följande exempel:

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

Elementet RuntimeFrameworkVersion åsidosätter standardversionsprincipen. För fristående distributioner RuntimeFrameworkVersion anger den exakta körningsramverksversionen. För ramverksberoende program RuntimeFrameworkVersion anger den lägsta nödvändiga körningsramverksversionen.