Compatibilidad con las API de Windows Runtime en aplicaciones de escritorio

Aunque puede usar la mayoría de las APIs de Windows Runtime (WinRT) (consulte Windows Runtime (WinRT) espacios de nombres) en su aplicación de escritorio de C# o C++, hay dos conjuntos principales de APIs de WinRT que no se admiten para aplicaciones de escritorio, o que presentan restricciones:

  • API que tienen dependencias de características de interfaz de usuario (UI) diseñadas para su uso solo en una aplicación de Plataforma universal de Windows (UWP).
  • API que requieren la identidad del paquete (consulte Características que requieren la identidad del paquete). Tales API se admiten solo en aplicaciones de escritorio que se empaquetan mediante MSIX.

En este artículo se proporcionan detalles sobre estos dos conjuntos de API de WinRT. Cuando están disponibles, en este artículo se sugieren API alternativas para lograr la misma funcionalidad que con las API que no se admiten en aplicaciones de escritorio. La mayoría de las API alternativas están disponibles en WinUI 3 o a través de interfaces COM de WinRT que están disponibles en Windows SDK.

Nota:

Las aplicaciones que usan .NET pueden usar implementaciones de clases proporcionadas para algunas de las interfaces COM de WinRT enumeradas en este artículo. Resulta más fácil trabajar con estas clases que usar directamente las interfaces COM de WinRT. Para obtener más información sobre las implementaciones de clases disponibles, consulte Llamada a las API de interoperabilidad desde una aplicación con .NET. Tenga en cuenta que estas clases requieren el SDK de .NET 6 o versiones posteriores.

API que dependen de características de interfaz de usuario exclusivas de UWP

Algunas API de WinRT se diseñaron específicamente para escenarios de interfaz de usuario en aplicaciones para UWP. Esas API no se comportan correctamente en las aplicaciones de escritorio debido al modelo de subprocesos y a otras diferencias de la plataforma. Esas API, y otras API de WinRT que tienen dependencias, no se pueden usar en aplicaciones de escritorio.

Clases esenciales sin soporte

Estas clases de WinRT no se admiten en aplicaciones de escritorio:

Class API alternativas
ApplicationView Ninguno
CoreApplicationView Use la clase Window proporcionada por WinUI en su lugar.
CoreApplicationViewTitleBar En lugar de la propiedad ExtendViewIntoTitleBar , use la propiedad Window.ExtendsContentIntoTitleBar proporcionada por WinUI.
CoreDispatcher Use la propiedad Microsoft.UI.Xaml.Window.DispatcherQueue proporcionada por WinUI en su lugar.

Tenga en cuenta que las propiedades Windows.UI.Xaml.Window.Dispatcher y Windows.UI.Xaml.DependencyObject.Dispatcher devuelven null en las aplicaciones de escritorio.
CoreWindow Consulte también la sección Clases que implementan IInitializeWithWindow a continuación.

En lugar del método GetKeyState , use el método InputKeyboardSource.GetKeyStateForCurrentThread proporcionado por WinUI.

En lugar de la propiedad PointerCursor , use la propiedad UIElement.ProtectedCursor proporcionada por WinUI. Deberá tener una subclase de UIElement para obtener acceso a esta propiedad.
UserActivity Use la interfaz COM IUserActivitySourceHostInterop en su lugar (en useractivityinterop.h).

Para ver otras API de WinRT que no se admiten en aplicaciones de escritorio, consulte Miembros no admitidos más adelante en este tema.

Clases con un método XxxForCurrentView

Muchas clases de WinRT tienen un método GetForCurrentView o CreateForCurrentView estático, como UIViewSettings.GetForCurrentView. Esos métodos XxxForCurrentView tienen una dependencia implícita del tipo ApplicationView, que no se admite en las aplicaciones de escritorio. Dado que ApplicationView no se admite en aplicaciones de escritorio, tampoco se admite ninguno de los métodos XxxForCurrentView. Algunos métodos XxxForCurrentView no admitidos no solo devolverán null, sino también excepciones.

Nota:

CoreInputView.GetForCurrentViewse admite en aplicaciones de escritorio y se puede usar incluso sin CoreWindow. Este método se puede usar para obtener un objeto CoreInputView en cualquier subproceso y, si ese subproceso tiene una ventana en primer plano, el objeto devolverá eventos.

Las siguientes clases se admiten en aplicaciones de escritorio, pero para recuperar una instancia en una aplicación de escritorio, se usa un mecanismo diferente de los métodos GetForCurrentView o CreateForCurrentView. En el caso de las clases que aparecen a continuación y que tienen una interfaz COM como API alternativa, los desarrolladores de C# también pueden consumir esas interfaces COM de WinRT (véase Llamada a las API de interoperabilidad desde una aplicación con .NET). Es posible que la lista no esté completa.

Class API alternativas
AccountsSettingsPane En su lugar, use la interfaz COM IAccountsSettingsPaneInterop (en accountssettingspaneinterop.h).
CoreDragDropManager En su lugar, use la interfaz COM IDragDropManagerInterop (en dragdropinterop.h).
CoreTextServicesManager Actualmente, esta clase solo se admite en aplicaciones de escritorio en compilaciones preliminares de Windows Insider.
DataTransferManager En su lugar, use la interfaz COM IDataTransferManagerInterop (en shobjidl_core.h).
DisplayInformation Para recuperar una instancia de DisplayInformation, use la interfaz IDisplayInformationStaticsInterop.

Como alternativa, en lugar de la propiedad LogicalDpi , puedes usar la propiedad XamlRoot.RasterizationScale y escuchar los cambios a través del evento XamlRoot.Changed (la propiedad XamlRoot.RasterizationScale se proporciona en WinUI).

