Edytuj

Udostępnij za pośrednictwem

Windows Runtime APIs not supported in desktop apps

  • Artykuł

Although you can use most Windows Runtime (WinRT) APIs (see Windows UWP namespaces) in your C# or C++ desktop app, there are two main sets of WinRT APIs that aren't supported in desktop apps, or that have restrictions:

  • APIs that have dependencies on user interface (UI) features that were designed for use only in a Universal Windows Platform (UWP) app.
  • APIs that require package identity (see Features that require package identity). Such APIs are supported only in desktop apps that are packaged using MSIX.

This article provides details about both of those sets of WinRT APIs. Where available, this article suggests alternative APIs to achieve the same functionality as the APIs that are unsupported 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

Apps using .NET can make use of provided class implementations for some of the WinRT COM interfaces listed in this article. Those classes are easier to work with than using the WinRT COM interfaces directly. For more information about the available class implementations, see Call interop APIs from a .NET app. Note that those classes require the .NET 6 SDK or later.

This article will be updated as more workarounds and replacements are identified. If you encounter an issue with an API not listed here, please create an issue in the microsoft-ui-xaml repo with the API name and details about what you're 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 a UWP app. Those APIs do not behave properly in desktop apps due to threading model and other platform differences. Those APIs, and other WinRT APIs that have dependencies on them, aren't supported for use in desktop apps.

Core unsupported classes

These WinRT classes aren't 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.
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 a desktop app.
CoreWindow Also see the Classes that implement IInitializeWithWindow section below.

Instead of the GetKeyState method, use the InputKeyboardSource.GetKeyStateForCurrentThread method provided by WinUI 3.

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

For other WinRT APIs that aren't supported in desktop apps, see Unsupported members later in this topic.

Classes with an XxxForCurrentView method

Many WinRT classes have a static GetForCurrentView or CreateForCurrentView method, such as UIViewSettings.GetForCurrentView. Those XxxForCurrentView methods have an implicit dependency on the ApplicationView type, which isn't supported in desktop apps. Because ApplicationView isn't supported in desktop apps, none of the XxxForCurrentView methods are supported either. Some unsupported XxxForCurrentView methods not only return null, but also throw exceptions.

Note

CoreInputView.GetForCurrentView is supported in desktop apps, and it can be used even without a CoreWindow. You can use that method to retrieve a CoreInputView object on any thread; and if that thread has a foreground window, then that object will produce events.

The following classes are supported in desktop apps; but to retrieve an instance of one in a desktop app, you use a mechanism that's different from the GetForCurrentView or CreateForCurrentView methods. For the classes below that have a COM interface listed as the alternative API, C# developers can also consume those WinRT COM interfaces (see Call interop APIs from a .NET app). The list might not be comprehensive.

Class Alternative APIs
AccountsSettingsPane Use the IAccountsSettingsPaneInterop COM interface instead (in accountssettingspaneinterop.h).
CoreDragDropManager Use the IDragDropManagerInterop COM interface instead (in dragdropinterop.h).
CoreTextServicesManager This class is currently supported in desktop apps only in Windows Insider Preview builds.
DataTransferManager Use the IDataTransferManagerInterop COM interface instead (in shobjidl_core.h).
DisplayInformation To retrieve an instance of DisplayInformation, use the IDisplayInformationStaticsInterop interface.

Alternatively, instead of the LogicalDpi property, you can use the XamlRoot.RasterizationScale property, and listen for changes via the XamlRoot.Changed event (the XamlRoot.RasterizationScale property is provided in WinUI 3).

And, instead of the RawPixelsPerViewPixel property, you have the option to use the XamlRoot.RasterizationScale property provided by WinUI 3.
InputPane Use the IInputPaneInterop COM interface instead (in inputpaneinterop.h).
PlayToManager Use the IPlayToManagerInterop COM interface instead (in playtomanagerinterop.h).
Print3DManager Use the IPrinting3DManagerInterop COM interface instead (in print3dmanagerinterop.h).
PrintManager Use the IPrintManagerInterop COM interface instead (in printmanagerinterop.h).
RadialController Use the IRadialControllerInterop COM interface instead (in radialcontrollerinterop.h).
RadialControllerConfiguration Use the IRadialControllerConfigurationInterop COM interface instead (in radialcontrollerinterop.h).
ResourceContext See MRT to MRT Core migration.
ResourceLoader See MRT to MRT Core migration.
SpatialInteractionManager Use the ISpatialInteractionManagerInterop COM interface instead (in spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Use the ISystemMediaTransportControlsInterop COM interface instead (in systemmediatransportcontrolsinterop.h).
UserActivityRequestManager Use the IUserActivityRequestManagerInterop COM interface instead (in useractivityinterop.h).
UIViewSettings Use the IUIViewSettingsInterop COM interface instead (in uiviewsettingsinterop.h).

The following classes are not supported in desktop apps because the APIs don't provide an alternative to their GetForCurrentView or CreateForCurrentView method. The list might not be comprehensive.

Class Alternative APIs
AppCapture None
BrightnessOverride None
ConnectedAnimationService None
CoreInputView None
CoreWindowResizeManager None
DisplayEnhancementOverride None
EdgeGesture None
GazeInputSourcePreview None
HdmiDisplayInformation None
HolographicKeyboardPlacementOverridePreview None
KeyboardDeliveryInterceptor None
LockApplicationHost None
MouseDevice None
PointerVisualizationSettings None
ProtectionPolicyManager None
SearchPane None
SettingsPane None
SystemNavigationManager None
SystemNavigationManagerPreview None
WebAuthenticationBroker None. for more details, see the WebAuthenticationBroker.AuthenticateAsync throws COMException GitHub issue.

Classes that implement IInitializeWithWindow

Certain pickers, popups, dialogs, and other Windows Runtime (WinRT) objects depend on a CoreWindow; typically, to display a UI. Even though CoreWindow isn't supported in desktop apps (see Core unsupported classes above), you can still use many of those WinRT classes in your desktop app by adding a little bit of interoperation code.

For more info (including a list of affected types), and code examples, see Display WinRT UI objects that depend on CoreWindow.

Unsupported members

This section lists (or describes, where a comprehensive list isn't possible) specific members of WinRT classes that aren't 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 event(s).

Class Unsupported events
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Methods

The following classes are supported in desktop apps, except for the specified method(s).

Class Unsupported methods
DeviceInformationPairing PairAsync

Methods that use the Request naming pattern

Most methods that follow the Request naming pattern—such as AppCapability.RequestAccessAsync and StoreContext.RequestPurchaseAsync—aren't supported in desktop apps. Internally, these methods use the Windows.UI.Popups class. That 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 doesn't provide a comprehensive list of those methods.

APIs that require package identity

The following WinRT classes require package identity (see Features that require package identity). These APIs are supported only in desktop apps that are packaged (that is, that have package identity at runtime). The list might not be comprehensive.

In addition, when called from a desktop app that doesn't have package identity, the AdaptiveMediaSource.CreateFromUriAsync methods don't support the ms-appx and ms-resource URI formats.