Hospedaje de controles XAML de WinRT en aplicaciones de escritorio (islas XAML)

A partir de Windows 10, versión 1903, puede hospedar controles XAML de WinRT en aplicaciones de escritorio que no son para UWP mediante una característica denominada islas XAML. Esta característica le permite mejorar el aspecto y la funcionalidad de las aplicaciones de WPF, Windows Forms y de C++ de escritorio (Win32) existentes, con las características más recientes de la UI de Windows 10 que solo están disponibles a través de controles XAML de WinRT. Esto significa que puede usar características de UWP como Windows Ink y controles que admiten el Sistema Fluent Design en las aplicaciones de WPF, Windows Forms y C++ de escritorio existentes.

Puede hospedar cualquier control XAML de WinRT que se derive de Windows.UI.Xaml.UIElement, incluido:

  • Cualquier control XAML de WinRT de origen proporcionado por la biblioteca de Windows SDK o WinUI 2.
  • Cualquier control XAML personalizado de WinRT (por ejemplo, un control de usuario que conste de varios controles XAML de WinRT que funcionen conjuntamente). Debes tener el código fuente del control personalizado para poder compilarlo con la aplicación.

Fundamentalmente, las islas XAML se crean mediante la API de hospedaje XAML de WinRT. Esta API consta de varias clases de Windows Runtime e interfaces COM que se introdujeron en el SDK de Windows 10, versión 1903. También proporcionamos un conjunto de controles .NET de las islas XAML en el kit de herramientas de la Comunidad Windows que usan internamente la API de hospedaje XAML de WinRT y proporcionan una experiencia de desarrollo más cómoda para las aplicaciones de WPF y Windows Forms.

La forma de usar las islas XAML depende del tipo de aplicación y de los tipos de controles XAML de WinRT que quiera hospedar.

Nota

Si tienes comentarios sobre las islas XAML, crea un nuevo problema en el repositorio de Microsoft.Toolkit.Win32 y deja los comentarios allí.

Requisitos

Las islas XAML tienen estos requisitos de tiempo de ejecución:

Aplicaciones de WPF y Windows Forms

Nota

El uso de islas XAML para hospedar controles XAML de WinRT en las aplicaciones de WPF y Windows Forms que tienen como destino .NET Core 3.x. Las islas XAML todavía no se admiten en aplicaciones destinadas a .NET 5 o en aplicaciones de cualquier versión de .NET Framework.

Se recomienda que las aplicaciones de WPF y Windows Forms usen los controles .NET de las islas XAML que están disponibles en el kit de herramientas de la Comunidad Windows. Estos controles ofrecen un modelo de objetos que imita (o proporciona acceso a) las propiedades, los métodos y los eventos de los controles XAML de WinRT correspondientes. También controlan el comportamiento, como la navegación con el teclado y los cambios de diseño.

Hay dos conjuntos de controles de islas XAML para aplicaciones de WPF y Windows Forms: controles encapsulados y controles host.

Controles encapsulados

Las aplicaciones de WPF y Windows Forms pueden utilizar una selección de controles de islas XAML que encapsulan la interfaz y la funcionalidad de un control de UWP específico. Puedes agregar estos controles directamente en la superficie de diseño de tu proyecto de WPF o Windows Forms y, luego, usarlos como cualquier otro control de WPF o Windows Forms en el diseñador.

Los siguientes controles XAML encapsulados de WinRT están disponibles actualmente en el kit de herramientas de la Comunidad Windows.

Control Sistema operativo mínimo compatible Descripción
InkCanvas
InkToolbar
Windows 10, versión 1903 Proporciona una superficie y barras de herramientas relacionadas para la interacción del usuario basada en Windows Ink en la aplicación de escritorio de Windows Forms o WPF.
MediaPlayerElement Windows 10, versión 1903 Incrusta una vista que transmite y representa contenido multimedia, como vídeo, en la aplicación de escritorio de Windows Forms o WPF.
MapControl Windows 10, versión 1903 Te permite mostrar un mapa simbólico o fotorrealista en la aplicación de escritorio de Windows Forms o WPF.

Para ver un tutorial que muestra cómo usar los controles encapsulados XAML encapsulados de WinRT, consulte Hospedaje de un control XAML estándar de WinRT en una aplicación de WPF.

Controles host

En el caso de controles personalizados y otros escenarios más allá de los cubiertos por los controles encapsulados disponibles, las aplicaciones de WPF y Windows Forms también pueden usar el control WindowsXamlHost que está disponible en el kit de herramientas de la Comunidad Windows.

Control Sistema operativo mínimo compatible Descripción
WindowsXamlHost Windows 10, versión 1903 Puede hospedar cualquier control XAML de WinRT que se derive de Windows.UI.Xaml.UIElement, incluido cualquier control XAML de WinRT de origen proporcionado por Windows SDK, así como controles personalizados.

Para ver tutoriales que muestran cómo usar el control WindowsXamlHost, consulte Hospedaje de un control XAML estándar de WinRT en una aplicación de WPF y Hospedaje de un control XAML personalizado de WinRT en una aplicación de WPF mediante islas XAML.

