Windows Runtime APIs not supported in desktop apps

Although most Windows Runtime (WinRT) APIs can be used by desktop apps (.NET 5 and native C++), there are two main sets of WinRT APIs that are not supported in desktop apps or have restrictions:

  • APIs that have dependencies on UI features that were designed for use only in UWP apps.
  • APIs that require require package identity. These APIs are only supported in desktop apps that are packaged using MSIX.

This article provides details about both of these sets of WinRT APIs. Where available, this article suggests alternative APIs to achieve the same functionality as the unsupported APIs in desktop apps. Most of the alternative APIs are available in WinUI 3 or via WinRT COM interfaces that are available in the Windows SDK.

Note

Starting with the .NET 5.0.205 SDK and .NET 5.0.302 SDK releases, .NET 5 apps can make use of provided class implementations for some of the WinRT COM interfaces listed in this article. These classes are easier to work with than using the WinRT COM interfaces directly. For more information about the available class implementations, see Call WinRT COM interop interfaces from .NET 5+ apps.

This article will be updated as more workarounds and replacements are identified. If you encounter an issue with an API not listed here, create an issue in the microsoft-ui-xaml repo with the API and and provide details about what you are trying to achieve by using it.

APIs that have dependencies on UWP-only UI features

Some WinRT APIs were designed specifically for UI scenarios in UWP apps. These APIs do not behave properly in desktop apps due to threading models and other platform differences. These APIs, and other WinRT APIs that have dependencies them, are not supported for use in desktop apps.

Core unsupported classes

The following WinRT classes are not supported in desktop apps.

Class Alternative APIs
ApplicationView None
CoreApplicationView Use the Window class provided by WinUI 3 instead.
CoreApplicationViewTitleBar Instead of the ExtendViewIntoTitleBar property, use the Window.ExtendsContentIntoTitleBar property provided by WinUI 3 instead.
CoreDispatcher Use the Microsoft.UI.Xaml.Window.DispatcherQueue property provided by WinUI 3 instead.

Note that the Windows.UI.Xaml.Window.Dispatcher and Windows.UI.Xaml.DependencyObject.Dispatcher properties return null in desktop apps.
CoreWindow Instead of the GetKeyState method, use the KeyboardInput.GetKeyStateForCurrentThread method provided by WinUI 3 instead.

Instead of the PointerCursor property, use the UIElement.ProtectedCursor property provided by WinUI 3 instead. You'll need to have a subclass of UIElement to access this property.
UserActivity Use the IUserActivitySourceHostInterop COM interface instead (in useractivityinterop.h).

Classes with GetForCurrentView methods

Many WinRT classes have a static GetForCurrentView method, such as UIViewSettings.GetForCurrentView. These GetForCurrentView methods have an implicit dependency on the ApplicationView class, which isn't supported in desktop apps. Because ApplicationView isn't supported in desktop apps, none of these other classes with GetForCurrentView methods are supported either. Note that some unsupported GetForCurrentView methods will not only return null, but will also throw exceptions.

For those classes below that have a COM interface alternative API listed, C# developers on .NET 5 or later can consume these WinRT COM interfaces starting in the July 2021 .NET 5 SDK update.

Note

One exception to this is CoreInputView.GetForCurrentView, which is supported in desktop apps and can be used even without a CoreWindow. This method can be used to get a CoreInputView object on any thread, and if that thread has a foreground window, that object will produce events.

The following classes are not supported in desktop apps because they have GetForCurrentView methods. This list may not be comprehensive.

Class Alternative APIs
AccountsSettingsPane Use the IAccountsSettingsPaneInterop COM interface instead (in accountssettingspaneinterop.h).
AppCapture None
BrightnessOverride None
ConnectedAnimationService None
CoreDragDropManager Use the IDragDropManagerInterop COM interface instead (in dragdropinterop.h).
CoreInputView None
CoreTextServicesManager This class is currently supported in desktop apps only in Windows Insider Preview builds.
CoreWindowResizeManager None
DataTransferManager Use the IDataTransferManagerInterop COM interface instead (in shobjidl_core.h).
DisplayEnhancementOverride None
DisplayInformation Instead of the LogicalDpi property, use the XamlRoot.RasterizationScale property and listen for changes on the XamlRoot.Changed event (the XamlRoot.RasterizationScale property is provided in WinUI 3).

