Målramverk i SDK-liknande projekt

Artikel
11/12/2024

När du riktar in dig på ett ramverk i en app eller ett bibliotek anger du den uppsättning API:er som du vill göra tillgängliga för appen eller biblioteket. Du anger målramverket i projektfilen med hjälp av en målramverksmoniker (TFM).

En app eller ett bibliotek kan rikta in sig på en version av .NET Standard. .NET Standard-versioner representerar standardiserade uppsättningar API:er för alla .NET-implementeringar. Ett bibliotek kan till exempel rikta in sig på .NET Standard 1.6 och få åtkomst till API:er som fungerar i .NET Core och .NET Framework med samma kodbas.

En app eller ett bibliotek kan också rikta in sig på en specifik .NET-implementering för att få åtkomst till implementeringsspecifika API:er. Till exempel har en app som riktar sig till Xamarin.iOS (till exempel Xamarin.iOS10) åtkomst till Xamarin-tillhandahållna iOS API-omslutningar för iOS 10, eller en app som riktar sig till Universell Windows-plattform (UWP, uap10.0) har åtkomst till API:er som kompileras för enheter som kör Windows 10.

För vissa målramverk, till exempel .NET Framework, definieras API:erna av de sammansättningar som ramverket installerar i ett system och kan innehålla API:er för programramverk (till exempel ASP.NET).

För paketbaserade målramverk (till exempel .NET 5+, .NET Core och .NET Standard) definieras API:erna av De NuGet-paket som ingår i appen eller biblioteket.

De senaste versionerna

I följande tabell definieras de vanligaste målramverken, hur de refereras och vilken version av .NET Standard de implementerar. Dessa målramverksversioner är de senaste stabila versionerna. Förhandsversioner visas inte. Ett målramverksmoniker (TFM) är ett standardiserat tokenformat för att ange målramverket för en .NET-app eller ett bibliotek.

Målramverk	Senaste stabil version	Målramverksmoniker (TFM)	Implementerad .NET Standard-version
.NET 9	9	net9.0	2.1
.NET 8	8	net8.0	2.1
.NET Standard	2.1	netstandard2.1	Ej tillämpligt
.NET Core	3.1	netcoreapp3.1	2.1
.NET Framework	4.8.1	net481	2.0

Målramverk som stöds

Ett målramverk refereras vanligtvis av en TFM. I följande tabell visas de målramverk som stöds av .NET SDK och NuGet-klienten. Motsvarigheter visas inom hakparenteser. Till exempel win81 är en motsvarande TFM till netcore451.

Målramverk	TFM
.NET 5+ (och .NET Core)	netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0* net8.0*
.NET Standard	netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1
.NET Framework	net11 net20 net35 net40 net403 net45 net451 net452 net46 net461 net462 net47 net471 net472 net48 net481
Windows Store	netcore [netcore45] netcore45 [win] [win8] netcore451 [win81]
.NET Micro Framework	netmf
Silverlight	sl4 sl5
Windows Phone	wp [wp7] wp7 wp75 wp8 wp81 wpa81
Universell Windows-plattform	uap [uap10.0] uap10.0 [win10] [netcore50]

* .NET 5 och senare TFM:er innehåller vissa operativsystemspecifika varianter. Mer information finns i följande avsnitt, .NET 5+ OS-specifika TFM:er.

.NET 5+ OS-specifika TFM:er

De net5.0, net6.0, net7.0, net8.0och net.0 TFM:er innehåller tekniker som fungerar på olika plattformar. Om du anger en OS-specifik TFM blir API:er som är specifika för ett operativsystem tillgängliga för din app, till exempel Windows Forms- eller iOS-bindningar. OS-specifika TFM:er ärver också varje API som är tillgängligt för deras bas-TFM, net9.0 till exempel TFM.

.NET 5 introducerade den net5.0-windows OS-specifika TFM som innehåller Windows-specifika bindningar för WinForms, WPF och UWP-API:er. .NET 6- och senare versioner har ytterligare OS-specifika TFM:er, till exempel net6.0-ios.

I följande tabell visas kompatibiliteten för .NET 5+ TFM:er.

