Zielframeworks in Projekten im SDK-Format

Wenn Sie ein Framework in einer App oder Bibliothek als Ziel verwenden, geben Sie mehrere APIs an, die Sie für die App oder Bibliothek verfügbar machen möchten. Sie geben das Zielframework in Ihrer Projektdatei mithilfe eines Zielframeworkmonikers (TFM) an.

Eine App oder Bibliothek kann auf eine Version von .NET Standard abzielen. .NET Standardversionen stellen standardisierte APIs für alle .NET Implementierungen dar. Beispielsweise kann eine Bibliothek auf .NET Standard 1.6 abzielen und Zugriff auf APIs erhalten, die über .NET Core und .NET Framework mit derselben Codebasis funktionieren.

Eine App oder Bibliothek kann auch auf eine bestimmte .NET Implementierung abzielen, um Zugriff auf implementierungsspezifische APIs zu erhalten. Beispielsweise hat eine App, die auf Universal Windows Platform (UWP, uap10.0) ausgerichtet ist, Zugriff auf APIs, die für Geräte kompiliert werden, die Windows 10 ausführen.

Bei einigen Zielframeworks, z. B. .NET Framework, werden die APIs durch die Assemblys definiert, die das Framework auf einem System installiert und kann Anwendungsframework-APIs (z. B. ASP.NET) enthalten.

Für paketbasierte Zielframeworks (z. B. .NET 5+, .NET Core und .NET Standard) werden die APIs durch die NuGet-Pakete definiert, die in der App oder Bibliothek enthalten sind.

Neueste Versionen

In der folgenden Tabelle werden die am häufigsten verwendeten Zielframeworks definiert, wie auf sie verwiesen wird und welche Version von .NET Standard implementiert wird. Diese Zielframeworkversionen sind die neuesten stabilen Versionen. Vorabversionen werden nicht angezeigt. Ein target Framework moniker (TFM) ist ein standardisiertes Tokenformat zum Angeben des Zielframeworks einer .NET App oder Bibliothek.

Unterstützte Zielframeworks

Auf ein Zielframework wird normalerweise mit einem TFM verwiesen. In der folgenden Tabelle sind die Zielframeworks aufgeführt, die vom .NET SDK und dem NuGet-Client unterstützt werden. Äquivalente werden in Klammern angegeben. win81 ist z.B ein äquivalenter TFM von netcore451.

* Die TFMs in .NET 5 und höher enthalten einige betriebssystemspezifische Varianten. Weitere Informationen finden Sie im folgenden Abschnitt, betriebssystemspezifische TFMs.

Betriebssystemspezifische TFMs

Zu den net8.0, net9.0 und net10.0 TFMs gehören Technologien, die plattformübergreifend funktionieren. Wenn Sie eine betriebssystemspezifische TFM angeben, werden APIs bereitgestellt, die speziell für ein Betriebssystem verfügbar sind, z. B. Windows Forms oder iOS-Bindungen. Betriebssystemspezifische TFMs erben auch jede API, die für ihren Basis-TFM verfügbar ist, z. B. den net10.0-TFM.

Die folgende Tabelle zeigt die Kompatibilität der .NET 8+ TFMs.

Damit Ihre App auf verschiedenen Plattformen genutzt werden kann und trotzdem Zugriff auf betriebsspezifische APIs möglich ist, können Sie mehrere betriebssystemspezifische TFMs als Ziel verwenden. Fügen Sie Plattformwächter für betriebsspezifische API-Aufrufe hinzu, indem Sie #if-Präprozessoranweisungen nutzen. Eine Liste der verfügbaren Symbole finden Sie unter Präprozessorsymbole.

Vorgeschlagene Ziele

Verwenden Sie diese Richtlinien, um zu bestimmen, welchen TFM Sie für Ihre App verwenden:

