Hospedar controles XAML para UWP en aplicaciones de escritorio (islas XAML de UWP)

A partir de Windows 10, versión 1903, puedes hospedar controles XAML para UWP en aplicaciones de escritorio que no sean para UWP mediante una característica denominada UWP XAML Islands. Esta característica te permite mejorar la apariencia y la funcionalidad de tus aplicaciones existentes de WPF, Windows Forms y escritorio de C++ (Win32) con características de interfaz de usuario de Windows que solo están disponibles a través de controles XAML para UWP. Esto significa que puedes usar características de UWP como Windows Ink y controles que admiten el sistema de diseño Fluent en tus aplicaciones de escritorio existentes WPF, Windows Forms y C++.

Puedes hospedar cualquier control XAML de UWP que derive de Windows. Interfaz de usuario. Xaml.UIElement, entre los que se incluyen:

• La mayoría de los controles XAML de UWP de primera parte proporcionados por el SDK de Windows o la biblioteca WinUI para UWP (ver exceptions).
• Cualquier control XAML de UWP personalizado (por ejemplo, un control de usuario que consta de varios controles XAML para UWP que funcionan juntos). Debes tener el código fuente del control personalizado para poder compilarlo con la aplicación.

Fundamentalmente, las islas XAML para UWP se crean mediante la API de hospedaje XAML de UWP. 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 XAML Island en el Windows Community Toolkit que utilizan internamente la API de hospedaje XAML de UWP y brindan una experiencia de desarrollo más cómoda para aplicaciones WPF y Windows Forms.

La forma en que usas islas XAML para UWP depende del tipo de aplicación y de los tipos de controles XAML de UWP que quieras hospedar.

Requisitos

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

• Windows 10, versión 1903 o posterior.
• Si tu aplicación no está empaquetada en un paquete MSIX para su implementación, el equipo debe tener instalado el Tiempo de ejecución de Visual C++.

aplicaciones de WPF y Windows Forms

Recomendamos que las aplicaciones WPF y Windows Forms utilicen los controles .NET de islas XAML que están disponibles en el Kit de herramientas de la comunidad de Windows. Estos controles proporcionan un modelo de objetos que imita (o proporciona acceso a) las propiedades, métodos y eventos de los controles XAML de UWP 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 isla XAML para aplicaciones de WPF y Windows Forms: controles wrapped y host.

Controles encapsulados

aplicaciones de WPF y Windows Forms pueden usar una selección de controles XAML Island que encapsulan la interfaz y la funcionalidad de un control XAML de UWP específico. Puede agregar estos controles directamente a la superficie de diseño de su proyecto de WPF o Windows Forms y, a continuación, usarlos como cualquier otro control de WPF o Windows Forms en el diseñador.

Los siguientes controles XAML para UWP envueltos están disponibles actualmente en el Windows Community Toolkit.

Para ver un tutorial que muestra cómo usar los controles XAML de UWP ajustados, consulta Use las islas XAML para hospedar un control XAML de UWP en una aplicación de WPF de C#.

Controles del anfitrión

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

Para ver tutoriales que muestran cómo usar el control WindowsXamlHost, consulta Use islas XAML para hospedar un control XAML de UWP en una aplicación de WPF de C# y Hospedar un control XAML de UWP personalizado en una aplicación de WPF mediante islas XAML.

Configura tu proyecto para usar los controles .NET de islas XAML

Los controles .NET de la Isla 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.

Ten en cuenta lo siguiente:

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

• Si vas a hospedar un control XAML de UWP personalizado, también tendrás que realizar algunos pasos adicionales para hacer referencia al control personalizado. Para obtener más información, consulta Alojar un control XAML UWP personalizado en una aplicación WPF usando Islas XAML.

Controles de vista web

El Kit de herramientas de la comunidad de Windows también proporciona los siguientes controles .NET para hospedar contenido web en aplicaciones WPF y Windows Forms. Estos controles se suelen usar en escenarios de modernización de aplicaciones de escritorio similares como los controles de isla XAML y se mantienen en el mismo repositorio de Microsoft.Toolkit.Win32 que los controles de isla XAML.

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

