Aufrufen von Windows-Runtime-APIs in Desktop-Apps

Konfigurieren eines .NET Projekts

.NET 6 und höher: Verwenden Sie die Option "Target Framework Moniker"

Geben Sie einen betriebssystem-spezifischen Ziel-Framework-Moniker (TFM) in Ihrer Projektdatei an. Dadurch wird zur Erstellungszeit ein Verweis auf das entsprechende Windows SDK-Zielpaket hinzugefügt.

1. Wählen Sie in Visual Studio Project > [ProjectName] Eigenschaften aus.

2. Suchen Sie auf der Eigenschaftenseite "Allgemeines zur Anwendung>", indem Sie es in der linken Navigationsleiste auswählen oder nach unten scrollen.

3. Wählen Sie Einstellungen für:

   1. Target-Framework – Dies wird zunächst auf die .NET Version festgelegt, die Sie beim Erstellen des Projekts ausgewählt haben, aber Sie können es hier ändern.
   2. Target-OS – Lassen Sie diese Einstellung auf Windows.
   3. Zielbetriebssystemversion – Wählen Sie die Version für den API-Satz aus, den Sie verwenden möchten, in der Regel die neueste.
   4. Unterstützte Betriebssystemversion (Optional) – Weitere Informationen finden Sie im nächsten Abschnitt.

Diese Werte werden im Target Framework Moniker wie folgt übersetzt:

• Ziel-Framework - net10.0
• Zielbetriebssystem - -windows
• Zielbetriebssystemversion - 10.0.22621.0

<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
<!-- If set... -->
<SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

Sie können die Werte auch festlegen, indem Sie die Projektdatei manuell bearbeiten.

1. Klicken Sie in Visual Studio mit der rechten Maustaste auf Ihr Projekt im Projektmappen-Explorer und wählen Sie Projektdatei bearbeiten aus.

2. Ersetzen Sie den Wert TargetFramework durch einen Windows-versionsspezifischen TFM.

   Ziel	TFM
   Windows 11, Version 24H2	net10.0-windows10.0.26100.0
   Windows 11, Version 22H2	net10.0-windows10.0.22621.0
   Windows 11 (erstversion)	net10.0-windows10.0.22000.0
   Windows 10, Version 2004	net10.0-windows10.0.19041.0
   Windows 10, Version 1903	net10.0-windows10.0.18362.0
   Windows 10, Version 1809	net10.0-windows10.0.17763.0

   Hinweis

   Die angezeigten Werte gelten für .NET 10. Aktualisieren Sie nach Bedarf für andere Versionen von .NET: net8.0, net9.0.

   Beispiel:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     </PropertyGroup>
   </Project>
   

3. Speichere und schließe die Projektdatei.

Unterstützung einer mindestens Windows Version

Wenn Ihre App auf einer Windows Version ausgeführt werden soll, die älter als Ihr TFM-Ziel ist, legen Sie die SupportedOSVersion (SupportedOSPlatformVersion) fest, wie im vorherigen Abschnitt gezeigt. Weitere Informationen finden Sie unter Zielframeworks: Unterstützen älterer Betriebssystemversionen.

Wenn Sie auf eine Reihe von Betriebssystemversionen abzielen, schützen Sie Aufrufe von APIs, die für alle Versionen mit ApiInformation-Prüfungen nicht verfügbar sind. Weitere Informationen finden Sie unter Versionsadaptive Apps.

Wenn SupportedOSVersion festgelegt ist, gibt Visual Studio eine Warnung für APIs an, die eine Laufzeitüberprüfung benötigen. Wenn die Zielversion beispielsweise 19041 ist und die Mindestversion 17763 ist, wird beim Aufrufen von AppInfo.Current eine Warnung wie folgt angezeigt.

CA1416	Using platform dependent API on a component makes the code no longer work across all platforms.

This call site is reachable on: 'Windows' 10.0.17763.0 and later. 'AppInfo.Current' is only supported on: 'Windows' 10.0.19041.0 and later.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
  </PropertyGroup>
</Project>

WinRT-APIs werden in .NET 6 und höher nicht unterstützt

In .NET 6 und höher werden mehrere WinRT-APIs im Windows.UI Namespace nicht unterstützt. Verwenden Sie die entsprechenden APIs im Microsoft. Ui Namespace (bereitgestellt durch den Windows App SDK) stattdessen:

.NET Core 3.x oder .NET Framework: Installieren des NuGet-Pakets

Wenn Ihre App auf .NET Core 3.x oder .NET Framework ausgerichtet ist, installieren Sie das Microsoft.Windows.SDK.Contracts NuGet-Paket:

1. Klicken Sie in Visual Studio mit der rechten Maustaste auf Ihr Projekt, und wählen Sie Manage NuGet Packages aus.

2. Suchen Sie nach Microsoft.Windows.SDK.Contracts.

3. Wählen Sie die Paketversion aus, die Ihrem mindesten Windows Ziel entsprechen:

   Paketversion	Windows-Zielsystem
   10.0.19041.xxxx	Windows 10, Version 2004
   10.0.18362.xxxx	Windows 10, Version 1903
   10.0.17763.xxxx	Windows 10, Version 1809
   10.0.17134.xxxx	Windows 10, Version 1803

4. Klicken Sie auf Installieren.

Multitargeting .NET 6+ und den früheren .NET-Versionen

Konfigurieren Sie die Projektdatei so, dass der TFM-Ansatz für .NET 6+ und das NuGet-Paket für frühere Versionen verwendet wird:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net8.0-windows10.0.19041.0</TargetFrameworks>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0"/>
  </ItemGroup>
</Project>

Bedingte Kompilierung

Verwenden Sie die bedingte Kompilierung beim Multiadressieren in .NET 6+ und früheren Versionen, um versionsspezifischen Code in einem einzelnen Projekt zu schreiben. Weitere Informationen finden Sie unter Zielframeworks: Präprozessorsymbole.

#if NET6_0_OR_GREATER
    // Code that uses .NET 6+ APIs or TFM-available WinRT APIs
#else
    // Fallback code for .NET Core 3.x / .NET Framework
#endif

Konfigurieren eines C++-Projekts (Win32)

Verwenden Sie C++/WinRT , um WinRT-APIs aus C++-Desktop-Apps zu nutzen.

• Installieren Sie das Microsoft.Windows.CppWinRT NuGet-Paket.
• Da C++/WinRT Features aus dem C++17-Standard verwendet, stellen Sie sicher, dass die Projekteigenschaft C/C++ > Language > C++ Language Standard auf ISO C++17 Standard (/std:c++17) oder höher in Visual Studio festgelegt ist.

Weitere Informationen finden Sie unter Visual Studio Support für C++/WinRT.