• Apps, die für mehrere Plattformen genutzt werden können, sollten einen Basis-TFM (z. B. net10.0) als Ziel verwenden. Dazu gehören die meisten Bibliotheken, aber auch ASP.NET Core und Entity Framework.
• Plattformspezifische Bibliotheken sollten plattformspezifische Varianten als Ziel verwenden. Beispielsweise sollten WinForms und WPF Projekte auf net10.0-windows abzielen.
• Plattformübergreifende Anwendungsmodelle (z. B. ASP.NET Core) sollten zumindest auf die Basis-TFM abzielen, z. B. net10.0, aber möglicherweise auch zusätzliche plattformspezifische Varianten anvisieren, um weitere APIs oder Features nutzen zu können.

Betriebssystemversion in TFMs

Sie können am Ende eines betriebssystemspezifischen TFM auch eine optionale Betriebssystemversion angeben, z. B. net8.0-ios17.2. Die Version gibt an, welche APIs für Ihre App oder Bibliothek verfügbar sind. Sie steuert nicht die Betriebssystemversion, die Ihre App oder Bibliothek zur Laufzeit unterstützt. Sie wird verwendet, um die Verweisassemblys auszuwählen, mit denen Ihr Projekt kompiliert wird, und um Ressourcen aus NuGet-Paketen auszuwählen. Stellen Sie sich diese Version als "Plattformversion" oder "Betriebssystem-API-Version" vor, um sie von der Laufzeitbetriebssystemversion zu unterscheiden.

Das .NET SDK ist so konzipiert, dass neu veröffentlichte APIs für eine einzelne Plattform ohne eine neue Version der Basis-TFM unterstützt werden können. Auf diese Weise können Sie auf plattformspezifische Funktionen zugreifen, ohne auf eine hauptversion von .NET zu warten. Sie können auf diese neu veröffentlichten APIs zugreifen, indem Sie die Plattformversion im TFM erhöhen. Zum Beispiel, wenn die Android-Plattform APIs der API-Ebene 34 in ein .NET 8.0.x SDK-Update aufgenommen hat, können Sie mithilfe des TFM net8.0-android34.0 darauf zugreifen.

Wenn ein betriebssystemspezifischer TFM die Plattformversion nicht explizit angibt, verfügt er über einen impliziten Wert, der aus dem Basis-TFM und dem Plattformnamen abgeleitet werden kann. Beispielsweise ist die Standardplattformversion für Android in .NET 9 35.0, was bedeutet, dass net9.0-android für die kanonische net9.0-android35.0 TFM kurz ist. Das Kurzhandformular ist nur für die Verwendung in Projektdateien vorgesehen und wird auf die kanonische Form durch die MSBuild-Ziele des .NET SDK erweitert, bevor sie an andere Tools wie NuGet übergeben werden.

Die folgende Tabelle zeigt die default Zielplattformversion (TPV) für Android und iOS für jede .NET-Version. Wenn Sie die neuesten Bindungen verwenden möchten, verwenden Sie die Standardeinstellung (d. h. geben Sie keine Betriebssystemversion an).

Ab .NET 9, wenn Dienstversionen die Unterstützung für eine spätere TPV einführen (die immer die gleiche major Versionsnummer hat wie bei der ursprünglichen Veröffentlichung der .NET-Version), bleibt der früheste unterstützte TPV für diese .NET-Version weiterhin unterstützt. Zum Beispiel wird für .NET 9 die früheste unterstützte iOS-Version, 18.0, weiterhin unterstützt, selbst wenn ein Service-Release die Unterstützung für die neueste iOS 18.x-Version hinzufügt. Wenn Sie die frühesten Bindungen für eine .NET-Version verwenden müssen, verwenden Sie eine bestimmte Betriebssystemversionsnummer in Ihrer TFM.

Rangfolge