• WPF: Microsoft. Kit de herramientas. Wpf. Interfaz de usuario. Controls.WebView
• Windows Forms: Microsoft. Toolkit.Forms.UI.Controls.WebView

Aplicaciones de C++ de escritorio (Win32)

Los controles .NET de isla XAML no son compatibles en aplicaciones de escritorio de C++. En su lugar, estas aplicaciones deben usar la API de hospedaje XAML UWP proporcionada por el SDK de Windows 10 (versión 1903 y posteriores).

La API de alojamiento XAML de UWP consta de varias clases de Windows Runtime e interfaces COM que tu aplicación de escritorio en C++ puede usar para alojar cualquier control XAML de UWP que derive de Windows.UI.Xaml.UIElement. Puedes hospedar controles XAML para UWP en cualquier elemento de interfaz de usuario 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.

• Uso de la API de hospedaje XAML para UWP en una aplicación de escritorio de C++
• Hospedar un control XAML estándar de UWP en una aplicación de escritorio de C++
• Hospedar un control XAML de UWP personalizado en una aplicación de escritorio de C++

Arquitectura de islas XAML para UWP

Aquí tienes un vistazo rápido sobre la organización de los diferentes tipos de controles XAML Island a nivel arquitectónico sobre la API de hospedaje XAML de UWP.

Las API que aparecen en la parte inferior de este diagrama se incluyen 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 soluciones alternativas para determinados escenarios de desarrollo de UWP en aplicaciones de escritorio que usan islas XAML para UWP.

Compatible solo con soluciones alternativas

✔️ Los controles de hospedaje de la Biblioteca WinUI para UWP en una isla XAML se admiten de forma condicional en la versión actual de UWP XAML Islands. Si la aplicación de escritorio usa un paquete MSIX para la implementación, puede 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, puede hospedar controles de WinUI solo si instala una versión preliminar del paquete NuGet Microsoft.UI.Xaml o si usa la API de dependencias dinámicas.

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

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

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

No está soportado

🚫 Usar islas UWP XAML en aplicaciones WPF y Windows Forms que tienen como objetivo el .NET Framework. Las islas XAML de UWP solo se admiten en aplicaciones destinadas a .NET Core 3.x.

🚫 el contenido XAML de UWP en islas XAML de UWP no responde a los cambios de tema de Windows de oscuro a claro o viceversa durante la ejecución. El contenido responde a los cambios de alto contraste durante la ejecución.

🚫 Adición de un control Windows.UI.Xaml.WebView. Para aplicaciones WPF y WinForms, consulte estas alternativas.

🚫 El control MediaPlayer y el control MediaPlayerElement no se admiten en modo pantalla completa.

🚫 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 para UWP no admiten el hospedaje de un ContentDialog que contiene un control que acepta entrada de texto, por ejemplo, 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 XAML Islands para UWP no admiten actualmente la visualización de archivos SVG en un control Windows.UI.Xaml.Controls.Image hospedado o 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 alojamiento de ventanas para islas XAML

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 clases CoreWindow, ApplicationView y Window no proporcionarán la información correcta para las islas XAML de UWP. 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 UWP hospedado en una isla XAML, usa la propiedad XamlRoot.Size del control. Dado que cada control XAML de UWP que se puede hospedar en una isla XAML deriva de Windows. Interfaz de usuario. Xaml.UIElement, puedes usar la propiedad XamlRoot del control para acceder al objeto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

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

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

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

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

Recursos adicionales

Para obtener más información y tutoriales sobre el uso de islas XAML para UWP, consulta los siguientes artículos y recursos:

• ejemplos de código de UWP XAML Islands: este repositorio contiene ejemplos de Windows Forms, WPF y escritorio de C++ (Win32) que muestran cómo usar islas XAML de UWP.
• Islas XAML de UWP v1: actualizaciones y hoja de ruta: en esta entrada de blog se describen muchas preguntas comunes sobre las islas XAML de UWP y se proporciona una hoja de ruta de desarrollo detallada.