傳統型應用程式中不支援 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 應用程式呼叫 Interop API。 請注意，這些類別需要 .NET 6 SDK 或更新版本。

本文將隨著識別更多因應措施和取代項目而進行更新。 如果您遇到此處未列出的 API 問題，請使用 API 名稱以及使用 API 嘗試達成目標的詳細資料，在 microsoft-ui-xaml 存放庫中建立問題。

具有僅限 UWP UI 功能相依性的 API

某些 WinRT API 專為 UWP 應用程式中的 UI 案例所設計。 由於執行緒模式和其他平台差異，這些 API 在傳統型應用程式中的行為不正確。 傳統型應用程式不支援這些 API 和其他與其具有相依性的 WinRT API。

核心不支援的類別

傳統型應用程式中不支援這些 WinRT 類別：

類別 替代 API
ApplicationView 無
CoreApplicationView 請改用 WinUI 3 所提供的 Window 類別。
CoreApplicationViewTitleBar 使用 WinUI 3 所提供的 Window.ExtendsContentIntoTitleBar 屬性，而不是 ExtendViewIntoTitleBar 屬性。
CoreDispatcher 請改用 WinUI 3 提供的 Microsoft.UI.Xaml.Window.DispatcherQueue 屬性。

請注意，Windows.UI.Xaml.Window.Dispatcher 和 Windows.UI.Xaml.DependencyObject.Dispatcher 屬性會在傳統型應用程式中傳回 null。
CoreWindow 另請參閱下列實作 IInitializeWithWindow 的類別一節。

使用 WinUI 3 所提供的 InputKeyboardSource.GetKeyStateForCurrentThread 方法，而不是 GetKeyState 方法。

使用 WinUI 3 所提供的 UIElement.ProtectedCursor 屬性，而不是 PointerCursor 屬性。 您必須有 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 應用程式呼叫 Interop API)。 該清單可能不完整。

類別 替代 API
AccountsSettingsPane 請改用 IAccountsSettingsPaneInterop COM 介面 (在 accountssettingspaneinterop.h 中)。
CoreDragDropManager 請改用 IDragDropManagerInterop COM 介面 (在 dragdropinterop.h 中)。
CoreTextServicesManager 此類別目前僅在 Windows Insider Preview 組建中才支援傳統型應用程式。
DataTransferManager 請改用 IDataTransferManagerInterop COM 介面 (在 shobjidl_core.h 中)。
DisplayInformation 若要擷取 DisplayInformation 的執行個體，請使用 IDisplayInformationStaticsInterop 介面。

或者，除了 LogicalDpi 屬性，您可以使用 XamlRoot.RasterizationScale 屬性，並透過 XamlRoot.Changed 事件接聽變更 (WinUI 3 中提供 XamlRoot.RasterizationScale 屬性)。

而且，除了 RawPixelsPerViewPixel 屬性，您也可以選擇使用 WinUI 3 提供的 XamlRoot.RasterizationScale 屬性。
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 核心移轉。
ResourceLoader 請參閱 MRT 至 MRT 核心移轉。
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

使用要求命名模式的方法

傳統型應用程式不支援遵循請求 命名模式的大多數方法 (例如 AppCapability.RequestAccessAsync 和 StoreContext.RequestPurchaseAsync)。 在內部，這些方法會使用 Windows.UI.Popups 類別。 該類別要求執行緒具有 CoreWindow 物件，這在傳統型應用程式中不受支援。

遵循要求命名模式的方法完整清單很長，本文不提供這些方法的完整清單。

需要套件識別資料的功能

下列 WinRT 類別需要套件識別資料 (請參閱需要套件識別資料的功能)。 這些 API 僅支援封裝的傳統型應用程式 (也就是在執行階段具有套件識別資料)。 該清單可能不完整。

此外，從沒有套件識別資料的傳統型應用程式呼叫時，AdaptiveMediaSource.CreateFromUriAsync 方法不支援 ms-appx 和 ms-resource URI 格式。