Wenn Ihre App auf ein Paket verweist, das mehrere Ressourcen für unterschiedliche TFMs enthält, werden die Ressourcen bevorzugt, deren Versionsnummern näher beieinander liegen. Wenn Ihre App beispielsweise net9.0-ios als Ziel hat und das Paket Ressourcen für net9.0 und net8.0-ios bietet, werden die net9.0-Ressourcen verwendet. Weitere Informationen finden Sie unter Rangfolgen.

Unterstützung älterer Betriebssystemversionen

Eine plattformspezifische App oder Bibliothek für APIs wird zwar aus einer bestimmten Version dieses Betriebssystems kompiliert, aber Sie können sie mit früheren Betriebssystemversionen kompatibel machen, indem Sie Ihrer Projektdatei die Eigenschaft SupportedOSPlatformVersion hinzufügen. Die Eigenschaft SupportedOSPlatformVersion gibt die Betriebssystemversion an, die zum Ausführen Ihrer App oder Bibliothek mindestens erforderlich ist. Wenn Sie diese Mindestlaufzeit-Betriebssystemversion im Projekt nicht explizit angeben, wird standardmäßig die Plattformversion aus dem TFM verwendet.

Damit Ihre App unter einer älteren Betriebssystemversion ordnungsgemäß ausgeführt werden kann, kann sie keine APIs aufrufen, die in dieser Version des Betriebssystems nicht vorhanden sind. Sie können jedoch Wächter für Aufrufe neuerer APIs hinzufügen, sodass die APIs nur aufgerufen werden, wenn sie in einer Version des Betriebssystems ausgeführt werden, die sie unterstützt. Mit diesem Muster können Sie Ihre App oder Bibliothek so entwerfen, dass sie die Ausführung unter älteren Betriebssystemversionen unterstützt und gleichzeitig neuere Betriebssystemfunktionen nutzt, wenn sie unter neueren Betriebssystemversionen ausgeführt wird.

Der SupportedOSPlatformVersion-Wert (egal ob explizit angegeben oder standardmäßig verwendet) wird vom Analysetool für die Plattformkompatibilität verwendet, das unbeaufsichtigte Aufrufe neuerer APIs erkennt und entsprechende Warnungen ausgibt. Sie wird als UnsupportedOSPlatformAttribute-Assemblyattribut in die kompilierte Assembly des Projekts eingebaut, sodass das Analysetool für die Plattformkompatibilität unbeaufsichtigte Aufrufe der APIs dieser Assembly aus Projekten mit einem niedrigeren SupportedOSPlatformVersion-Wert erkennen kann. Auf einigen Plattformen wirkt sich der SupportedOSPlatformVersion-Wert auf plattformspezifische Prozesse für die App-Paketerstellung und -Kompilierung aus, die in der Dokumentation für diese Plattformen behandelt werden.

Das folgende Beispiel ist ein Auszug aus einer Projektdatei, die die TargetFramework MsBuild-Eigenschaften SupportedOSPlatformVersion verwendet, um anzugeben, dass die App oder Bibliothek Zugriff auf iOS 15.0-APIs hat, aber die Ausführung unter iOS 13.0 und höher unterstützt:

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

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

</Project>

So geben Sie ein Zielframework an

Zielframeworks werden in einer Projektdatei angegeben. Wenn ein einzelnes Zielframework angegeben wird, verwenden Sie das Element „TargetFramework“. Die folgende Projektdatei für eine Konsolenanwendung zeigt, wie man auf .NET 10 abzielt.

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

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

</Project>

Wenn Sie mehrere Zielframeworks angeben, können Sie für jedes Zielframework bedingt auf Assemblys verweisen. Sie können in Ihrem Code bedingt mit diesen Assemblys kompilieren, indem Sie die Präprozessorsymbole mit wenn-dann-sonst-Logik (if-then-else) verwenden.

