Hospedar controles WinRT XAML em aplicativos da área de trabalho (Ilhas XAML)

  • Artigo

Importante

Este tópico usa ou menciona tipos do repositório GitHub CommunityToolkit/Microsoft.Toolkit.Win32. Para saber mais sobre o suporte a ilhas XAML, confira o Aviso de ilhas XAML nesse repositório.

No Windows 10 em diante, versão 1903, você pode hospedar controles WinRT XAML em aplicativos da área de trabalho que não sejam UWP usando um recurso chamado Ilhas XAML. Esse recurso permite que você aprimore a aparência e a funcionalidade de seus aplicativos WPF, Windows Forms e C++ de desktop (Win32) existentes com os recursos mais recentes de interface do usuário do Windows que só estão disponíveis por meio dos controles XAML WinRT. Isso significa que você pode usar recursos do UWP, como o Windows Ink, e controles que dão suporte ao Sistema Fluent Design nos seus aplicativos para desktop WPF, Windows Forms e C++ existentes.

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

  • A maioria dos controles internos XAML do WinRT fornecidos pela biblioteca do WinUI 2 ou pelo SDK do Windows (confira as exceções).
  • Qualquer controle WinRT XAML personalizado (por exemplo, um controle de usuário que consiste em vários controles WinRT XAML que funcionam juntos). É necessário ter o código-fonte do controle personalizado para compilá-lo com o aplicativo.

Fundamentalmente, as Ilhas XAML são criadas com a API de hospedagem XAML do WinRT. Essa API consiste em várias classes do Windows Runtime 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 Windows Community Toolkit que usa a API de hospedagem XAML do WinRT internamente e fornece uma experiência de desenvolvimento mais conveniente para aplicativos WPF e do Windows Forms.

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

Observação

Caso tenha comentários sobre as Ilhas XAML, crie um problema no repositório Microsoft.Toolkit.Win32 e deixe seus comentários nele.

Requisitos

As Ilhas XAML têm estes requisitos de runtime:

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

Aplicativos WPF e do Windows Forms

Observação

Usar Ilhas XAML para hospedar controles WinRT XAML no WPF, bem como em aplicativos do Windows Forms, atualmente é compatível somente com aplicativos destinados ao .NET Core 3.x. As Ilhas XAML ainda não têm suporte em aplicativos destinados ao .NET nem em aplicativos de qualquer versão do .NET Framework.

Recomendamos que os aplicativos WPF e do Windows Forms usem os controles .NET da Ilha XAML disponíveis no Kit de Ferramentas da Comunidade do Windows. Esses controles fornecem um modelo de objeto que simula (ou fornece acesso a) propriedades, métodos e eventos dos controles WinRT XAML correspondentes. Eles também processam o comportamento, como a navegação por teclado e as alterações de layout.

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

Controles encapsulados

Os aplicativos WPF e do Windows Forms podem usar uma seleção de controles da Ilha XAML que encapsulam a interface e a funcionalidade de um controle WinRT XAML específico. Adicione esses controles diretamente à área de design do projeto do WPF ou do Windows Forms e use-os como qualquer outro controle WPF ou Windows Forms no designer.

No momento, os controles WinRT XAML encapsulados a seguir estão disponíveis no Kit de Ferramentas da Comunidade do Windows.

Control Sistema operacional mínimo compatível Descrição
InkCanvas
InkToolbar		 Windows 10, versão 1903 Forneça uma superfície e as barras de ferramentas relacionadas para a interação do usuário baseada no Windows Ink em seu aplicativo da área de trabalho WPF ou do Windows Forms.
MediaPlayerElement Windows 10, versão 1903 Insere uma exibição que transmite e renderiza o conteúdo de mídia, como um vídeo no aplicativo da área de trabalho WPF ou do Windows Forms.
MapControl Windows 10, versão 1903 Permite exibir um mapa simbólico ou fotorrealista no aplicativo da área de trabalho WPF ou do Windows Forms.