TFM	Kompatibel med
`net5.0`	net1.. 4 (med NU1701-varning) netcoreapp1.. 3.1 (varning när WinForms eller WPF refereras) netstandard1.. 2.1
`net5.0-windows`	netcoreapp1.. 3.1 (plus allt annat ärvt från `net5.0`)
`net6.0`	(Efterföljande version av `net5.0`)
`net6.0-android`	`xamarin.android` (plus allt annat ärvt från `net6.0`)
`net6.0-ios`	Allt ärvt från `net6.0`
`net6.0-maccatalyst`	Allt ärvt från `net6.0`
`net6.0-macos`	Allt ärvt från `net6.0`
`net6.0-tvos`	Allt ärvt från `net6.0`
`net6.0-windows`	(Efterföljande version av `net5.0-windows`)
`net7.0`	(Efterföljande version av `net6.0`)
`net7.0-android`	(Efterföljande version av `net6.0-android`)
`net7.0-ios`	(Efterföljande version av `net6.0-ios`)
`net7.0-maccatalyst`	(Efterföljande version av `net6.0-maccatalyst`)
`net7.0-macos`	(Efterföljande version av `net6.0-macos`)
`net7.0-tizen`	`tizen40` (plus allt annat ärvt från `net7.0`)
`net7.0-tvos`	(Efterföljande version av `net6.0-tvos`)
`net7.0-windows`	(Efterföljande version av `net6.0-windows`)
`net8.0`	(Efterföljande version av `net7.0`)
`net8.0-android`	(Efterföljande version av `net7.0-android`)
`net8.0-browser`	Allt ärvt från `net8.0`
`net8.0-ios`	(Efterföljande version av `net7.0-ios`)
`net8.0-maccatalyst`	(Efterföljande version av `net7.0-maccatalyst`)
`net8.0-macos`	(Efterföljande version av `net7.0-macos`)
`net8.0-tizen`	(Efterföljande version av `net7.0-tizen`)
`net8.0-tvos`	(Efterföljande version av `net7.0-tvos`)
`net8.0-windows`	(Efterföljande version av `net7.0-windows`)
`net9.0`	(Efterföljande version av `net8.0`)
`net9.0-android`	(Efterföljande version av `net8.0-android`)
`net9.0-browser`	(Efterföljande version av `net8.0-browser`)
`net9.0-ios`	(Efterföljande version av `net8.0-ios`)
`net9.0-maccatalyst`	(Efterföljande version av `net8.0-maccatalyst`)
`net9.0-macos`	(Efterföljande version av `net8.0-macos`)
`net9.0-tizen`	(Efterföljande version av `net8.0-tizen`)
`net9.0-tvos`	(Efterföljande version av `net8.0-tvos`)
`net9.0-windows`	(Efterföljande version av `net8.0-windows`)

Om du vill göra din app portabel på olika plattformar men fortfarande har åtkomst till OS-specifika API:er kan du rikta in dig på flera OS-specifika TFM:er och lägga till plattformsskydd runt OS-specifika API-anrop med hjälp av #if förprocessordirektiv. En lista över tillgängliga symboler finns i Preprocessor-symboler.

Föreslagna mål

Använd dessa riktlinjer för att avgöra vilken TFM som ska användas i din app:

Appar som är portabla till flera plattformar bör rikta in sig på en bas-TFM, net9.0till exempel . Detta omfattar de flesta bibliotek men även ASP.NET Core och Entity Framework.
Plattformsspecifika bibliotek bör rikta in sig på plattformsspecifika smaker. Till exempel bör WinForms- och WPF-projekt rikta in sig på net9.0-windows.
Plattformsoberoende programmodeller (Xamarin Forms, ASP.NET Core) och bridge-paket (Xamarin Essentials) bör åtminstone riktas mot bas-TFM, net9.0till exempel , men kan också rikta in sig på ytterligare plattformsspecifika smaker för att lysa upp fler API:er eller funktioner.

OS-version i TFM:er

Du kan också ange en valfri os-version i slutet av en OS-specifik TFM, till exempel net6.0-ios15.0. Versionen anger vilka API:er som är tillgängliga för din app eller ditt bibliotek. Den styr inte den operativsystemversion som din app eller ditt bibliotek stöder vid körning. Den används för att välja de referenssammansättningar som ditt projekt kompilerar mot och för att välja tillgångar från NuGet-paket. Tänk på den här versionen som "plattformsversion" eller "OS API-version" för att skilja den från körningsoperativsystemets version.

När en OS-specifik TFM inte uttryckligen anger plattformsversionen har den ett underförstått värde som kan härledas från bas-TFM och plattformsnamnet. Standardplattformsvärdet för Android i .NET 6 är 31.0till exempel , vilket innebär att det net6.0-android är en förkortning för den kanoniska net6.0-android31.0 TFM:en. Den underförstådda plattformsversionen för en nyare bas-TFM kan vara högre, till exempel kan en framtida net8.0-android TFM mappas till net8.0-android34.0. Det kortfattade formuläret är endast avsett att användas i projektfiler och utökas till kanoniskt format av .NET SDK:s MSBuild-mål innan det skickas till andra verktyg, till exempel NuGet.

