Las API de Windows Runtime no se admiten en aplicaciones de escritorio

  • Artículo

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

  • API que tienen dependencias en las características de la interfaz de usuario (UI) que se diseñaron para usarlas solo en una aplicación de la 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 mediante interfaces COM de WinRT disponibles en Windows SDK.

Nota

Las aplicaciones que usan .NET pueden usar las implementaciones de clase proporcionadas para algunas de las interfaces COM de WinRT que se enumeran 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.

Este artículo se actualizará a medida que se identifiquen más soluciones alternativas y reemplazos. Si tiene algún problema con una API que no aparece aquí, cree una nota de problema en el repositorio microsoft-ui-xaml que tenga el nombre de la API y proporcione detalles sobre lo que intenta lograr al usarla.

API que tienen dependencias en las características de la interfaz de usuario solo para 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 principales no admitidas

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

Clase API alternativas
ApplicationView None
CoreApplicationView En su lugar, use la clase Windows que proporciona WinUI 3.
CoreApplicationViewTitleBar En lugar de la propiedad ExtendViewIntoTitleBar, use la propiedad Window.ExtendsContentIntoTitleBar que proporciona WinUI 3.
CoreDispatcher En su lugar, use la propiedad Microsoft.UI.Xaml.Window.DispatcherQueue que proporciona WinUI 3.

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 que proporciona WinUI 3.

En lugar de la propiedad PointerCursor, use la propiedad UIElement.ProtectedCursor que proporciona WinUI 3. 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.

Clase 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.

Igualmente, en lugar de la propiedad LogicalDpi, puede usar la propiedad XamlRoot.RasterizationScale y escuchar los cambios en el evento XamlRoot.Changed (la propiedad XamlRoot.RasterizationScale se proporciona en WinUI 3).

En lugar de la propiedad RawPixelsPerViewPixel, tiene la opción de usar la propiedad XamlRoot.RasterizationScale que proporciona WinUI 3.
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 Migración de MRT a MRT Core.
ResourceLoader Consulte 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.

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

Clases que implementan IInitializeWithWindow

Ciertos selectores, elementos emergentes, cuadros de diálogo y otros objetos de Windows Runtime (WinRT) dependen de una instancia de 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, el resto de las clases aparte de estos miembros se admiten en aplicaciones de escritorio.

Events

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

Clase Eventos no admitidos
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Métodos

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

Clase Miembros no admitidos
DeviceInformationPairing PairAsync

Métodos que usan el patrón de nomenclatura de solicitud

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.

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.