In Desktop-Apps nicht unterstützte Windows-Runtime-APIs

  • Artikel

Obwohl Sie die meisten Windows-Runtime (WinRT)-APIs in Ihrer C#- oder C++-Desktop-App verwenden können (siehe Windows UWP-Namespaces), gibt es zwei Hauptgruppen von WinRT-APIs, die in Desktop-Apps nicht unterstützt werden oder für die Einschränkungen gelten:

  • APIs, die Abhängigkeiten von Benutzeroberflächenfeatures (UI) aufweisen und nur zur Verwendung in einer UWP-Apps (Universelle Windows-Plattform) entwickelt wurden.
  • APIs, die Paketidentität erfordern (siehe Features, die eine Paketidentität erfordern). Solche APIs werden nur in Desktop-Apps unterstützt, die mit MSIX gepackt wurden.

Dieser Artikel enthält Details zu diesen beiden Gruppen von WinRT-APIs. Falls verfügbar, werden in diesem Artikel alternative APIs vorgeschlagen, mit denen Sie die gleiche Funktionalität wie mit den in Desktop-Apps nicht unterstützten APIs erreichen. Die meisten alternativen APIs sind in WinUI 3 oder über WinRT-COM-Schnittstellen im Microsoft Windows SDK verfügbar.

Hinweis

Apps, die .NET verwenden, können bereitgestellte Klassenimplementierungen für einige der in diesem Artikel aufgeführten WinRT-COM-Schnittstellen verwenden. Die Verwendung dieser Klassen ist einfacher als die direkte Verwendung der WinRT-COM-Schnittstellen. Weitere Informationen zu den verfügbaren Klassenimplementierungen finden Sie unter Aufrufen von Interop-APIs aus einer .NET-App. Beachten Sie, dass diese Klassen das .NET 6 SDK oder höher erfordern.

Dieser Artikel wird aktualisiert, wenn weitere Problemumgehungen und Ersetzungen verfügbar sind. Wenn Sie auf ein Problem mit einer hier nicht aufgeführten API stoßen, erstellen Sie ein Problem im Repository microsoft-ui-xaml. Geben Sie dabei den API-Namen und Details darüber an, was Sie mit der API erreichen möchten.

APIs, die von reinen UWP-Benutzeroberflächenfeatures abhängig sind

Einige WinRT-APIs wurden speziell für Benutzeroberflächenszenarien in UWP-Apps entwickelt. Diese APIs verhalten sich in Desktop-Apps aufgrund von Threadingmodellen und anderen Plattformunterschieden nicht ordnungsgemäß. Die Verwendung dieser APIs und anderer davon abhängiger WinRT-APIs wird in Desktop-Apps nicht unterstützt.

Wichtige nicht unterstützte Klassen

Diese WinRT-Klassen werden in Desktop-Apps nicht unterstützt:

Class Alternative APIs
ApplicationView Keine
CoreApplicationView Verwenden Sie stattdessen die von WinUI 3 bereitgestellte Window-Klasse.
CoreApplicationViewTitleBar Verwenden Sie anstelle der Eigenschaft ExtendViewIntoTitleBar die von WinUI 3 bereitgestellte Eigenschaft Window.ExtendsContentIntoTitleBar.
CoreDispatcher Verwenden Sie stattdessen die von WinUI 3 bereitgestellte Eigenschaft Microsoft.UI.Xaml.Window.DispatcherQueue.

Beachten Sie, dass die Eigenschaften Windows.UI.Xaml.Window.Dispatcher und Windows.UI.Xaml.DependencyObject.Dispatcher in einer Desktop-App null zurückgeben.
CoreWindow Weitere Informationen finden Sie auch im Abschnitt Klassen, die „IInitializeWithWindow“ implementieren weiter unten.

Verwenden Sie anstelle der Methode GetKeyState die von WinUI 3 bereitgestellte Methode InputKeyboardSource.GetKeyStateForCurrentThread.

Verwenden Sie anstelle der Eigenschaft PointerCursor die von WinUI 3 bereitgestellte Eigenschaft UIElement.ProtectedCursor. Sie benötigen eine Unterklasse von UIElement, um auf diese Eigenschaft zugreifen zu können.
UserActivity Verwenden Sie stattdessen die COM-Schnittstelle IUserActivitySourceHostInterop (in useractivityinterop.h).