I följande tabell visas standardvärdena för målplattform (TPV) för varje .NET-version.

.NET-version	Android	iOS	Mac Catalyst	macOS	tvOS	Tizen	Windows
.NET 8	34,0	17,2	17,2	14,2	17.1	7.0	10,0
.NET 9	35.0	18,0	18,0	15.0		7.0	10,0

Kommentar

På Apple-plattformar (iOS, macOS, tvOS och Mac Catalyst) i .NET 8 och tidigare är standard-TPV den senaste versionen som stöds i den för närvarande installerade arbetsbelastningen. Det innebär att uppdatering av iOS-arbetsbelastningen i .NET 8 till exempel kan resultera i en högre standard-TPV om stöd för en ny version av iOS har lagts till i den arbetsbelastningen. I föregående tabell är standard-TPV den i den första versionen för den angivna .NET-versionen.

Från och med .NET 9 gäller det här speciella beteendet endast för körbara projekt. Standard-TPV för biblioteksprojekt förblir nu samma för hela en större .NET-version, som alla andra plattformar.

.NET SDK är utformat för att kunna stödja nyligen släppta API:er för en enskild plattform utan en ny version av bas-TFM. På så sätt kan du komma åt plattformsspecifika funktioner utan att vänta på en större version av .NET. Du kan få åtkomst till dessa nyligen släppta API:er genom att öka plattformsversionen i TFM. Om Android-plattformen till exempel har lagt till API-nivå 32-API:er i en .NET 6.0.x SDK-uppdatering kan du komma åt dem med hjälp av TFM net6.0-android32.0.

Prioritet

Om din app refererar till ett paket som har flera tillgångar för olika TFM:er föredras de tillgångar som ligger närmare versionsnumret. Om din app till exempel riktar in sig net6.0-ios på och paketet erbjuder tillgångar för net6.0 och net5.0-iosanvänds net6.0 tillgångarna. Mer information finns i Prioriteter.

Stöd för äldre os-versioner

Även om en plattformsspecifik app eller ett bibliotek kompileras mot API:er från en viss version av operativsystemet kan du göra den kompatibel med tidigare OS-versioner genom att lägga till egenskapen i SupportedOSPlatformVersion projektfilen. Egenskapen SupportedOSPlatformVersion anger den lägsta operativsystemversion som krävs för att köra din app eller ditt bibliotek. Om du inte uttryckligen anger den här lägsta körningsversionen av operativsystemet i projektet, är den standardversion av plattformen från TFM.

För att appen ska kunna köras korrekt på en äldre operativsystemversion kan den inte anropa API:er som inte finns på den versionen av operativsystemet. Du kan dock lägga till vakter runt anrop till nyare API:er så att de bara anropas när de körs på en version av operativsystemet som stöder dem. Med det här mönstret kan du utforma din app eller ditt bibliotek så att det stöder körning på äldre os-versioner samtidigt som du drar nytta av nyare os-funktioner när du kör på nyare os-versioner.

Värdet SupportedOSPlatformVersion (oavsett om det är explicit eller standard) används av analysverktyget för plattformskompatibilitet, som identifierar och varnar för obevakade anrop till nyare API:er. Den bränns in i projektets kompilerade sammansättning som ett UnsupportedOSPlatformAttribute sammansättningsattribut, så att analysverktyget för plattformskompatibilitet kan identifiera obevakade anrop till sammansättningens API:er från projekt med ett lägre SupportedOSPlatformVersion värde. På vissa plattformar SupportedOSPlatformVersion påverkar värdet plattformsspecifika apppaketerings- och byggprocesser, som beskrivs i dokumentationen för dessa plattformar.

Här är ett exempelutdrag av en projektfil som använder TargetFramework egenskaperna och SupportedOSPlatformVersion MSBuild för att ange att appen eller biblioteket har åtkomst till iOS 15.0-API:er men stöder körning på iOS 13.0 och senare:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0-ios15.0</TargetFramework>
    <SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
  </PropertyGroup>
  ...

</Project>

Så här anger du ett målramverk

Målramverk anges i en projektfil. När ett enda målramverk har angetts använder du targetframework-elementet. Följande konsolappprojektfil visar hur du riktar in dig på .NET 9:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

</Project>

När du anger flera målramverk kan du villkorligt referera till sammansättningar för varje målramverk. I koden kan du villkorligt kompilera mot dessa sammansättningar med hjälp av preprocessorsymboler med if-then-else-logik .

