Doelframeworks in SDK-projecten

Artikel
11/12/2024

Wanneer u een framework in een app of bibliotheek richt, geeft u de set API's op die u beschikbaar wilt maken voor de app of bibliotheek. U geeft het doelframework in uw projectbestand op met behulp van een target framework moniker (TFM).

Een app of bibliotheek kan zich richten op een versie van .NET Standard. .NET Standard-versies vertegenwoordigen gestandaardiseerde sets API's voor alle .NET-implementaties. Een bibliotheek kan zich bijvoorbeeld richten op .NET Standard 1.6 en toegang krijgen tot API's die werken in .NET Core en .NET Framework met behulp van dezelfde codebase.

Een app of bibliotheek kan ook gericht zijn op een specifieke .NET-implementatie om toegang te krijgen tot implementatiespecifieke API's. Een app die bijvoorbeeld is gericht op Xamarin.iOS (bijvoorbeeldXamarin.iOS10) heeft toegang tot door Xamarin geleverde iOS API-wrappers voor iOS 10 of een app die is gericht op Universeel Windows-platform (UWP, uap10.0) heeft toegang tot API's die worden gecompileerd voor apparaten met Windows 10.

Voor sommige doelframeworks, zoals .NET Framework, worden de API's gedefinieerd door de assembly's die het framework op een systeem installeert en kunnen toepassingsframework-API's (bijvoorbeeld ASP.NET) bevatten.

Voor op pakketten gebaseerde doelframeworks (bijvoorbeeld .NET 5+, .NET Core en .NET Standard) worden de API's gedefinieerd door de NuGet-pakketten die zijn opgenomen in de app of bibliotheek.

Nieuwste versies

In de volgende tabel worden de meest voorkomende doelframeworks gedefinieerd, hoe ernaar wordt verwezen en naar welke versie van .NET Standard ze worden geïmplementeerd. Deze doelframeworkversies zijn de nieuwste stabiele versies. Voorlopige versies worden niet weergegeven. Een doelframework moniker (TFM) is een gestandaardiseerde tokenindeling voor het opgeven van het doelframework van een .NET-app of -bibliotheek.

Doelframework	Laatst stabiele versie	Moniker van het doelframework (TFM)	Implemented .NET Standard-versie
.NET 9	9	net9.0	2.1
.NET 8	8	net8.0	2.1
.NET Standard	2.1	netstandard2.1	N.v.t.
.NET Core	3.1	netcoreapp3.1	2.1
.NET Framework	4.8.1	net481	2.0

Ondersteunde doelframeworks

Naar een doelframework wordt doorgaans verwezen door een TFM. In de volgende tabel ziet u de doelframeworks die worden ondersteund door de .NET SDK en de NuGet-client. Equivalenten worden tussen vierkante haken weergegeven. Is bijvoorbeeld win81 een equivalent van TFM aan netcore451.