Para ver instruções de uso dos controles XAML encapsulados do WinRT, confira Usar as ilhas XAML para hospedar um controle XAML da UWP em um aplicativo WPF em C#.

Controles de host

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

Control Sistema operacional mínimo compatível Descrição
WindowsXamlHost Windows 10, versão 1903 Pode hospedar qualquer controle WinRT XAML derivado de Windows.UI.Xaml.UIElement, incluindo qualquer controle WinRT XAML internamente fornecido pelo SDK do Windows, bem como controles personalizados.

Para ver instruções de uso do controle de WindowsXamlHost, confira Usar as ilhas XAML para hospedar um controle XAML da UWP em um aplicativo WPF em C# e Hospedar um controle XAML personalizado do WinRT em um aplicativo WPF usando as Ilhas XAML.

Configurar o projeto para usar os controles .NET da Ilha XAML

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 de host e os controles encapsulados da Ilha XAML e incluem outros pacotes NuGet relacionados que também são necessários.

Tipo de controle Pacote NuGet Artigos relacionados
Controles encapsulados Versão 6.0.0 ou posterior destes pacotes: Usar as ilhas XAML para hospedar um controle XAML da UWP em um aplicativo WPF em C#
Controle de host Versão 6.0.0 ou posterior destes pacotes: Usar as ilhas XAML para hospedar um controle XAML da UWP em um aplicativo WPF em C#
Hospedar um controle WinRT XAML personalizado em um aplicativo WPF

Esteja ciente dos seguintes detalhes:

  • Os pacotes do controle de host também estão incluídos nos pacotes do controle encapsulado. Instale os pacotes do controle encapsulado caso deseje usar os dois conjuntos de controles.

  • Se estiver hospedando um controle WinRT XAML personalizado, você também precisará executar algumas etapas adicionais para referenciar o controle personalizado. Para obter mais informações, confira Hospedar um controle WinRT XAML personalizado em um aplicativo WPF usando as Ilhas XAML.

Controles de exibição da Web

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

Control Sistema operacional mínimo compatível Descrição
WebView Windows 10, versão 1803 Usa o mecanismo de renderização do Microsoft Edge para mostrar o conteúdo da Web.
WebViewCompatible Windows 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 o conteúdo da Web no Windows 10 versão 1803 e posterior e o mecanismo de renderização do Internet Explorer para mostrar o 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 desktop C++ (Win32)

Não há suporte para os controles .NET da Ilha XAML em aplicativos para desktop C++. Esses aplicativos precisam usar a API de hospedagem XAML do WinRT fornecida pelo SDK do Windows 10 (versão 1903 e posterior).

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

Observação

Os controles encapsulados e os controles de host no Windows Community Toolkit usam a API de hospedagem XAML do WinRT internamente e implementam todo o comportamento que você precisaria processar por conta própria se usasse a API de hospedagem XAML do WinRT diretamente, incluindo a navegação por teclado e as alterações de layout. Para aplicativos WPF e do Windows Forms, recomendamos expressamente que você use esses controles em vez da API de hospedagem XAML do WinRT diretamente, porque eles abstraem muitos dos detalhes de implementação do uso da API.

Arquitetura das Ilhas XAML

Veja a seguir uma visão rápida de como os diferentes tipos de controles da Ilha XAML são organizados em termos de arquitetura na API de hospedagem XAML do WinRT.

Host control Architecture

As APIs exibidas na parte inferior do 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 seções a seguir abordam limitações e soluções alternativas para alguns cenários de desenvolvimento em UWP em aplicativos da área de trabalho que usam as Ilhas XAML.

Compatível apenas com soluções alternativas