Y, en lugar de la propiedad RawPixelsPerViewPixel , tienes la opción de usar la propiedad XamlRoot.RasterizationScale proporcionada por WinUI.
InputPane En su lugar, use la interfaz COM IInputPaneInterop (en inputpaneinterop.h).
PlayToManager En su lugar, use la interfaz COM IPlayToManagerInterop (en playtomanagerinterop.h).
Print3DManager En su lugar, use la interfaz COM IPrinting3DManagerInterop (en print3dmanagerinterop.h).
PrintManager En su lugar, use la interfaz COM PrintManagerInterop (en printmanagerinterop.h).
RadialController En su lugar, use la interfaz COM IRadialControllerInterop (en radialcontrollerinterop.h).
RadialControllerConfiguration En su lugar, use la interfaz COM IRadialControllerConfigurationInterop (en radialcontrollerinterop.h).
ResourceContext Consulte la migración de MRT a MRT Core.
ResourceLoader Consulte la migración de MRT a MRT Core.
SpatialInteractionManager En su lugar, use la interfaz COM ISpatialInteractionManagerInterop (en spatialinteractionmanagerinterop.h).
SystemMediaTransportControls En su lugar, use la interfaz COM ISystemMediaTransportControlsInterop (en systemmediatransportcontrolsinterop.h).
UserActivityRequestManager En su lugar, use la interfaz COM IUserActivityRequestManagerInterop (en useractivityinterop.h).
UIViewSettings En su lugar, use la interfaz COM IUIViewSettingsInterop (en uiviewsettingsinterop.h).

Las siguientes clases no se admiten en aplicaciones de escritorio porque las API no proporcionan una alternativa a su método GetForCurrentView o CreateForCurrentView. Es posible que la lista no esté completa.

Class API alternativas
AppCapture Ninguno
BrightnessOverride Ninguno
ConnectedAnimationService Ninguno
CoreInputView Ninguno
CoreWindowResizeManager Ninguno
DisplayEnhancementOverride Ninguno
EdgeGesture Ninguno
GazeInputSourcePreview Ninguno
HdmiDisplayInformation Ninguno
HolographicKeyboardPlacementOverridePreview Ninguno
KeyboardDeliveryInterceptor Ninguno
LockApplicationHost Ninguno
MouseDevice Ninguno
PointerVisualizationSettings Ninguno
ProtectionPolicyManager Ninguno
SearchPane Ninguno
SettingsPane Ninguno
SystemNavigationManager Ninguno
SystemNavigationManagerPreview Ninguno
WebAuthenticationBroker Ninguna. para obtener más información, consulte el problema de GitHub WebAuthenticationBroker.AuthenticateAsync lanza COMException.

Clases que implementan IInitializeWithWindow

Algunos selectores, elementos emergentes, diálogos y otros objetos de Windows Runtime (WinRT) dependen de un CoreWindow; normalmente, para mostrar una interfaz de usuario. Aunque CoreWindow no se admite en aplicaciones de escritorio (consulte Clases principales no admitidas anteriormente), puede seguir usando muchas de esas clases de WinRT en la aplicación de escritorio tras agregar algo de código de interoperación.

Para obtener más información (incluida una lista de tipos afectados) y ejemplos de código, consulte Visualización de objetos de la interfaz de usuario de WinRT que dependen de CoreWindow.

Miembros no admitidos

En esta sección se enumeran (o describen, si no es posible ofrecer una lista completa) miembros específicos de clases de WinRT que no se pueden usar en aplicaciones de escritorio. A menos que se indique lo contrario, todas las demás clases, aparte de estos miembros, son compatibles con las aplicaciones de escritorio.

Events

Las siguientes clases se admiten en las aplicaciones de escritorio, excepto para los eventos especificados.

Class Eventos no compatibles
UISettings ColorValuesChanged
Configuración de accesibilidad HighContrastChanged

Methods

Las siguientes clases se admiten en apps de escritorio, excepto para los métodos especificados.

Class Métodos no soportados
DeviceInformationPairing PairAsync

Métodos que usan el patrón de nomenclatura "Request"

La mayoría de los métodos que siguen el patrón de nomenclatura Request, como AppCapability.RequestAccessAsync y StoreContext.RequestPurchaseAsync, no se admiten en las aplicaciones de escritorio. Internamente, estos métodos usan la clase Windows.UI.Popups. Esa clase requiere que el subproceso tenga un objeto CoreWindow que no se admite en las aplicaciones de escritorio.

La lista completa de métodos que siguen el patrón de nomenclatura Request es muy larga y este artículo no proporciona una lista completa de estos métodos.

API que requieren la identidad del paquete

Las siguientes clases de WinRT requieren una identidad del paquete (consulte Características que requieren una identidad del paquete). Estas API solo se admiten en aplicaciones de escritorio empaquetadas (es decir, que tienen identidad del paquete en tiempo de ejecución). Es posible que la lista no esté completa.

Windows. ApplicationModel...

Windows.Data...

Windows. Dispositivos...

Windows. Fundación...

Windows. Globalización...

Windows.Gráficos

Windows.Management...

Windows.Media

Windows.Networking...

Windows.Services.Maps...

Importante

Las API de la plataforma Mapas de Windows (Windows. Services.Maps.*) están en desuso y es posible que no estén disponibles en versiones futuras de Windows. Para obtener más información, consulte Recursos para características en desuso.

Windows.Services.Store...

Windows. Almacenamiento...

Windows. Sistema...

Windows. Interfaz de usuario...

Además, cuando se llama desde una aplicación de escritorio que no tiene identidad del paquete, los métodos AdaptiveMediaSource.CreateFromUriAsync no admiten los formatos de URI ms-appx y ms-resource.

  • Last updated on