Partilhar via

Hospedar controlos XAML do WinRT em aplicações de ambiente de trabalho (Ilhas XAML)

Importante

Este tópico usa ou menciona tipos do repositório CommunityToolkit/Microsoft.Toolkit.Win32 GitHub. Para informações importantes sobre o suporte a Ilhas XAML, consulte o Aviso de Ilhas XAML nesse repositório.

A partir do Windows 10, versão 1903, é possível hospedar controles XAML WinRT em aplicações de desktop que não sejam UWP, utilizando uma funcionalidade chamada Ilhas XAML . Esse recurso permite que você aprimore a aparência, a sensação e a funcionalidade de seus aplicativos de área de trabalho WPF, Windows Forms e C++ (Win32) existentes com os recursos mais recentes da interface do usuário do Windows que só estão disponíveis por meio de controles WinRT XAML. Isso significa que você pode usar recursos UWP, como o Windows Ink e controles que oferecem suporte ao Fluent Design System em seus aplicativos de desktop WPF, Windows Forms e C++ existentes.

Você pode hospedar qualquer controle WinRT XAML que derive de Windows.UI.Xaml.UIElement , incluindo:

  • A maioria dos controles XAML WinRT primários fornecidos pelo SDK do Windows ou pela biblioteca WinUI 2 (consulte exceções).
  • Qualquer controle XAML WinRT personalizado (por exemplo, um controle de usuário que consiste em vários controles XAML WinRT que trabalham juntos). Você deve ter o código-fonte para o controle personalizado para que você possa compilá-lo com seu aplicativo.

Fundamentalmente, as Ilhas XAML são criadas usando a API de hospedagem XAML do WinRT. Essa API consiste em várias classes do Tempo de Execução do Windows e interfaces COM que foram introduzidas no SDK do Windows 10, versão 1903. Também fornecemos um conjunto de controles .NET da Ilha XAML no do Kit de Ferramentas da Comunidade do Windows que usam a API de hospedagem XAML do WinRT internamente e fornecem uma experiência de desenvolvimento mais conveniente para aplicativos WPF e Windows Forms.

A maneira como você usa Ilhas XAML depende do seu tipo de aplicativo e dos tipos de controles XAML do WinRT que você deseja hospedar.

Observação

Se você tiver comentários sobre Ilhas XAML, crie um novo problema no de repositório Microsoft.Toolkit.Win32 e deixe seus comentários lá.

Requerimentos

As Ilhas XAML têm estes requisitos de tempo de execução:

  • Windows 10, versão 1903 ou uma versão posterior.
  • Se seu aplicativo não estiver empacotado em um pacote MSIX para implantação, o computador deve ter o Visual C++ Runtime instalado.

Aplicativos WPF e Windows Forms

Observação

Atualmente, o uso de ilhas XAML para hospedar controles XAML WinRT em aplicativos WPF e Windows Forms é suportado apenas em aplicativos destinados ao .NET Core 3.x. As Ilhas XAML ainda não são suportadas em aplicativos destinados ao .NET ou em aplicativos que tenham qualquer versão do .NET Framework.

Recomendamos que as aplicações WPF e Windows Forms utilizem os controlos .NET XAML Island disponíveis no Windows Community Toolkit. Esses controles fornecem um modelo de objeto que imita (ou fornece acesso a) as propriedades, métodos e eventos dos controles XAML WinRT correspondentes. Eles também lidam com comportamentos como navegação pelo teclado e alterações de layout.

Há dois conjuntos de controles de Ilha XAML para aplicativos WPF e Windows Forms: controles encapsulados e controles de host.

Controles encapsulados

As aplicações WPF e Windows Forms podem usar uma seleção de controles XAML Island que encapsulam a interface e a funcionalidade de um controle WinRT XAML específico. Você pode adicionar esses controles diretamente à superfície de design do seu projeto WPF ou Windows Forms e, em seguida, usá-los como qualquer outro controle WPF ou Windows Forms no designer.

Os seguintes controles XAML WinRT encapsulados estão atualmente disponíveis no Windows Community Toolkit.