Doelframework	TFM
.NET 5+ (en .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
Universeel Windows-platform	uap [uap10.0] uap10.0 [win10] [netcore50]

* TFM's voor .NET 5 en hoger bevatten enkele besturingssysteemspecifieke variaties. Zie de volgende sectie, .NET 5+ OS-specifieke TFM's voor meer informatie.

.NET 5+ BEsturingssysteemspecifieke TFM's

De net5.0, net6.0, , net7.0en net8.0net.0 TFM's bevatten technologieën die op verschillende platforms werken. Als u een besturingssysteemspecifieke TFM opgeeft, worden API's die specifiek zijn voor een besturingssysteem beschikbaar voor uw app, bijvoorbeeld Windows Forms of iOS-bindingen. Besturingssysteemspecifieke TFM's nemen ook elke API over die beschikbaar is voor hun basis TFM, bijvoorbeeld de net9.0 TFM.

.NET 5 heeft het net5.0-windows besturingssysteemspecifieke TFM geïntroduceerd, waaronder Windows-specifieke bindingen voor WinForms, WPF en UWP-API's. .NET 6 en nieuwere versies hebben extra besturingssysteemspecifieke TFM's, net6.0-iosbijvoorbeeld.

In de volgende tabel ziet u de compatibiliteit van de .NET 5+ TFM's.

TFM	Compatibel met
`net5.0`	net1.. 4 (met NU1701-waarschuwing) netcoreapp1.. 3.1 (waarschuwing wanneer naar WinForms of WPF wordt verwezen) netstandard1.. 2.1
`net5.0-windows`	netcoreapp1.. 3.1 (plus alle andere overgenomen van `net5.0`)
`net6.0`	(Volgende versie van `net5.0`)
`net6.0-android`	`xamarin.android` (plus alle overige overgenomen van `net6.0`)
`net6.0-ios`	Alles overgenomen van `net6.0`
`net6.0-maccatalyst`	Alles overgenomen van `net6.0`
`net6.0-macos`	Alles overgenomen van `net6.0`
`net6.0-tvos`	Alles overgenomen van `net6.0`
`net6.0-windows`	(Volgende versie van `net5.0-windows`)
`net7.0`	(Volgende versie van `net6.0`)
`net7.0-android`	(Volgende versie van `net6.0-android`)
`net7.0-ios`	(Volgende versie van `net6.0-ios`)
`net7.0-maccatalyst`	(Volgende versie van `net6.0-maccatalyst`)
`net7.0-macos`	(Volgende versie van `net6.0-macos`)
`net7.0-tizen`	`tizen40` (plus alle overige overgenomen van `net7.0`)
`net7.0-tvos`	(Volgende versie van `net6.0-tvos`)
`net7.0-windows`	(Volgende versie van `net6.0-windows`)
`net8.0`	(Volgende versie van `net7.0`)
`net8.0-android`	(Volgende versie van `net7.0-android`)
`net8.0-browser`	Alles overgenomen van `net8.0`
`net8.0-ios`	(Volgende versie van `net7.0-ios`)
`net8.0-maccatalyst`	(Volgende versie van `net7.0-maccatalyst`)
`net8.0-macos`	(Volgende versie van `net7.0-macos`)
`net8.0-tizen`	(Volgende versie van `net7.0-tizen`)
`net8.0-tvos`	(Volgende versie van `net7.0-tvos`)
`net8.0-windows`	(Volgende versie van `net7.0-windows`)
`net9.0`	(Volgende versie van `net8.0`)
`net9.0-android`	(Volgende versie van `net8.0-android`)
`net9.0-browser`	(Volgende versie van `net8.0-browser`)
`net9.0-ios`	(Volgende versie van `net8.0-ios`)
`net9.0-maccatalyst`	(Volgende versie van `net8.0-maccatalyst`)
`net9.0-macos`	(Volgende versie van `net8.0-macos`)
`net9.0-tizen`	(Volgende versie van `net8.0-tizen`)
`net9.0-tvos`	(Volgende versie van `net8.0-tvos`)
`net9.0-windows`	(Volgende versie van `net8.0-windows`)

Als u uw app overdraagbaar wilt maken op verschillende platforms, maar nog steeds toegang hebt tot besturingssysteemspecifieke API's, kunt u zich richten op meerdere BEsturingssysteemspecifieke TFM's en platformbeveiligingen toevoegen rond OS-specifieke API-aanroepen met behulp van #if preprocessorrichtlijnen. Zie Preprocessorsymbolen voor een lijst met de beschikbare symbolen.

Voorgestelde doelen

Gebruik deze richtlijnen om te bepalen welke TFM in uw app moet worden gebruikt:

Apps die overdraagbaar zijn naar meerdere platforms, moeten bijvoorbeeld net9.0gericht zijn op een basis TFM. Dit omvat de meeste bibliotheken, maar ook ASP.NET Core en Entity Framework.
Platformspecifieke bibliotheken moeten gericht zijn op platformspecifieke smaken. WinForms- en WPF-projecten moeten zich bijvoorbeeld richten op net9.0-windows.
Platformoverschrijdende toepassingsmodellen (Xamarin Forms, ASP.NET Core) en bridge packs (Xamarin Essentials) moeten ten minste gericht zijn op de basis TFM, net9.0maar kunnen ook gericht zijn op extra platformspecifieke smaken om meer API's of functies op te lichten.

Besturingssysteemversie in TFM's

U kunt ook een optionele versie van het besturingssysteem opgeven aan het einde van een besturingssysteemspecifieke TFM, bijvoorbeeld net6.0-ios15.0. De versie geeft aan welke API's beschikbaar zijn voor uw app of bibliotheek. Het besturingssysteem heeft geen controle over de versie van het besturingssysteem die tijdens runtime door uw app of bibliotheek wordt ondersteund. Het wordt gebruikt om de referentieassembly's te selecteren waarmee uw project wordt gecompileerd en om assets te selecteren uit NuGet-pakketten. U kunt deze versie beschouwen als de 'platformversie' of 'OS API-versie' om deze te onderscheiden van de runtimeversie van het besturingssysteem.

Wanneer een besturingssysteemspecifieke TFM niet expliciet de platformversie opgeeft, heeft deze een impliciete waarde die kan worden afgeleid van de basis-TFM- en platformnaam. De standaardplatformwaarde voor Android in .NET 6 is 31.0bijvoorbeeld, wat betekent dat dit net6.0-android afkorting is voor de canonieke net6.0-android31.0 TFM. De impliciete platformversie voor een nieuwere basis TFM kan hoger zijn, bijvoorbeeld een toekomstige net8.0-android TFM kan worden toegewezen aan net8.0-android34.0. Het verkorte formulier is alleen bedoeld voor gebruik in projectbestanden en wordt uitgebreid naar de canonieke vorm door de MSBuild-doelen van de .NET SDK voordat ze worden doorgegeven aan andere hulpprogramma's, zoals NuGet.

In de volgende tabel ziet u de standaardwaarden van het doelplatform (TPV) voor elke .NET-release.

.NET-versie	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

Notitie

Op Apple-platforms (iOS, macOS, tvOS en Mac Catalyst) in .NET 8 en eerder is de standaard-TPV de meest recente ondersteunde versie in de momenteel geïnstalleerde workload. Dit betekent dat het bijwerken van de iOS-workload in .NET 8 bijvoorbeeld kan leiden tot een hogere standaard-TPV als ondersteuning voor een nieuwe versie van iOS is toegevoegd in die workload. In de voorgaande tabel is de standaard-NHW de standaard-TPV in de eerste release voor de vermelde .NET-versie.

Vanaf .NET 9 is dit speciale gedrag alleen van toepassing op uitvoerbare projecten. De standaard-TPV voor bibliotheekprojecten blijft nu hetzelfde voor de gehele primaire .NET-release, net als alle andere platforms.

De .NET SDK is ontworpen om nieuw uitgebrachte API's te kunnen ondersteunen voor een afzonderlijk platform zonder een nieuwe versie van de basis TFM. Hierdoor hebt u toegang tot platformspecifieke functionaliteit zonder te wachten op een grote release van .NET. U kunt toegang krijgen tot deze nieuw uitgebrachte API's door de platformversie in tfm te verhogen. Als het Android-platform bijvoorbeeld API-niveau 32 API's heeft toegevoegd in een SDK-update van .NET 6.0.x, kunt u deze openen met behulp van de TFM net6.0-android32.0.

Prioriteit

Als uw app verwijst naar een pakket met meerdere assets voor verschillende TFM's, hebben de assets die dichter bij het versienummer staan de voorkeur. Als uw app-doelen net6.0-ios en het pakket bijvoorbeeld assets biedt voor net6.0 en net5.0-ios, worden de net6.0 assets gebruikt. Zie Prioriteiten voor meer informatie.

Oudere besturingssysteemversies ondersteunen

Hoewel een platformspecifieke app of bibliotheek wordt gecompileerd op API's van een specifieke versie van dat besturingssysteem, kunt u deze compatibel maken met eerdere versies van het besturingssysteem door de SupportedOSPlatformVersion eigenschap toe te voegen aan uw projectbestand. De SupportedOSPlatformVersion eigenschap geeft de minimale versie van het besturingssysteem aan die is vereist om uw app of bibliotheek uit te voeren. Als u deze minimale runtimebesturingssysteemversie niet expliciet opgeeft in het project, wordt deze standaard ingesteld op de platformversie van tfm.

Uw app kan alleen correct worden uitgevoerd op een oudere versie van het besturingssysteem, maar kan geen API's aanroepen die niet bestaan in die versie van het besturingssysteem. U kunt echter bewakers toevoegen rond aanroepen naar nieuwere API's, zodat ze alleen worden aangeroepen wanneer ze worden uitgevoerd op een versie van het besturingssysteem die deze ondersteunt. Met dit patroon kunt u uw app of bibliotheek ontwerpen om ondersteuning te bieden voor oudere versies van het besturingssysteem, terwijl u profiteert van nieuwere besturingssysteemfunctionaliteit bij het uitvoeren van nieuwere versies van het besturingssysteem.

De SupportedOSPlatformVersion waarde (expliciet of standaard) wordt gebruikt door de platformcompatibiliteitsanalyse, waarmee niet-beveiligde aanroepen naar nieuwere API's worden gedetecteerd en gewaarschuwd. Deze wordt in de gecompileerde assembly van het project verbrand als een UnsupportedOSPlatformAttribute assemblykenmerk, zodat de platformcompatibiliteitsanalyse niet-bewaakte aanroepen van de API's van die assembly kan detecteren uit projecten met een lagere SupportedOSPlatformVersion waarde. Op sommige platforms is de SupportedOSPlatformVersion waarde van invloed op platformspecifieke processen voor het verpakken en bouwen van apps, die worden behandeld in de documentatie voor deze platforms.

Hier volgt een voorbeeldfragment van een projectbestand dat gebruikmaakt van de TargetFramework eigenschappen en SupportedOSPlatformVersion MSBuild om op te geven dat de app of bibliotheek toegang heeft tot iOS 15.0-API's, maar ondersteuning biedt voor uitvoering op iOS 13.0 en hoger:

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

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

</Project>

Een doelframework opgeven

Doelframeworks worden opgegeven in een projectbestand. Wanneer er één doelframework is opgegeven, gebruikt u het TargetFramework-element. In het volgende console-app-projectbestand ziet u hoe u .NET 9 kunt targeten:

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

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

</Project>

Wanneer u meerdere doelframeworks opgeeft, kunt u voorwaardelijk verwijzen naar assembly's voor elk doelframework. In uw code kunt u voorwaardelijk compileren op basis van deze assembly's met behulp van preprocessorsymbolen met if-then-else-logica .

Het volgende bibliotheekproject is gericht op API's van .NET Standard (netstandard1.4) en .NET Framework (net40 en net45). Gebruik het meervouds TargetFrameworks-element met meerdere doelframeworks. De Condition kenmerken omvatten implementatiespecifieke pakketten wanneer de bibliotheek wordt gecompileerd voor de twee .NET Framework TFM's:

<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>

In uw bibliotheek of app schrijft u voorwaardelijke code met behulp van preprocessorrichtlijnen om te compileren voor elk doelframework:

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

Preprocessorsymbolen

Het buildsysteem is op de hoogte van preprocessorsymbolen die de doelframeworks vertegenwoordigen die worden weergegeven in de tabel Ondersteunde doelframeworkversies wanneer u SDK-projecten gebruikt. Als u een .NET Standard-, .NET Core- of .NET 5+ TFM wilt converteren naar een preprocessorsymbool, vervangt u puntjes en afbreekstreepjes door een onderstrepingsteken en wijzigt u kleine letters in hoofdletters (bijvoorbeeld het symbool hiervoornetstandard1.4).NETSTANDARD1_4

U kunt het genereren van deze symbolen uitschakelen via de DisableImplicitFrameworkDefines eigenschap. Zie DisableImplicitFrameworkDefines voor meer informatie over deze eigenschap.

De volledige lijst met preprocessorsymbolen voor .NET-doelframeworks is:

Doelframeworks	Symbolen	Aanvullende symbolen (beschikbaar in .NET 5+ SDK's)	Platformsymbolen (alleen beschikbaar) wanneer u een besturingssysteemspecifieke TFM opgeeft)
.NET Framework	`NETFRAMEWORK`, , `NET481`, , `NET472`, `NET471`, , `NET47`, `NET462`, `NET452NET46NET451NET40NET35NET461NET45`, `NET48NET20`	`NET48_OR_GREATER`, , `NET472_OR_GREATER`, , , , `NET461_OR_GREATER`, `NET46_OR_GREATER`, `NET452_OR_GREATER`, `NET45_OR_GREATERNET40_OR_GREATERNET35_OR_GREATERNET451_OR_GREATERNET462_OR_GREATERNET47_OR_GREATERNET471_OR_GREATERNET20_OR_GREATER`
.NET Standard	`NETSTANDARD`, , `NETSTANDARD2_0`, `NETSTANDARD1_6NETSTANDARD2_1`, , `NETSTANDARD1_5`, `NETSTANDARD1_4`, , `NETSTANDARD1_1NETSTANDARD1_2NETSTANDARD1_3NETSTANDARD1_0`	`NETSTANDARD2_1_OR_GREATER`, , `NETSTANDARD1_6_OR_GREATERNETSTANDARD2_0_OR_GREATER`, `NETSTANDARD1_5_OR_GREATER`, , `NETSTANDARD1_4_OR_GREATER`, `NETSTANDARD1_3_OR_GREATER`, `NETSTANDARD1_1_OR_GREATERNETSTANDARD1_2_OR_GREATERNETSTANDARD1_0_OR_GREATER`
.NET 5+ (en .NET Core)	`NET`, , `NET8_0NET9_0`, `NET7_0`, , `NET6_0`, , `NET5_0NETCOREAPP`, `NETCOREAPP3_1`, `NETCOREAPP2_2NETCOREAPP3_0NETCOREAPP2_1NETCOREAPP2_0NETCOREAPP1_1`,`NETCOREAPP1_0`	`NET8_0_OR_GREATER`, , `NET7_0_OR_GREATERNET6_0_OR_GREATER`, `NET5_0_OR_GREATER`, `NETCOREAPP3_1_OR_GREATER`, , `NETCOREAPP3_0_OR_GREATER`, , `NETCOREAPP2_0_OR_GREATERNETCOREAPP2_1_OR_GREATERNETCOREAPP1_1_OR_GREATERNETCOREAPP2_2_OR_GREATERNETCOREAPP1_0_OR_GREATER`	`ANDROID`, , `BROWSERIOS`, `MACCATALYST`, , `MACOS`, , `TVOSWINDOWS` `[OS][version]` (bijvoorbeeld `IOS15_1`), `[OS][version]_OR_GREATER` (bijvoorbeeld `IOS15_1_OR_GREATER`)