Hospedaje de controles XAML de WinRT en aplicaciones de escritorio (islas XAML)
Importante
En este tema se usan o mencionan tipos del repositorio de GitHub CommunityToolkit/Microsoft.Toolkit.Win32. Para obtener información importante sobre la compatibilidad con islas XAML, consulte el Aviso de islas XAML en ese repositorio.
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 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:
- La mayoría de los controles XAML de WinRT propios proporcionados por Windows SDK o la biblioteca de WinUI 2 (consulte las excepciones).
- 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:
- Windows 10, versión 1903, o una versión 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
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 ni 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 XAML encapsulados de WinRT, consulte Uso de islas XAML para hospedar un control XAML para UWP en una aplicación de WPF en C#.
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 Uso de islas XAML para hospedar un control XAML para UWP en una aplicación de WPF en C# 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:
|
Uso de islas XAML para hospedar un control XAML para UWP en una aplicación de WPF en C# |
| Control host | Versión 6.0.0 o posterior de estos paquetes:
|
Uso de islas XAML para hospedar un control XAML para UWP en una aplicación de WPF en C# 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:
- WPF: Microsoft.Toolkit.Wpf.UI.Controls.WebView
- Windows Forms: Microsoft.Toolkit.Forms.UI.Controls.WebView
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.
- Uso de la API de hospedaje XAML de WinRT en una aplicación de C++ de escritorio
- Hospedaje de un control XAML estándar de WinRT en una aplicación de C++ de escritorio
- Hospedaje de un control XAML personalizado de WinRT en una aplicación de C++ de escritorio
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.
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, 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. 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 use 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 escritorio de WPF, Windows Forms o C++ 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.
Adición de un control Windows.UI.Xaml.WebView. Para las aplicaciones de WPF y WinForms, consulte estas alternativas.
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.