✔️ A hospedagem de controles da Biblioteca WinUI 2 em uma Ilha XAML tem suporte condicional na versão atual das Ilhas XAML. Se o seu aplicativo da área de trabalho usar um pacote MSIX para implantação, você poderá hospedar controles WinUI de versões de pré-lançamento ou de lançamento do pacote NuGet Microsoft.UI.Xaml. Se o seu aplicativo da área de trabalho não for empacotado usando MSIX, você poderá hospedar controles de 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. O suporte para hospedagem de controles da Biblioteca WinUI 3.0 será disponibilizado 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 WPF, Windows Forms ou aplicativo C++ da área de trabalho (Win32), o aplicativo precisará usar a interface IDataTransferManagerInterop para fazer com que o objeto DataTransferManager inicie a operação de compartilhamento em uma janela específica. Para obter uma amostra que descreve como usar essa interface em um aplicativo WPF, confira a amostra ShareSource.

✔️ Não há suporte para o uso de x:Bind com os controles hospedados em Ilhas XAML. É necessário declarar o modelo de dados em uma biblioteca .NET Standard.

Sem suporte

🚫 Usando Ilhas XAML nos aplicativos WPF e Windows Forms que direcionam o .NET Framework. Há suporte para Ilhas XAML somente em aplicativos que direcionam o .NET Core 3.x.

🚫 O conteúdo UWP XAML nas Ilhas XAML não responde às alterações de tema do Windows de escuro para claro ou vice-versa em runtime. O conteúdo responde a alterações de alto contraste em runtime.

🚫 Como adicionar um controle Windows.UI.Xaml.WebView. Para aplicativos WPF e WinForms, confira estas alternativas.

🚫 Não há suporte para o controle MediaPlayer e o controle de host MediaPlayerElement no modo de tela inteira.

🚫 Entrada de texto com a exibição de texto manuscrito. Para obter mais informações sobre esse recurso, confira este artigo.

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

🚫 Ilhas XAML não dão suporte à hospedagem de um ContentDialog que contenha um controle que aceita entrada de texto, como TextBox, RichEditBox ou AutoSuggestBox. Se você fizer isso, o controle de entrada não responderá adequadamente aos pressionamentos de tecla. Para obter funcionalidade semelhante usando uma Ilha XAML, recomendamos hospedar uma Pop-up que contenha o controle de entrada.

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

Contexto do host de janela para Ilhas XAML

Ao hospedar as 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 simultaneamente. 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, use a classe XamlRoot. As classes CoreWindow, ApplicationView e Window não fornecerão as informações corretas para as Ilhas XAML. Objetos CoreWindow e Window existem no thread e podem ser acessados pelo seu aplicativo, mas eles não retornarão limites nem visibilidade significativos (eles são sempre invisíveis e têm um tamanho de 1x1). Para obter mais informações, confira Hosts de exibição em janelas.

Por exemplo, para obter o retângulo delimitador da janela que contém um controle WinRT XAML hospedado em uma ilha XAML, use a propriedade XamlRoot.Size do controle. Como todos os controles WinRT XAML que podem ser hospedados em uma ilha XAML derivam de Windows.UI.Xaml.UIElement, você pode usar a propriedade XamlRoot do controle para acessar o objeto XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Não use a propriedade CoreWindows.Bounds para obter o retâ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 uma tabela de APIs relacionadas à janela comum que você deve evitar no contexto de Ilhas XAML e as substituições de XamlRoot recomendadas, confira a tabela nesta seção.

Para obter uma amostra que descreve como usar essa interface em um aplicativo WPF, confira a amostra ShareSource.

Recursos adicionais

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

  • Tutorial: modernizar um aplicativo WPF: esse tutorial fornece instruções passo a passo de uso dos controles encapsulados e dos controles de host no Kit de Ferramentas da Comunidade do Windows para adicionar controles WinRT XAML a um aplicativo WPF de linha de negócios existente. Esse tutorial inclui o código completo para o aplicativo WPF, bem como instruções detalhadas de cada etapa do processo.
  • Exemplos de código de Ilhas XAML: este repositório contém exemplos do Windows Forms, do WPF e do C++ de desktop (Win32) que demonstram como usar as Ilhas XAML.
  • Ilhas XAML v1: atualizações e roteiro: Essa postagem no blog aborda muitas perguntas comuns sobre as Ilhas XAML e fornece um roteiro de desenvolvimento detalhado.