Unterstützung für Windows-Runtime-APIs in Desktop-Apps

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

  • 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 verfügbar, die im Windows SDK verfügbar sind.

Note

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.

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 Die alternativen APIs
ApplicationView Nichts
CoreApplicationView Verwenden Sie stattdessen die von WinUI bereitgestellte Window-Klasse .
CoreApplicationViewTitleBar Verwenden Sie anstelle der ExtendViewIntoTitleBar-Eigenschaft die von WinUI bereitgestellte Window.ExtendContentIntoTitleBar-Eigenschaft .
CoreDispatcher Verwenden Sie stattdessen die von WinUI bereitgestellte Microsoft.UI.Xaml.Window.DispatcherQueue-Eigenschaft .

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 GetKeyState-Methode die von WinUI bereitgestellte InputKeyboardSource.GetKeyStateForCurrentThread-Methode .

Verwenden Sie anstelle der PointerCursor-Eigenschaft die von WinUI bereitgestellte UIElement.ProtectedCursor-Eigenschaft . 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.

Note

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 Die alternativen 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 LogicalDpi-Eigenschaft die XamlRoot.RasterizationScale-Eigenschaft verwenden und änderungen über das XamlRoot.Changed-Ereignis überwachen (die XamlRoot.RasterizationScale-Eigenschaft wird in WinUI bereitgestellt).

Und anstelle der RawPixelsPerViewPixel-Eigenschaft haben Sie die Möglichkeit, die xamlRoot.RasterizationScale-Eigenschaft zu verwenden, die von WinUI bereitgestellt wird.
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 Die alternativen APIs
AppCapture Nichts
BrightnessOverride Nichts
ConnectedAnimationService Nichts
CoreInputView Nichts
CoreWindowResizeManager Nichts
DisplayEnhancementOverride Nichts
EdgeGesture Nichts
GazeInputSourcePreview Nichts
HdmiDisplayInformation Nichts
HolographicKeyboardPlacementOverridePreview Nichts
KeyboardDeliveryInterceptor Nichts
LockApplicationHost Nichts
MouseDevice Nichts
Zeigervisualisierungseinstellungen Nichts
ProtectionPolicyManager Nichts
SearchPane Nichts
SettingsPane Nichts
SystemNavigationManager Nichts
SystemNavigationManagerPreview Nichts
WebAuthenticationBroker Keiner. Weitere Details finden Sie im GitHub-Problem WebAuthenticationBroker.AuthenticateAsync throws COMException (WebAuthenticationBroker.AuthenticateAsync löst COMException aus).

Klassen, die „IInitializeWithWindow“ implementieren

Bestimmte Auswahlelemente, Popups, Dialogfelder und andere Windows-Runtime (WinRT)-Objekte hängen von einer CoreWindow; normalerweise zum Anzeigen einer Benutzeroberfläche ab. 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 Mitglieder

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 alle anderen Klassen außer diesen Mitgliedern in Desktop-Apps unterstützt.

Events

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

Class Nicht unterstützte Ereignisse
UISettings FarbwerteGeändert
AccessibilitySettings HighContrastChanged

Methodik

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

Class Nicht unterstützte Methoden
Geräteinformationskopplung 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.

Windows. ApplicationModel...

Windows.Data

Windows. Geräte...

Windows. Foundation...

Windows. Globalisierung...

Windows.Graphics...

Windows. Management...

Windows.Media

Windows.Networking...

Windows.Services.Maps...

Von Bedeutung

Die Windows-Karten Plattform-APIs (Windows. Services.Maps.*) sind veraltet und sind in zukünftigen Versionen von Windows möglicherweise nicht verfügbar. Weitere Informationen finden Sie unter Ressourcen für veraltete Funktionen.

Windows.Services.Store...

Windows. Speicher...

Windows.System...

Windows.UI...

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.

  • Last updated on