Instead of the RawPixelsPerViewPixel property, use the XamlRoot.RasterizationScale property provided by WinUI 3.
EdgeGesture None
GazeInputSourcePreview None
HdmiDisplayInformation None
HolographicKeyboardPlacementOverridePreview None
InputPane Use the IInputPaneInterop COM interface instead (in inputpaneinterop.h).
KeyboardDeliveryInterceptor None
LockApplicationHost None
MouseDevice None
PlayToManager Use the IPlayToManagerInterop COM interface instead (in playtomanagerinterop.h).
PointerVisualizationSettings None
Print3DManager Use the IPrinting3DManagerInterop COM interface instead (in print3dmanagerinterop.h).
PrintManager Use the IPrintManagerInterop COM interface instead (in printmanagerinterop.h).
ProtectionPolicyManager None
RadialControllerConfiguration Use the IRadialControllerConfigurationInterop COM interface instead (in radialcontrollerinterop.h).
ResourceContext See MRT to MRT Core migration
ResourceLoader See MRT to MRT Core migration
SearchPane None
SettingsPane None
SpatialInteractionManager Use the ISpatialInteractionManagerInterop COM interface instead (in spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Use the ISystemMediaTransportControlsInterop COM interface instead (in systemmediatransportcontrolsinterop.h).
SystemNavigationManager None
SystemNavigationManagerPreview None
UserActivityRequestManager Use the IUserActivityRequestManagerInterop COM interface insead (in useractivityinterop.h).
UIViewSettings Use the IUIViewSettingsInterop COM interface instead (in uiviewsettingsinterop.h).
WebAuthenticationBroker None. for more details, see this GitHub issue.

Classes that use IInitializeWithWindow

Some WinRT classes require a CoreWindow object on which to call certain methods, typically to display a UI. Because the CoreWindow class is not supported in desktop apps, these WinRT classes cannot be used in desktop apps by default.

However, some of these classes implement the IInitializeWithWindow interface, which provides a way to use them in desktop apps. This interface enables you to specify the owner window for the operations that will be performed using the class. Examples of these classes include PopupMenu and FileOpenPicker. For more details, including a list of more WinRT classes that implement this interface, see IInitializeWithWindow.

The following example demonstrates how to use the IInitializeWithWindow interface to specify the owner window for the FileOpenPicker class.

#include <shobjidl.h>
#include <winrt/windows.storage.pickers.h>

winrt::Windows::Foundation::IAsyncAction
ShowFilePickerAsync(HWND hwnd)
{
    auto picker = winrt::Windows::Storage::Pickers::FileOpenPicker();
    picker.as<IInitializeWithWindow>()->Initialize(hwnd);
    picker.FileTypeFilter().Append(L".jpg");
    auto file = co_await picker.PickSingleFileAsync();
}

Note

In C# apps that use .NET 5 and later, you can use the WinRT.Interop.InitializeWithWindow helper class instead of using the IInitializeWithWindow interface directly. For more information, see Call WinRT COM interop interfaces from .NET 5+ apps.

Unsupported members

This section lists (or describes, where a comprehensive list is not possible) specific members of WinRT classes that are not supported for use in desktop apps. Unless otherwise noted, the rest of the classes apart from these members are supported in desktop apps.

Events

The following classes are supported in desktop apps except for the specified events.

Class Unsupported events
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Methods that use the Request naming pattern

Methods that follow the Request naming pattern, such as AppCapability.RequestAccessAsync and StoreContext.RequestPurchaseAsync, are not supported in desktop apps. Internally, these methods use the Windows.UI.Popups class. This class requires that the thread have a CoreWindow object, which isn't supported in desktop apps.

The full list of methods that follow the Request naming pattern is very long, and this article does not provide a comprehensive list of these methods.

APIs that require package identity

The following WinRT classes require require package identity. These APIs are only supported in desktop apps that are packaged using MSIX. This list may not be comprehensive.