桌面应用中不支持的 Windows 运行时 API

  • 项目

尽管可以在 C# 或 C++ 桌面应用中使用大多数 Windows 运行时 (WinRT) API（请参阅 Windows UWP 命名空间），但有两个主要的 WinRT API 集在桌面应用中不受支持或具有限制：

  • 依赖于用户界面 (UI) 功能的 API，这些功能仅在通用 Windows 平台 (UWP) 应用中可用。
  • 需要程序包标识符的 API（请参阅需要程序包标识符的功能）。 此类 API 仅在使用 MSIX 打包的桌面应用中受支持。

本文提供了有关这两个 WinRT API 集的详细信息。 如果可能，本文建议使用替代 API 来实现与桌面应用中不受支持的 API 相同的功能。 大多数替代 API 都是通过 WinUI 3 或通过 Windows SDK 中的 WinRT COM 接口提供的。

注意

使用 .NET 的应用可以将提供的类实现用于本文中列出的某些 WinRT COM 接口。 与直接使用 WinRT COM 接口相比，这些类更易于使用。 有关可用类实现的详细信息，请参阅从 .NET 应用调用互操作 API。 请注意，这些类需要 .NET 6 SDK 或更高版本。

本文将随着更多解决方法和替换内容的确定而进行更新。 如果你遇到有关此处未列出的某个 API 的问题，请在 microsoft-ui-xaml 存储库中创建一个问题，并提供 API 名称和有关你要尝试用其实现哪些操作的详细信息。

依赖于 UI 功能（仅限 UWP 使用）的 API

某些 WinRT API 专为 UWP 应用中的 UI 方案而设计。 由于线程模型和其他平台差异，这些 API 在桌面应用中不能正常运行。 桌面应用中不支持使用这些 API 和其他依赖于它们的 WinRT API。

主要不受支持的类

桌面应用中不支持以下 WinRT 类：

实例 替代 API
ApplicationView 无
CoreApplicationView 请改为使用 WinUI 3 提供的 Window 类。
CoreApplicationViewTitleBar 请勿使用 ExtendViewIntoTitleBar 属性，而改为使用 WinUI 3 提供的 Window.ExtendsContentIntoTitleBar 属性。
CoreDispatcher 请改为使用 WinUI 3 提供的 Microsoft.UI.Xaml.Window.DispatcherQueue 属性。

请注意，Windows.UI.Xaml.Window.Dispatcher 和 Windows.UI.Xaml.DependencyObject.Dispatcher 属性在桌面应用中会返回 null。
CoreWindow 另请参阅下面的实现 IInitializeWithWindow 的类部分。

请勿使用 GetKeyState 方法，而改为使用 WinUI 3 提供的 InputKeyboardSource.GetKeyStateForCurrentThread 方法。

请勿使用 PointerCursor 属性，而改为使用 WinUI 3 提供的 UIElement.ProtectedCursor 属性。 访问此属性需要具有 UIElement 的子类。
UserActivity 请改为使用 IUserActivitySourceHostInterop COM 接口（位于 useractivityinterop.h 中）。

有关桌面应用不支持的其他 WinRT API，请参阅本主题后面的不受支持的成员。

具有 XxxForCurrentView 方法的类

许多 WinRT 类都具有静态 GetForCurrentView 或 CreateForCurrentView 方法，例如 UIViewSettings.GetForCurrentView。 这些 XxxForCurrentView 方法对 ApplicationView 类型具有隐式依赖关系，桌面应用中不支持这种关系。 由于桌面应用中不支持 ApplicationView，因此也不支持 XxxForCurrentView 方法。 某些不受支持的 XxxForCurrentView 方法不仅会返回 null，还会引发异常。

注意

CoreInputView.GetForCurrentView在桌面应用中受到支持，甚至在没有 CoreWindow 的情况下也可以使用。 可以使用此方法检索任何线程上的 CoreInputView 对象；如果该线程具有前台窗口，则该对象将生成事件。

桌面应用支持以下类；但要在桌面应用中检索其中某个类的实例，需使用不同于 GetForCurrentView 或 CreateForCurrentView 方法的机制。 对于将 COM 接口列为替代 API 的以下类，C# 开发人员也可以使用这些 WinRT COM 接口（请参阅从 .NET 应用调用互操作 API）。 此列表可能不是完整的列表。

实例 替代 API
AccountsSettingsPane 请改为使用 IAccountsSettingsPaneInterop COM 接口（位于 accountssettingspaneinterop.h 中）。
CoreDragDropManager 请改为使用 IDragDropManagerInterop COM 接口（位于 dragdropinterop.h 中）。
CoreTextServicesManager 此类当前仅在 Windows 预览体验成员预览版桌面应用中受支持。
DataTransferManager 请改为使用 IDataTransferManagerInterop COM 接口（位于 shobjidl_core.h 中）。
DisplayInformation 若要检索 DisplayInformation 的实例，请使用 IDisplayInformationStaticsInterop 接口。

