Call Windows Runtime APIs in desktop apps

Configure a .NET project

.NET 6 and later: Use the Target Framework Moniker option

Specify a Windows OS version-specific Target Framework Moniker (TFM) in your project file. This adds a reference to the appropriate Windows SDK targeting package at build time.

1. In Visual Studio, select Project > [ProjectName] Properties.

2. On the properties page, find Application > General by selecting it in the left side navigation or scrolling to it.

3. Choose settings for:

   1. Target framework - This is initially set to the .NET version you selected when the project was created, but you can change it here.
   2. Target OS - Leave this set to Windows.
   3. Target OS version - Select the version for the API set you want to use, typically the latest.
   4. Supported OS version (Optional) - See the next section for more information.

In the Target Framework Moniker, these values translate like this:

• Target framework - net10.0
• Target OS - -windows
• Target OS version - 10.0.22621.0

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

You can also set the values by manually editing the project file.

1. In Visual Studio, right-click your project in Solution Explorer and choose Edit Project File.

2. Replace the TargetFramework value with a Windows-version-specific TFM.

   Target	TFM
   Windows 11, version 24H2	net10.0-windows10.0.26100.0
   Windows 11, version 22H2	net10.0-windows10.0.22621.0
   Windows 11 (initial release)	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

   Note

   The values shown are for .NET 10. Update as needed for other versions of .NET: net8.0, net9.0.

   Example:

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

3. Save and close the project file.

Supporting a minimum Windows version

To allow your app to run on a Windows version older than your TFM target, set the SupportedOSVersion (SupportedOSPlatformVersion), as shown in the previous section. For more info, see Target frameworks: Support older OS versions.

When you target a range of OS versions, guard calls to APIs that aren't available on all versions using ApiInformation checks. For more information, see Version adaptive apps.

When SupportedOSVersion is set, Visual Studio will give a warning for APIs that need a runtime check. For example, if the target version is 19041, and the minimum version is 17763, you will see a warning like this when you call AppInfo.Current.

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 not supported in .NET 6 and later

In .NET 6 and later, several WinRT APIs in the Windows.UI namespace are not supported. Use the equivalent APIs in the Microsoft.UI namespace (provided by the Windows App SDK) instead:

.NET Core 3.x or .NET Framework: Install the NuGet package

If your app targets .NET Core 3.x or .NET Framework, install the Microsoft.Windows.SDK.Contracts NuGet package:

1. In Visual Studio, right-click your project and choose Manage NuGet Packages.

2. Search for Microsoft.Windows.SDK.Contracts.

3. Select the package version matching your minimum Windows target:

   Package version	Windows target
   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. Click Install.

Multi-targeting .NET 6+ and earlier .NET versions

Configure the project file to use the TFM approach for .NET 6+ and the NuGet package for earlier versions:

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

Conditional compilation

When multi-targeting across .NET 6+ and earlier versions, use conditional compilation to write version-specific code in a single project. For more information, see Target frameworks: Preprocessor symbols.

#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

Configure a C++ (Win32) project

Use C++/WinRT to consume WinRT APIs from C++ desktop apps.

• Install the Microsoft.Windows.CppWinRT NuGet package.
• Because C++/WinRT uses features from the C++17 standard, ensure the project property C/C++ > Language > C++ Language Standard is set to ISO C++17 Standard (/std:c++17) or later in Visual Studio.

For more details, see Visual Studio support for C++/WinRT.