Controlo SO mínimo suportado Descrição
TelaDeTinta
Barra de Ferramentas de Tinta		 Windows 10, versão 1903 Forneça uma superfície e barras de ferramentas relacionadas para interação do usuário baseada no Windows Ink em seu aplicativo de área de trabalho Windows Forms ou WPF.
MediaPlayerElement Windows 10, versão 1903 Incorpora um modo de exibição que transmite e processa conteúdo de mídia, como vídeo, em seu aplicativo de área de trabalho Windows Forms ou WPF.
MapControl Windows 10, versão 1903 Permite que você exiba um mapa simbólico ou fotorrealista em seu aplicativo de área de trabalho Windows Forms ou WPF.

Para obter uma orientação passo a passo que demonstra como usar os controles XAML WinRT encapsulados, consulte Usar XAML Islands para integrar um controlo XAML UWP num aplicativo WPF C#.

Controles do anfitrião

Para controles personalizados e outros cenários além daqueles cobertos pelos controles encapsulados disponíveis, os aplicativos WPF e Windows Forms também podem usar o controle WindowsXamlHost que está disponível no Kit de Ferramentas da Comunidade do Windows.

Controlo SO mínimo suportado Descrição
WindowsXamlHost Windows 10, versão 1903 Pode hospedar qualquer controle WinRT XAML que derive de Windows.UI.Xaml.UIElement, incluindo qualquer controle WinRT XAML primário fornecido pelo SDK do Windows, bem como controles personalizados.

Para obter instruções passo a passo que demonstram como usar o controle WindowsXamlHost, consulte Usar ilhas XAML para hospedar um controle XAML UWP em um aplicativo WPF C# e Hospedar um controle XAML WinRT personalizado em um aplicativo WPF usando Ilhas XAML.

Configure seu projeto para usar os controlos .NET da XAML Island

Os controles .NET da Ilha XAML exigem o Windows 10, versão 1903 ou uma versão posterior. Para usar esses controles, instale um dos pacotes NuGet listados abaixo. Esses pacotes fornecem tudo o que você precisa para usar os controles encapsulados de XAML Island e os controles de host, incluindo outros pacotes NuGet relacionados que também são necessários.

Tipo de controlo Pacote NuGet Artigos relacionados
Controles encapsulados Versão 6.0.0 ou posterior destes pacotes: Use Ilhas XAML para hospedar um controle UWP XAML em um aplicativo WPF C#
Controle de Host Versão 6.0.0 ou posterior destes pacotes: Use Ilhas XAML para hospedar um controle UWP XAML em um aplicativo WPF C#
Integrar um controlo WinRT XAML personalizado numa aplicação WPF

Esteja atento aos seguintes detalhes:

  • Os pacotes de controle de host também estão incluídos nos pacotes de controle empacotados. Você pode instalar os pacotes de controle encapsulados se quiser usar ambos os conjuntos de controles.

  • Se você estiver hospedando um controle XAML WinRT personalizado, também precisará executar algumas etapas adicionais para fazer referência ao controle personalizado. Para mais informações, veja Hospedagem de um controle personalizado XAML WinRT em uma aplicação WPF utilizando Ilhas XAML.

Controles de exibição da Web

O Kit de Ferramentas da Comunidade do Windows também fornece os seguintes controles .NET para hospedar conteúdo da Web em aplicativos WPF e Windows Forms. Esses controles geralmente são usados em cenários de modernização de aplicativos de área de trabalho semelhantes aos controles da Ilha XAML e são mantidos no mesmo repositório Microsoft.Toolkit.Win32 que os controles da Ilha XAML.

Controlo SO mínimo suportado Descrição
Visualização da Web Windows 10, versão 1803 Usa o mecanismo de renderização do Microsoft Edge para mostrar conteúdo da Web.
Compatível com WebView Janelas 7 Fornece uma versão do WebView que é compatível com mais versões do sistema operacional. Esse controle usa o mecanismo de renderização do Microsoft Edge para mostrar conteúdo da Web no Windows 10 versão 1803 e posterior e o mecanismo de renderização do Internet Explorer para mostrar conteúdo da Web em versões anteriores do Windows 10, Windows 8.x e Windows 7.