Weitere WinRT-APIs, die in Desktop-Apps nicht unterstützt werden, finden Sie weiter unten in diesem Thema unter Nicht unterstützte Member.

Klassen mit einer XxxForCurrentView-Methode

Viele WinRT-Klassen verfügen über eine statische GetForCurrentView- oder CreateForCurrentView -Methode, z. B. UIViewSettings.GetForCurrentView. Diese XxxForCurrentView-Methoden weisen eine implizite Abhängigkeit vom ApplicationView-Typ auf, die in Desktop-Apps nicht unterstützt wird. Da ApplicationView in Desktop-Apps nicht unterstützt wird, wird auch keine der XxxForCurrentView-Methoden unterstützt. Einige nicht unterstützte XxxForCurrentView-Methoden geben nicht nur null zurück, sondern lösen auch Ausnahmen aus.

Hinweis

CoreInputView.GetForCurrentViewwird in Desktop-Apps unterstützt und kann auch ohne CoreWindow verwendet werden. Sie können diese Methode verwenden, um ein CoreInputView-Objekt in einem beliebigen Thread abzurufen. Wenn dieser Thread über ein Vordergrundfenster verfügt, dann erzeugt dieses Objekt Ereignisse.

Die folgenden Klassen werden in Desktop-Apps unterstützt. Um jedoch eine Instanz davon in einer Desktop-App abzurufen, verwenden Sie einen Mechanismus, der sich von den Methoden GetForCurrentView oder CreateForCurrentView unterscheidet. Für die unten aufgeführten Klassen, für die eine COM-Schnittstelle als alternative API aufgeführt ist, können C#-Entwickler auch diese WinRT-COM-Schnittstellen verwenden (siehe Aufrufen von Interop-APIs aus einer .NET-App). Die Liste ist möglicherweise nicht vollständig.

Class Alternative APIs
AccountsSettingsPane Verwenden Sie stattdessen die COM-Schnittstelle IAccountsSettingsPaneInterop (in accountssettingspaneinterop.h).
CoreDragDropManager Verwenden Sie stattdessen die COM-Schnittstelle IDragDropManagerInterop (in dragdropinterop.h).
CoreTextServicesManager Diese Klasse wird derzeit nur in Desktop-Apps in Windows Insider Preview-Builds unterstützt.
DataTransferManager Verwenden Sie stattdessen die COM-Schnittstelle IDataTransferManagerInterop (in shobjidl_core.h).
DisplayInformation Um eine Instanz von DisplayInformation abzurufen, verwenden Sie die Schnittstelle IDisplayInformationStaticsInterop.

Alternativ können Sie anstelle der Eigenschaft LogicalDpi die Eigenschaft XamlRoot.RasterizationScale verwenden und das XamlRoot.Changed auf Änderungen überwachen (die Eigenschaft XamlRoot.RasterizationScale wird in WinUI 3 bereitgestellt).