Das folgende Bibliotheksprojekt zielt auf APIs von .NET Standard (netstandard1.4) und .NET Framework (net40 und net45) ab. Verwenden Sie das Element „TargetFrameworks“ im Plural für mehrere Zielframeworks. Die attribute Condition enthalten implementierungsspezifische Pakete, wenn die Bibliothek für die beiden .NET Framework-TFMs kompiliert wird:

<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 Ihrer Bibliothek oder App schreiben Sie mithilfe von Präprozessoranweisungen Bedingungscode, um für die verschiedenen Zielframeworks zu kompilieren:

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

TargetFramework-Werte sind Aliase

Die TargetFramework Eigenschaftswert (zum Beispiel, net10.0) ist ein benutzerfreundlicher Name – ein Alias –, den das .NET SDK in kanonische Moniker-Eigenschaften übersetzt. Insbesondere legt das SDK die folgenden Eigenschaften aus dem TargetFramework Wert fest:

• TargetFrameworkMoniker (z. B. .NETCoreApp,Version=v10.0)
• TargetFrameworkIdentifier (z. B. .NETCoreApp)
• TargetFrameworkVersion (z. B. v10.0)
• TargetPlatformMoniker, TargetPlatformIdentifierund TargetPlatformVersion (bei der Ausrichtung auf eine bestimmte Plattform)

NuGet und das .NET SDK verwenden diese Moniker-Eigenschaften – nicht die TargetFramework Zeichenfolge – für Paketkompatibilitätsprüfungen und Buildlogik. Diese Übersetzung erfolgt bereits für betriebssystemspezifische TFMs. Beispielsweise übersetzt net10.0-windows in TargetFrameworkMoniker = .NETCoreApp,Version=v10.0 und TargetPlatformMoniker = Windows,Version=7.0.

Da der Alias nur ein Name ist, kann der TargetFramework Wert eine beliebige alphanumerische Zeichenfolge sein, solange die entsprechenden Monikereigenschaften richtig festgelegt sind. Die folgende Projektdatei verwendet einen benutzerdefinierten Alias namens banana und legt die Moniker-Eigenschaften explizit fest, sodass das Projekt für .NET 10.0 erstellt und wiederhergestellt wird:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>banana</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition=" '$(TargetFramework)' == 'banana' ">
    <TargetFrameworkIdentifier>.NETCoreApp</TargetFrameworkIdentifier>
    <TargetFrameworkVersion>v10.0</TargetFrameworkVersion>
    <TargetFrameworkMoniker>.NETCoreApp,Version=v10.0</TargetFrameworkMoniker>
  </PropertyGroup>
</Project>

Weitere Informationen zu diesen Eigenschaften finden Sie in der Referenz zur TargetFramework MSBuild-Eigenschaft.

Präprozessorsymbole

Das Buildsystem beachtet Präprozessorsymbole, die Zielframeworks darstellen, die in der Tabelle Unterstützte Zielframeworkversionen aufgelistet sind, wenn Sie Projekte im SDK-Format verwenden. Um einen .NET Standard, .NET Core oder .NET 5+ TFM in ein Präprozessorsymbol zu konvertieren, ersetzen Sie Punkte und Bindestriche durch einen Unterstrich, und ändern Sie Kleinbuchstaben in Großbuchstaben (z. B. das Symbol für netstandard2.0 ist NETSTANDARD2_0).

Sie können die Generierung dieser Symbole über die DisableImplicitFrameworkDefines-Eigenschaft deaktivieren. Weitere Informationen zu dieser Eigenschaft finden Sie unter DisableImplicitFrameworkDefines.

Die vollständige Liste der Präprozessorsymbole für .NET Zielframeworks lautet:

Veraltete Zielframeworks

Die folgenden Zielframeworks sind veraltet. Pakete, die auf diese Zielframeworks ausgelegt sind, sollten in die angegebenen Nachfolgeframeworks migriert werden.

Siehe auch

• Namen der Ziel-Frameworks in .NET 5
• .NET Standard
• .NET Versionsverwaltung
• Windows 11 Releaseinformationen