Uso de la API de hospedaje XAML para UWP

Importante

En este tema se usan o mencionan tipos del repositorio CommunityToolkit/Microsoft.Toolkit.Win32 GitHub. Para obtener información importante sobre la compatibilidad de Islas XAML para UWP, consulta el aviso de Islas XAML en ese repositorio.

Las aplicaciones de escritorio que no son para UWP (incluidas las aplicaciones de escritorio de C++ (Win32), WPF y Windows Forms pueden usar la API de hospedaje XAML de UWP para hospedar controles XAML de UWP en cualquier elemento de interfaz de usuario asociado a un identificador de ventana (HWND). Para obtener información general sobre esta característica, consulta Hospedar controles XAML para UWP en aplicaciones de escritorio (islas XAML para UWP).

¿La API de hospedaje XAML para UWP es la opción adecuada para la aplicación de escritorio?

La API de hospedaje XAML para UWP proporciona la infraestructura de bajo nivel para hospedar controles XAML de UWP en aplicaciones de escritorio. Algunos tipos de aplicaciones de escritorio tienen la opción de usar API alternativas y más cómodas para lograr este objetivo.

  • Si tienes una aplicación de escritorio de C++ y quieres hospedar controles XAML para UWP en tu aplicación, debes usar la API de hospedaje XAML de UWP. No hay alternativas para estos tipos de aplicaciones.

  • Para aplicaciones de WPF y Windows Forms, te recomendamos encarecidamente usar los controles .NET de XAML Island en Windows Community Toolkit en lugar de usar directamente la API de alojamiento de XAML de UWP. Estos controles usan la API de hospedaje XAML para UWP internamente e implementan todo el comportamiento que de otro modo tendrías que controlarte si usaste la API de hospedaje XAML para UWP directamente, incluidos los cambios de navegación y diseño del teclado.

Como se recomienda que solo las aplicaciones de escritorio de C++ usen la API de hospedaje XAML para UWP, en este artículo se proporcionan principalmente instrucciones y ejemplos para aplicaciones de escritorio de C++. Sin embargo, puedes usar la API de hospedaje XAML de UWP en aplicaciones de WPF y Windows Forms, si eliges. En este artículo, se señala el código fuente pertinente para los controles de alojamiento host para WPF y Windows Forms en el Toolkit de la Comunidad de Windows, para que puedas ver cómo estos controles utilizan la API de hospedaje XAML para UWP.

Obtenga información sobre cómo usar la API de hospedaje XAML

Para seguir instrucciones paso a paso con ejemplos de código para usar la API de hospedaje XAML en aplicaciones de escritorio de C++, consulta estos artículos:

Muestras

La forma en que usas la API de hospedaje XAML para UWP en tu código depende del tipo de aplicación, del diseño de la aplicación y de otros factores. Para ayudar a ilustrar cómo usar esta API en el contexto de una aplicación completa, en este artículo se hace referencia al código de los ejemplos siguientes.

C++ de escritorio (Win32)

En los ejemplos siguientes se muestra cómo usar la API de hospedaje XAML para UWP en una aplicación de escritorio de C++:

  • Ejemplo simple de isla XAML. En este ejemplo se muestra una implementación básica de hospedar un control XAML para UWP en una aplicación de escritorio de C++ sin empaquetar.

  • XAML Island con ejemplo de control personalizado. En este ejemplo se muestra una implementación completa de hospedar un control XAML de UWP personalizado en una aplicación de escritorio de C++ empaquetada, así como controlar otro comportamiento, como la entrada del teclado y la navegación de foco.

WPF y Windows Forms

El control WindowsXamlHost en Windows Community Toolkit sirve como ejemplo de referencia para usar la API de hospedaje XAML de UWP en aplicaciones WPF y Windows Forms. El código fuente está disponible en las siguientes ubicaciones:

Nota:

Recomendamos encarecidamente que uses los controles de .NET XAML Island en Windows Community Toolkit en lugar de usar la API de hospedaje XAML de UWP directamente en aplicaciones WPF y Windows Forms. Los vínculos de ejemplo WPF y Windows Forms de este artículo solo tienen fines ilustrativos.

Arquitectura de la API

La API de hospedaje XAML para UWP incluye estos tipos de Windows Runtime principales e interfaces COM.

Tipo o interfaz Description
WindowsXamlManager Esta clase representa el marco XAML de UWP. Esta clase proporciona un único método InitializeForCurrentThread estático que inicializa el marco XAML de UWP en el subproceso actual de la aplicación de escritorio.
DesktopWindowXamlSource Esta clase representa una instancia de contenido XAML de UWP que hospedas en tu aplicación de escritorio. El miembro más importante de esta clase es la propiedad Content . Asignas esta propiedad a un windows.UI.Xaml.UIElement que quieras hospedar. Esta clase también tiene otros miembros para enrutar la navegación del foco del teclado hacia y hacia fuera de las islas XAML.
IDesktopWindowXamlSourceNative Esta interfaz COM proporciona el método AttachToWindow , que se usa para adjuntar una isla XAML en la aplicación a un elemento primario de la interfaz de usuario. Cada objeto DesktopWindowXamlSource implementa esta interfaz.
IDesktopWindowXamlSourceNative2 Esta interfaz COM proporciona el método PreTranslateMessage , que permite que el marco XAML de UWP procese determinados mensajes de Windows correctamente. Cada objeto DesktopWindowXamlSource implementa esta interfaz.

En el diagrama siguiente se muestra la jerarquía de objetos de una isla XAML hospedada en una aplicación de escritorio.

  • En el nivel base es el elemento de interfaz de usuario de la aplicación donde quieres hospedar la isla XAML. Este elemento de interfaz de usuario debe tener un identificador de ventana (HWND). Algunos ejemplos de elementos de interfaz de usuario en los que puedes hospedar una isla XAML incluyen una window para aplicaciones de escritorio de C++, System.Windows.Interop.HwndHost para aplicaciones de WPF y un System.Windows.Forms.Control para aplicaciones Windows Forms.

  • En el siguiente nivel, es un objeto DesktopWindowXamlSource . Este objeto proporciona la infraestructura para hospedar la isla XAML. El código es responsable de crear este objeto y adjuntarlo al elemento primario de la interfaz de usuario.

  • Al crear un DesktopWindowXamlSource, este objeto crea automáticamente una ventana secundaria nativa para hospedar el control XAML de UWP. Esta ventana secundaria nativa es mayormente abstraída de su código, pero puede acceder a su identificador (HWND) si es necesario.

  • Por último, en el nivel superior es el control XAML de UWP que quieres hospedar en tu aplicación de escritorio. Puede ser cualquier objeto de UWP que derive de Windows. Interfaz de usuario. Xaml.UIElement, incluido cualquier control XAML de UWP proporcionado por el SDK de Windows, así como controles de usuario personalizados.

Arquitectura DesktopWindowXamlSource

Nota:

Al hospedar islas XAML para UWP en una aplicación de escritorio, puedes tener varios árboles de contenido XAML que se ejecuta en el mismo subproceso al mismo tiempo. Para acceder al elemento raíz de un árbol de contenido XAML en una Isla XAML y obtener información relacionada sobre el contexto en el que se aloja, usa la clase XamlRoot. Las API CoreWindow, ApplicationView y Window no proporcionarán la información correcta para las islas XAML de UWP. Para obtener más información, consulta esta sección.

procedimientos recomendados

Al usar la API de hospedaje XAML para UWP, sigue estos procedimientos recomendados para cada subproceso que hospeda controles XAML de UWP:

Solución de problemas

Error al usar la API de hospedaje XAML para UWP en una aplicación para UWP

Cuestión Resolución
La aplicación recibe una excepción COMException con el siguiente mensaje: "No se puede activar DesktopWindowXamlSource. Este tipo no se puede usar en una aplicación para UWP" o "No se puede activar WindowsXamlManager. Este tipo no se puede usar en una aplicación para UWP". Este error indica que estás intentando usar la API de hospedaje XAML de UWP (en concreto, intentas crear instancias de los tipos DesktopWindowXamlSource o WindowsXamlManager ) en una aplicación para UWP. La API de hospedaje XAML para UWP solo está pensada para usarse en aplicaciones de escritorio que no sean para UWP, como WPF, Windows Forms y aplicaciones de escritorio de C++.

Error al intentar usar los tipos WindowsXamlManager o DesktopWindowXamlSource

Cuestión Resolución
La aplicación recibe una excepción con el siguiente mensaje: "WindowsXamlManager y DesktopWindowXamlSource se admiten para aplicaciones destinadas a Windows versión 10.0.18226.0 y posteriores. Compruebe el manifiesto de aplicación o el manifiesto del paquete y asegúrese de que la propiedad MaxTestedVersion está actualizada". Este error indica que la aplicación intentó usar los tipos WindowsXamlManager o DesktopWindowXamlSource en la API de hospedaje XAML de UWP, pero el sistema operativo no puede determinar si la aplicación se creó para tener como destino Windows 10, versión 1903 o posterior. La API de hospedaje XAML para UWP se introdujo por primera vez como versión preliminar en una versión anterior de Windows 10, pero solo se admite a partir de Windows 10, versión 1903.

Para resolver este problema, cree un paquete MSIX para la aplicación y ejecútelo desde el paquete, o instale el paquete nuGet Microsoft.Toolkit.Win32.UI.SDK NuGet en el project.

Error al asociarse a una ventana en un subproceso diferente

Cuestión Resolución
La aplicación recibe una excepción COMException con el siguiente mensaje: "Error en el método AttachToWindow porque se creó el HWND especificado en un subproceso diferente". Este error indica que la aplicación llamó al método IDesktopWindowXamlSourceNative::AttachToWindow y le pasó el HWND de una ventana que se creó en otro subproceso. Debe pasarle a este método el HWND de una ventana que se creó en el mismo subproceso que el código desde el cual está llamando al método.

Error al asociarse a una ventana en otra ventana de nivel superior

Cuestión Resolución
La aplicación recibe una excepción COMException con el siguiente mensaje: "Error en el método AttachToWindow porque el HWND especificado desciende de una ventana de nivel superior diferente a la HWND que se pasó anteriormente a AttachToWindow en el mismo subproceso". Este error indica que la aplicación llamó al método IDesktopWindowXamlSourceNative::AttachToWindow y le pasó el HWND de una ventana que desciende de una ventana de nivel superior diferente a una ventana que especificó en una llamada anterior a este método en el mismo subproceso.

Una vez que la aplicación llama a AttachToWindow en un subproceso determinado, todos los demás objetos DesktopWindowXamlSource del mismo subproceso solo pueden asociarse a ventanas que son descendientes de la misma ventana de nivel superior que se pasó en la primera llamada a AttachToWindow. Cuando todos los objetos DesktopWindowXamlSource están cerrados para un subproceso determinado, el siguiente DesktopWindowXamlSource puede conectarse a cualquier ventana de nuevo.

Para resolver este problema, cierre todos los objetos DesktopWindowXamlSource enlazados a otras ventanas de nivel superior de este subproceso o cree un subproceso para este DesktopWindowXamlSource.
  • Last updated on