Para usar esses controles, instale um destes pacotes NuGet:

Aplicativos de área de trabalho C++ (Win32)

Os controlos .NET da XAML Island não são suportados em aplicações de desktop C++. Em vez disso, esses aplicativos devem usar a API de hospedagem XAML do WinRT fornecida pelo SDK do Windows 10 (versão 1903 e posterior).

A API de alojamento XAML do WinRT consiste em várias classes do Windows Runtime e interfaces COM que a sua aplicação de ambiente de trabalho C++ pode usar para alojar qualquer controlo XAML WinRT derivado de Windows.UI.Xaml.UIElement. Você pode hospedar controles XAML do WinRT em qualquer elemento da interface do usuário em seu aplicativo que tenha um identificador de janela associado (HWND). Para obter mais informações sobre essa API, consulte os seguintes artigos.

Observação

Os controles encapsulados e os controles de host no Kit de Ferramentas da Comunidade do Windows usam a API de hospedagem XAML do WinRT internamente e implementam todo o comportamento que você precisaria lidar sozinho se usasse a API de hospedagem XAML do WinRT diretamente, incluindo navegação pelo teclado e alterações de layout. Para aplicativos WPF e Windows Forms, é altamente recomendável que você use esses controles em vez da API de hospedagem XAML do WinRT diretamente, pois eles abstraem muitos dos detalhes de implementação do uso da API.

Arquitetura de Ilhas XAML

Aqui está uma rápida olhada em como os diferentes tipos de controles XAML Island são organizados arquitetonicamente sobre a API de hospedagem XAML do WinRT.

Arquitetura de controle de host

As APIs que aparecem na parte inferior deste diagrama são fornecidas com o SDK do Windows. Os controles encapsulados e os controles de host estão disponíveis por meio de pacotes NuGet no Kit de Ferramentas da Comunidade do Windows.

Limitações e soluções alternativas

As secções a seguir discutem limitações e soluções alternativas para certos cenários de desenvolvimento UWP em aplicações desktop que usam Ilhas XAML.

Suportado apenas com soluções alternativas

✔️ Os controles de hospedagem do Biblioteca WinUI 2 em uma Ilha XAML são suportados condicionalmente na versão atual das Ilhas XAML. Se seu aplicativo de área de trabalho usa um pacote MSIX para implantação, você pode hospedar controles WinUI de versões de pré-lançamento ou de lançamento do pacote Microsoft.UI.Xaml NuGet. Se seu aplicativo da área de trabalho não estiver empacotado usando MSIX, você poderá hospedar controles WinUI somente se instalar uma versão de pré-lançamento do pacote NuGet Microsoft.UI.Xaml ou se usar a API de Dependências Dinâmicas . Suporte para controles de hospedagem da biblioteca WinUI 3.0 está chegando em uma versão posterior.

✔️ Para acessar o elemento raiz de uma árvore de conteúdo XAML em uma Ilha XAML e obter informações relacionadas sobre o contexto no qual ele está hospedado, não use as classes CoreWindow, ApplicationView e Window . Em vez disso, use a classe XamlRoot. Para obter mais informações, consulte esta seção.

✔️ Para dar suporte ao contrato de Compartilhamento de um aplicativo de área de trabalho WPF, Windows Forms ou C++ (Win32), o seu aplicativo deve usar a interface IDataTransferManagerInterop para obter o objeto DataTransferManager para iniciar a operação de partilha para uma janela específica. Para obter um exemplo que demonstra como usar essa interface em um aplicativo WPF, consulte o exemplo ShareSource.

✔️ Não há suporte para o uso de x:Bind com controles hospedados em Ilhas XAML. Você terá que declarar o modelo de dados em uma biblioteca .NET Standard.

Não suportado