或者，可使用 XamlRoot.RasterizationScale 属性而非 LogicalDpi 属性，并通过 XamlRoot.Changed 事件（XamlRoot.RasterizationScale 属性在 WinUI 3 中提供）侦听更改。

而且，可选择使用 WinUI 3 提供的 XamlRoot.RasterizationScale 属性，而不是 RawPixelsPerViewPixel 属性。
InputPane 请改为使用 IInputPaneInterop COM 接口（位于 inputpaneinterop.h 中）。
PlayToManager 请改为使用 IPlayToManagerInterop COM 接口（位于 playtomanagerinterop.h 中）。
Print3DManager 请改为使用 IPrinting3DManagerInterop COM 接口（位于 print3dmanagerinterop.h）。
PrintManager 请改为使用 IPrintManagerInterop COM 接口（位于 printmanagerinterop.h 中）。
RadialController 请改为使用 IRadialControllerInterop COM 接口（位于 radialcontrollerinterop.h 中）。
RadialControllerConfiguration 请改为使用 IRadialControllerConfigurationInterop COM 接口（位于 radialcontrollerinterop.h 中）。
ResourceContext 请参阅 MRT 到 MRT Core 的迁移。
ResourceLoader 请参阅 MRT 到 MRT Core 的迁移。
SpatialInteractionManager 请改为使用 ISpatialInteractionManagerInterop COM 接口（位于 spatialinteractionmanagerinterop.h 中）。
SystemMediaTransportControls 请改为使用 ISystemMediaTransportControlsInterop COM 接口（位于 systemmediatransportcontrolsinterop.h 中）。
UserActivityRequestManager 请改为使用 IUserActivityRequestManagerInterop COM 接口（位于 useractivityinterop.h 中）。
UIViewSettings 请改为使用 IUIViewSettingsInterop COM 接口（位于 uiviewsettingsinterop.h 中）。

以下类在桌面应用中不受支持，因为 API 不提供其 GetForCurrentView 或 CreateForCurrentView 方法的替代方法。 此列表可能不是完整的列表。

实例 替代 API
AppCapture 无
BrightnessOverride 无
ConnectedAnimationService 无
CoreInputView 无
CoreWindowResizeManager 无
DisplayEnhancementOverride 无
EdgeGesture 无
GazeInputSourcePreview 无
HdmiDisplayInformation 无
HolographicKeyboardPlacementOverridePreview 无
KeyboardDeliveryInterceptor 无
LockApplicationHost 无
MouseDevice 无
PointerVisualizationSettings 无
ProtectionPolicyManager 无
SearchPane 无
SettingsPane 无
SystemNavigationManager 无
SystemNavigationManagerPreview 无
WebAuthenticationBroker 无。 有关详细信息，请参阅 WebAuthenticationBroker.AuthenticateAsync 引发 COMException GitHub 问题。

实现 IInitializeWithWindow 的类

某些选取器、弹出窗口、对话框和其他 Windows 运行时 (WinRT) 对象依赖于 CoreWindow；通常用于显示 UI。 即使 CoreWindow 在桌面应用中不受支持（请参阅上面的主要不受支持的类），但你仍可通过添加少量互操作代码在桌面应用中使用其中许多 WinRT 类。

有关详细信息（包括受影响类型的列表）和代码示例，请参阅显示依赖于 CoreWindow 的 WINRT UI 对象。

不支持的成员

本部分列出了（或在不可能提供完整列表时说明了）不可在桌面应用中使用的 WinRT 类的特定成员。 除非另有说明，否则桌面应用中支持除以下成员之外的其他类。

事件

除指定的事件外，桌面应用支持以下类。

实例 不支持的事件
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

方法

除指定的方法外，桌面应用支持以下类。

类 不受支持的方法
DeviceInformationPairing PairAsync

使用 Request 命名模式的方法

桌面应用不支持采用 Request 命名模式的大多数方法，例如 AppCapability.RequestAccessAsync 和 StoreContext.RequestPurchaseAsync。 在内部，这些方法使用 Windows.UI.Popups 类。 该类要求线程具有 CoreWindow 对象，但桌面应用中不支持该对象。

使用 Request 命名模式的方法的完整列表非常长，本文未提供这些方法的完整列表。

需要包标识的 API

以下 WinRT 类需要程序包标识符（请参阅需要程序包标识符的功能）。 这些 API 仅在打包的桌面应用中受支持（即在运行时具有程序包标识符）。 此列表可能不是完整的列表。

此外，当从没有程序包标识符的桌面应用调用时，AdaptiveMediaSource.CreateFromUriAsync 方法不支持 ms-appx 和 ms-resource URI 格式。