Und anstelle der Eigenschaft RawPixelsPerViewPixel können Sie die von WinUI 3 bereitgestellte Eigenschaft XamlRoot.RasterizationScale verwenden.
InputPane Verwenden Sie stattdessen die COM-Schnittstelle IInputPaneInterop (in inputpaneinterop.h).
PlayToManager Verwenden Sie stattdessen die COM-Schnittstelle IPlayToManagerInterop (in playtomanagerinterop.h).
Print3DManager Verwenden Sie stattdessen die COM-Schnittstelle IPrinting3DManagerInterop (in print3dmanagerinterop.h).
PrintManager Verwenden Sie stattdessen die COM-Schnittstelle IPrintManagerInterop (in printmanagerinterop.h).
RadialController Verwenden Sie stattdessen die COM-Schnittstelle IRadialControllerInterop (in radialcontrollerinterop.h).
RadialControllerConfiguration Verwenden Sie stattdessen die COM-Schnittstelle IRadialControllerConfigurationInterop (in radialcontrollerinterop.h).
ResourceContext Siehe Migration von MRT zu MRT Core.
ResourceLoader Siehe Migration von MRT zu MRT Core.
SpatialInteractionManager Verwenden Sie stattdessen die COM-Schnittstelle ISpatialInteractionManagerInterop (in spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Verwenden Sie stattdessen die COM-Schnittstelle ISystemMediaTransportControlsInterop (in systemmediatransportcontrolsinterop.h).
UserActivityRequestManager Verwenden Sie stattdessen die COM-Schnittstelle IUserActivityRequestManagerInterop (in useractivityinterop.h).
UIViewSettings Verwenden Sie stattdessen die COM-Schnittstelle IUIViewSettingsInterop (in uiviewsettingsinterop.h).

Die folgenden Klassen werden in Desktop-Apps nicht unterstützt, da die APIs keine Alternative zu ihrer GetForCurrentView- oder CreateForCurrentView-Methode bereitstellen. Die Liste ist möglicherweise nicht vollständig.

Class Alternative APIs
AppCapture Keine
BrightnessOverride Keine
ConnectedAnimationService Keine
CoreInputView Keine
CoreWindowResizeManager Keine
DisplayEnhancementOverride Keine
EdgeGesture Keine
GazeInputSourcePreview Keine
HdmiDisplayInformation Keine
HolographicKeyboardPlacementOverridePreview Keine
KeyboardDeliveryInterceptor Keine
LockApplicationHost Keine
MouseDevice Keine
PointerVisualizationSettings Keine
ProtectionPolicyManager Keine
SearchPane Keine
SettingsPane Keine
SystemNavigationManager Keine
SystemNavigationManagerPreview Keine
WebAuthenticationBroker Keine. Weitere Details finden Sie im GitHub-Problem WebAuthenticationBroker.AuthenticateAsync throws COMException (WebAuthenticationBroker.AuthenticateAsync löst COMException aus).

Klassen, die „IInitializeWithWindow“ implementieren

Bestimmte Auswahlsteuerelemente, Popups, Dialogfelder und andere WinRT-Objekte (Windows-Runtime) sind von einem CoreWindow-Element abhängig. In der Regel wird eine Benutzeroberfläche (UI) angezeigt. CoreWindow wird in Desktop-Apps zwar nicht unterstützt (siehe Nicht unterstützte Core-Klassen weiter oben), Sie können aber dennoch viele dieser WinRT-Klassen in Ihrer Desktop-App verwenden, indem Sie ein wenig Interoperationscode hinzufügen.

Weitere Informationen (einschließlich einer Liste der betroffenen Typen) und Codebeispiele finden Sie unter Anzeigen von WinRT UI-Objekten, die von CoreWindow abhängig sind.

Nicht unterstützte Member

In diesem Abschnitt werden bestimmte Member von WinRT-Klassen aufgeführt (oder beschrieben, wenn keine umfassende Liste verfügbar ist), die nicht für die Verwendung in Desktop-Apps unterstützt werden. Sofern nicht anders angegeben, werden die restlichen Klassen mit Ausnahme dieser Member in Desktop-Apps unterstützt.

Ereignisse

Die folgenden Klassen werden in Desktop-Apps mit Ausnahme der angegebenen Ereignisse unterstützt.

Class Nicht unterstützte Ereignisse
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Methoden

Die folgenden Klassen werden in Desktop-Apps mit Ausnahme der angegebenen Methoden unterstützt.

Klasse Nicht unterstützte Methoden
DeviceInformationPairing PairAsync

Methoden, die das Request-Benennungsmuster verwenden

Die meisten Methoden, die dem Request-Benennungsmuster folgen, z. B. AppCapability.RequestAccessAsync und StoreContext.RequestPurchaseAsync, werden in Desktop-Apps nicht unterstützt. Intern verwenden diese Methoden die Klasse Windows.UI.Popups. Diese Klasse erfordert, dass der Thread über ein CoreWindow-Objekt verfügt, was in Desktop-Apps nicht unterstützt wird.

Die vollständige Liste der Methoden, die dem Request-Benennungsmuster folgen, ist sehr lang, und dieser Artikel enthält keine vollständige Liste dieser Methoden.

APIs, für die Paketidentität benötigt wird

Die folgenden WinRT-Klassen erfordern die Paketidentität (siehe Features, die eine Paketidentität erfordern). Diese APIs werden nur in Desktop-Apps unterstützt, die verpackt sind (d. h. die zur Laufzeit über Paketidentitäten verfügen). Die Liste ist möglicherweise nicht vollständig.

Wenn sie von einer Desktop-App aufgerufen werden, die keine Paketidentität aufweist, unterstützen die AdaptiveMediaSource.CreateFromUriAsync-Methoden nicht die URI-Formate ms-appx und ms-resource.