Configuración del proyecto para usar los controles .NET de las islas XAML

Los controles .NET de las islas XAML requieren Windows 10, versión 1903, o una versión posterior. Para usar estos controles, instala uno de los paquetes NuGet que se enumeran a continuación. Estos paquetes ofrecen todo lo necesario para usar los controles encapsulados y los controles host de las islas XAML, e incluyen otros paquetes NuGet relacionados que también son necesarios.

Tipo de control Paquete NuGet Artículos relacionados
Controles encapsulados Versión 6.0.0 o posterior de estos paquetes: Hospedaje de un control XAML estándar de WinRT en una aplicación de WPF
Control host Versión 6.0.0 o posterior de estos paquetes: Hospedaje de un control XAML estándar de WinRT en una aplicación de WPF
Hospedaje de un control XAML personalizado de WinRT en una aplicación de WPF

Ten en cuenta lo siguiente:

  • Los paquetes de controles host también se incluyen en los paquetes de controles encapsulados. Puedes instalar los paquetes de controles encapsulados si quieres usar ambos conjuntos de controles.

  • Si va a hospedar un control XAML personalizado de WinRT, también tendrá que seguir algunos pasos adicionales para hacer referencia al control personalizado. Para obtener más información, consulte Hospedaje de un control XAML personalizado de WinRT en una aplicación WPF mediante islas XAML.

Controles de vista web

El kit de herramientas de la Comunidad Windows también proporciona los siguientes controles .NET para hospedar contenido web en aplicaciones de WPF y Windows Forms. Estos controles se usan a menudo en escenarios similares de modernización de aplicaciones de escritorio que los controles de las islas XAML, y se mantienen en el mismo repositorio de Microsoft.Toolkit.Win32 que los controles de las islas XAML.

Control Sistema operativo mínimo compatible Descripción
WebView Windows 10, versión 1803 Usa el motor de representación de Microsoft Edge para mostrar el contenido web.
WebViewCompatible Windows 7 Proporciona una versión de WebView compatible con más versiones de sistemas operativos. Este control usa el motor de representación de Microsoft Edge para mostrar el contenido web en Windows 10, versión 1803, y versiones posteriores, y el motor de representación de Internet Explorer para mostrar el contenido web en versiones anteriores de Windows 10, Windows 8.x y Windows 7.

Para usar estos controles, instala uno de los paquetes NuGet siguientes:

Aplicaciones de C++ de escritorio (Win32)

Los controles .NET de las islas XAML no se admiten en aplicaciones de C++ de escritorio. En su lugar, estas aplicaciones deben usar la API de hospedaje XAML de WinRT proporcionada por el SDK de Windows 10 (versión 1903 y posterior).

La API de hospedaje XAML de WinRT consta de varias clases de Windows Runtime e interfaces COM que la aplicación de C++ de escritorio puede usar para hospedar cualquier control XAML de WinRT que derive de Windows.UI.Xaml.UIElement. Puede hospedar controles XAML de WinRT en cualquier elemento de UI de la aplicación, que tenga un identificador de ventana asociado (HWND). Para más información sobre esta API, consulta los artículos siguientes.

Nota

Los controles encapsulados y los controles host del kit de herramientas de la Comunidad Windows usan la API de hospedaje XAML de WinRT internamente, e implementan todo el comportamiento que, de lo contrario, tendría que controlar usted mismo si usara la API de hospedaje XAML de WinRT directamente, incluida la navegación con el teclado y los cambios de diseño. En el caso de las aplicaciones de WPF y Windows Forms, se recomienda encarecidamente usar estos controles en lugar de la API de hospedaje XAML de WinRT directamente, ya que abstraen muchos de los detalles de implementación del uso de la API.

Arquitectura de las islas XAML

A continuación se muestra una visión rápida de cómo los distintos tipos de controles de las islas XAML se organizan arquitectónicamente sobre la API de hospedaje XAML de WinRT.

Arquitectura de los controles host

Las API que aparecen en la parte inferior de este diagrama se incluye con el Windows SDK. Los controles encapsulados y los controles host están disponibles a través de paquetes NuGet en el kit de herramientas de la Comunidad Windows.

Limitaciones y soluciones alternativas

En las secciones siguientes se describen las limitaciones y las soluciones alternativas para ciertos escenarios de desarrollo de UWP en aplicaciones de escritorio que usan islas XAML.

Compatible solo con soluciones alternativas

✔️ El hospedaje de controles de la biblioteca WinUI 2 en una isla XAML se admite de forma condicional en la versión actual de las islas XAML. Si la aplicación de escritorio usa un paquete MSIX para la implementación, puedes hospedar controles de WinUI de versiones preliminares o de lanzamiento del paquete NuGet Microsoft.UI.Xaml. Si la aplicación de escritorio no está empaquetada con MSIX, puedes hospedar controles de WinUI solo si instalas una versión preliminar del paquete NuGet Microsoft.UI.Xaml. La compatibilidad con el hospedaje de controles desde la biblioteca WinUI 3.0 está disponible en una versión posterior.