Följande biblioteksprojekt riktar sig till API:er för .NET Standard (netstandard1.4) och .NET Framework (net40 och net45). Använd elementet TargetFrameworks i plural med flera målramverk. Attributen Condition innehåller implementeringsspecifika paket när biblioteket kompileras för de två .NET Framework TFM:erna:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>
  </PropertyGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.0 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net40' ">
    <Reference Include="System.Net" />
  </ItemGroup>

  <!-- Conditionally obtain references for the .NET Framework 4.5 target -->
  <ItemGroup Condition=" '$(TargetFramework)' == 'net45' ">
    <Reference Include="System.Net.Http" />
    <Reference Include="System.Threading.Tasks" />
  </ItemGroup>

</Project>

I ditt bibliotek eller din app skriver du villkorsstyrd kod med hjälp av förprocessordirektiv för att kompilera för varje målramverk:

public class MyClass
{
    static void Main()
    {
#if NET40
        Console.WriteLine("Target framework: .NET Framework 4.0");
#elif NET45
        Console.WriteLine("Target framework: .NET Framework 4.5");
#else
        Console.WriteLine("Target framework: .NET Standard 1.4");
#endif
    }
}

Symboler för förprocessor

Byggsystemet är medvetet om preprocessorsymboler som representerar målramverken som visas i tabellen Målramverksversioner som stöds när du använder SDK-liknande projekt. Om du vill konvertera en .NET Standard, .NET Core eller .NET 5+ TFM till en preprocessorsymbol ersätter du punkter och bindestreck med ett understreck och ändrar gemener till versaler (till exempel är NETSTANDARD1_4symbolen för netstandard1.4 ).

Du kan inaktivera generering av dessa symboler via egenskapen DisableImplicitFrameworkDefines . Mer information om den här egenskapen finns i DisableImplicitFrameworkDefines.

Den fullständiga listan över preprocessorsymboler för .NET-målramverk är:

Målramverk	Symboler	Ytterligare symboler (finns i .NET 5+ SDK:er)	Plattformssymboler (endast tillgängliga när du anger en OS-specifik TFM)
.NET Framework	`NETFRAMEWORK`, `NET481`, `NET48`, `NET472`, `NET471`, `NET47`, `NET462`, `NET461`, `NET46`, , `NET452`, `NET451`, `NET45`, `NET40`, , `NET35NET20`	`NET48_OR_GREATER`, `NET472_OR_GREATER`, `NET471_OR_GREATER`, `NET47_OR_GREATER`, `NET462_OR_GREATER`, `NET461_OR_GREATER`, `NET46_OR_GREATER`, `NET452_OR_GREATER`, , `NET451_OR_GREATER`, `NET45_OR_GREATER`, `NET40_OR_GREATER`, , , `NET35_OR_GREATERNET20_OR_GREATER`
.NET Standard	`NETSTANDARD`, `NETSTANDARD2_1`, `NETSTANDARD2_0`, `NETSTANDARD1_6`, `NETSTANDARD1_5`, `NETSTANDARD1_4`, , `NETSTANDARD1_3`, `NETSTANDARD1_2`, , `NETSTANDARD1_1NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`, `NETSTANDARD2_0_OR_GREATER`, `NETSTANDARD1_6_OR_GREATER`, `NETSTANDARD1_5_OR_GREATER`, `NETSTANDARD1_4_OR_GREATER`, `NETSTANDARD1_3_OR_GREATER`, , `NETSTANDARD1_2_OR_GREATER`, , `NETSTANDARD1_1_OR_GREATERNETSTANDARD1_0_OR_GREATER`
.NET 5+ (och .NET Core)	`NET`, `NET9_0`, `NET8_0`, `NET7_0`, `NET6_0`, `NET5_0`, `NETCOREAPP`, `NETCOREAPP3_1`, , `NETCOREAPP3_0`, `NETCOREAPP2_2`, `NETCOREAPP2_1`, `NETCOREAPP2_0`, , `NETCOREAPP1_1NETCOREAPP1_0`	`NET8_0_OR_GREATER`, `NET7_0_OR_GREATER`, `NET6_0_OR_GREATER`, `NET5_0_OR_GREATER`, `NETCOREAPP3_1_OR_GREATER`, `NETCOREAPP3_0_OR_GREATER`, , `NETCOREAPP2_2_OR_GREATER`, `NETCOREAPP2_1_OR_GREATER`, `NETCOREAPP2_0_OR_GREATER`, , , `NETCOREAPP1_1_OR_GREATERNETCOREAPP1_0_OR_GREATER`	`ANDROID`, `BROWSER`, `IOS`, `MACCATALYST`, `MACOS`, , `TVOS`, , `WINDOWS` `[OS][version]` (till exempel `IOS15_1`), `[OS][version]_OR_GREATER` (till exempel `IOS15_1_OR_GREATER`)