🚫 Usando Ilhas XAML em aplicações WPF e Windows Forms que têm como alvo o .NET Framework. As Ilhas XAML são suportadas apenas em aplicativos destinados ao .NET Core 3.x.

🚫 UWP XAML content em XAML Islands não responde a alterações de tema do Windows do modo escuro para o modo claro ou vice-versa em execução. O conteúdo responde a alterações de alto contraste em tempo de execução.

🚫 Adicionando um controlo Windows.UI.Xaml.WebView. Para aplicações WPF e WinForms, consulte estas alternativas.

O controle MediaPlayer e controle de host MediaPlayerElement não são suportados no modo de tela cheia.

🚫 Entrada de texto com a vista de caligrafia. Para obter mais informações sobre este recurso, consulte este artigo.

🚫 Controles de texto que usam @Places e @People links de conteúdo. Para obter mais informações sobre este recurso, consulte este artigo.

🚫 Ilhas XAML não suportam a hospedagem de um ContentDialog que contém um controlo que aceita entrada de texto, como um TextBox, RichEditBox, ou AutoSuggestBox. Se você fizer isso, o controle de entrada não responderá corretamente a pressionamentos de teclas. Para obter uma funcionalidade semelhante usando uma ilha de XAML, recomendamos que se hospede um Popup que contenha o controlo de entrada.

Ilhas XAML atualmente não oferecem suporte à exibição de arquivos SVG em um controle de Windows.UI.Xaml.Controls.Image hospedado ou usando um objeto Windows.UI.Xaml.Media.Imaging.SvgImageSource. Como solução alternativa, converta os arquivos de imagem que deseja exibir em formatos baseados em raster, como JPG ou PNG.

Contexto de janela do host para ilhas XAML

Ao hospedar Ilhas XAML em um aplicativo da área de trabalho, você pode ter várias árvores de conteúdo XAML em execução no mesmo thread ao mesmo tempo. Para aceder ao elemento raiz de uma árvore de conteúdo XAML numa Ilha XAML e obter informações relacionadas sobre o contexto no qual está hospedado, utilize a classe XamlRoot. As classes CoreWindow, ApplicationView e Window não fornecerão as informações corretas para Ilhas XAML. os objetos CoreWindow e Window existem na thread e são acessíveis na sua aplicação, mas não retornarão limites significativos ou visibilidade (são sempre invisíveis e têm um tamanho de 1x1). Para obter mais informações, consulte Windowing hosts.

Por exemplo, para obter o retângulo delimitador da janela que contém um controle WinRT XAML hospedado em uma XAML Island, use a propriedade XamlRoot.Size do controle. Como cada controlo XAML WinRT que pode ser hospedado numa Ilha XAML deriva de Windows.UI.Xaml.UIElement, pode usar a propriedade XamlRoot do controlo para aceder ao objeto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Não use a propriedade CoreWindows.Bounds para obter o retângulo de delimitação.

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

Para obter uma tabela de APIs comuns relacionadas a janelas que você deve evitar no contexto de Ilhas XAML e as substituições recomendadas de XamlRoot , consulte a tabela em esta seção.

Para obter um exemplo que demonstra como usar essa interface em um aplicativo WPF, consulte o exemplo ShareSource .

Recursos adicionais

Para obter mais informações básicas e tutoriais sobre como usar ilhas XAML, consulte os seguintes artigos e recursos:

  • Modernize a WPF app tutorial: Este tutorial fornece instruções passo a passo para usar os controles envolventes e de anfitrião no Windows Community Toolkit para adicionar controles XAML do WinRT a um aplicativo de linha de negócios WPF existente. Este tutorial inclui o código completo para o aplicativo WPF, bem como instruções detalhadas para cada etapa do processo.
  • exemplos de código de Ilhas XAML: Este repositório contém exemplos de Windows Forms, WPF e área de trabalho C++ (Win32) que demonstram como usar Ilhas XAML.
  • Ilhas XAML v1 - Atualizações e Roteiro: Esta publicação no blog aborda muitas perguntas comuns sobre as Ilhas XAML e apresenta um roteiro de desenvolvimento detalhado.