✔️ Para acceder al elemento raíz de un árbol de contenido XAML en una isla XAML y obtener la información relacionada sobre el contexto en el que se hospeda, no uses las clasesCoreWindow, ApplicationView y Window. En su lugar, usa la clase XamlRoot. Para obtener más información, consulta esta sección.

✔️ para admitir el Contrato para contenido compartido desde una aplicación de WPF, Windows Forms o C++ de escritorio (Win32), la aplicación tiene que usar la interfaz IDataTransferManagerInterop para obtener el objeto DataTransferManager para iniciar la operación de uso compartido para una ventana específica. Para obtener un ejemplo que muestra cómo usar esta interfaz en una aplicación de WPF, consulta el ejemplo de ShareSource.

✔️ No se admite el uso de x:Bind con controles hospedados en islas XAML. Tendrás que declarar el modelo de datos en una biblioteca de .NET Standard.

Incompatible

🚫 Usar islas XAML en aplicaciones de WPF y Windows Forms destinadas a .NET Framework. Las islas XAML solo se admiten en aplicaciones destinadas a .NET Core 3.x.

🚫 El contenido XAML de UWP en las islas XAML no responde a los cambios de tema de Windows de oscuro a claro, ni viceversa, en tiempo de ejecución. El contenido responde a los cambios de contraste alto en tiempo de ejecución.

🚫 Agregar un control WebView a un control de usuario personalizado (en subproceso, fuera de subproceso o fuera de proceso).

🚫 En el modo de pantalla completa no se admiten el control MediaPlayer y el control de host MediaPlayerElement.

🚫 Entrada de texto con la vista de escritura a mano. Para más información sobre esta característica, consulta este artículo.

🚫 Controles de texto que usan vínculos de contenido @Places y @People. Para más información sobre esta característica, consulta este artículo.

🚫 Las islas XAML no admiten el hospedaje de un elemento ContentDialog que contiene un control que acepta entrada de texto, como TextBox, RichEditBox o AutoSuggestBox. Si lo hace, el control de entrada no responderá correctamente a las pulsaciones de teclas. Para lograr una funcionalidad similar con una isla XAML, se recomienda hospedar un elemento Popup que contenga el control de entrada.

🚫 Las islas XAML no admiten actualmente la visualización de archivos SVG en un control Windows.UI.Xaml.Controls.Image hospedado ni mediante un objeto Windows.UI.Xaml.Media.Imaging.SvgImageSource. Como alternativa, convierte los archivos de imagen que quieras mostrar en formatos basados en tramas como JPG o PNG.

Contexto de hosts de ventanas para islas XAML

Al hospedar islas XAML en una aplicación de escritorio, puedes tener varios árboles de contenido XAML que se ejecuten en el mismo subproceso a la vez. Para acceder al elemento raíz de un árbol de contenido XAML en una isla XAML y obtener la información relacionada sobre el contexto en el que se hospeda, usa la clase XamlRoot. Las clases CoreWindow, ApplicationView y Window no proporcionan la información correcta para las islas XAML. Los objetos CoreWindow y Window existen en el subproceso, y la aplicación puede acceder a ellos, pero no devolverán límites ni visibilidad significativos (son siempre invisibles y tienen un tamaño de 1×1). Para más información, consulta Hosts de ventanas.

Por ejemplo, para obtener el rectángulo delimitador de la ventana que contiene un control XAML de WinRT que se hospeda en una isla XAML, use la propiedad XamlRoot.Size del control. Dado que todos los controles XAML de WinRT que se pueden hospedar en una isla XAML derivan de Windows.UI.Xaml.UIElement, puede usar la propiedad XamlRoot del control para acceder al objeto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

No uses la propiedad CoreWindows.Bounds para obtener el rectángulo delimitador.

// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

Para obtener una tabla de las API comunes relacionadas con ventanas que debes evitar en el contexto de las islas XAML y los reemplazos de XamlRoot recomendados, consulta la tabla de esta sección.

Para obtener un ejemplo que muestra cómo usar esta interfaz en una aplicación de WPF, consulta el ejemplo de ShareSource.

Recursos adicionales

Para obtener información general y tutoriales sobre el uso de las islas XAML, consulta los siguientes artículos y recursos:

  • Tutorial de modernización de una aplicación de WPF: En este tutorial se proporcionan instrucciones paso a paso para usar los controles encapsulados y hospedar controles en el kit de herramientas de la Comunidad Windows para agregar controles XAML de WinRT a una aplicación de línea de negocio de WPF existente. En este tutorial se incluye el código completo de la aplicación de WPF, así como instrucciones detalladas para cada paso del proceso.
  • Ejemplos de código de las islas XAML: en este repositorio se incluyen ejemplos de Windows Forms, WPF y C++ de escritorio (Win32) que muestran cómo utilizar las islas XAML.
  • Islas XAML v1, actualizaciones y hoja de ruta: En esta entrada de blog se describen muchas preguntas comunes sobre las islas XAML, y se proporciona una hoja de ruta de desarrollo detallada.