Introdução ao WinUI 2 para UWP

WinUI 2.8 é a versão estável mais recente do WinUI que pode ser usado para criar aplicativos UWP de produção (e aplicativos de desktop usando ilhas XAML).

A biblioteca está disponível como um pacote NuGet que pode ser adicionado a qualquer projeto novo ou existente do Visual Studio.

Configurar o Visual Studio para desenvolvimento UWP

Baixe o Visual Studio 2022 e instale as ferramentas para desenvolvimento UWP. Para obter instruções mais detalhadas, consulte Criar um aplicativo UWP nos documentos do Visual Studio.

No separador de Cargas de Trabalho do aplicativo Visual Studio Installer, selecione as seguintes cargas de trabalho e componentes:

Baixe e instale o WinUI

1. Abra um projeto existente ou crie um novo projeto usando o modelo Aplicativo em Branco em Visual C# > Windows > Universal ou o modelo apropriado para sua projeção de linguagem.

   Importante

   Para usar o WinUI 2.8, você deve definir TargetPlatformVersion >= 10.0.18362.0 e TargetPlatformMinVersion >= 10.0.17763.0 nas propriedades do projeto.

2. No painel Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Gerenciar pacotes NuGet.

   
   O painel Gerenciador de Soluções com o projeto clicado com o botão direito do mouse e a opção Gerenciar Pacotes NuGet realçada.

3. No Gerenciador de Pacotes NuGet, selecione a guia Procurar e procure Microsoft.UI.Xaml ou WinUI. Selecione quais pacotes NuGet WinUI você deseja usar (o pacote Microsoft.UI.Xaml contém controles Fluent e recursos adequados para todos os aplicativos). Clique em Instalar.

   Marque a caixa de seleção "Incluir pré-lançamento" para ver as versões de pré-lançamento mais recentes que incluem novos recursos experimentais.

   
   A caixa de diálogo Gerenciador de Pacotes NuGet mostrando a guia Procurar com winui no campo de pesquisa e Incluir pré-lançamento marcada.

4. Adicione os recursos de tema WinUI ao seu arquivo App.xaml.

   Há duas maneiras de fazer isso, dependendo se você tem recursos adicionais do aplicativo.

   a) Se você não precisar de outros recursos do aplicativo, adicione o elemento de recursos WinUI XamlControlsResources conforme mostrado no exemplo a seguir:

   <Application
       x:Class="ExampleApp.App"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       RequestedTheme="Light">
   
       <Application.Resources>
           <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
       </Application.Resources>
   
   </Application>
   

   b) Se tiver outros recursos, recomendamos que os adicione a XamlControlsResources.MergedDictionaries. Isso funciona com o sistema de recursos da plataforma para permitir substituições dos recursos XamlControlsResources.

   <Application
       x:Class="ExampleApp.App"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:controls="using:Microsoft.UI.Xaml.Controls"
       RequestedTheme="Light">
   
       <Application.Resources>
           <controls:XamlControlsResources>
               <controls:XamlControlsResources.MergedDictionaries>
                   <ResourceDictionary Source="/Styles/Styles.xaml"/>
                   <!-- Other app resources here -->
               </controls:XamlControlsResources.MergedDictionaries>
           </controls:XamlControlsResources>
       </Application.Resources>
   
   </Application>
   

5. Adicione uma referência ao pacote WinUI às páginas XAML e/ou às páginas code-behind.

   • Na página XAML, adicione uma referência na parte superior da página

     xmlns:muxc="using:Microsoft.UI.Xaml.Controls"
     

   • No teu código (se quiseres usar os nomes de tipo sem os qualificar), podes adicionar uma diretiva de utilização.

     using MUXC = Microsoft.UI.Xaml.Controls;
     

Etapas adicionais para um projeto C++/WinRT

Quando você adiciona um pacote NuGet a um projeto C++/WinRT, as ferramentas geram um conjunto de cabeçalhos de projeção na pasta \Generated Files\winrt do projeto. Para integrar esses ficheiros de cabeçalho no teu projeto e garantir que as referências a esses novos tipos são resolvidas, podes abrir o ficheiro de cabeçalho pré-compilado (normalmente pch.h) e incluí-los. Abaixo está um exemplo que inclui os arquivos de cabeçalho gerados para o pacote Microsoft.UI.Xaml .

// pch.h
...
#include <winrt/Microsoft.UI.Xaml.Automation.Peers.h>
#include <winrt/Microsoft.UI.Xaml.Controls.Primitives.h>
#include <winrt/Microsoft.UI.Xaml.Media.h>
#include <winrt/Microsoft.UI.Xaml.XamlTypeInfo.h>
...

Para obter um passo a passo completo sobre como adicionar suporte simples para WinUI a um projeto C++/WinRT, consulte Um exemplo simples de WinUI C++/WinRT.

WinUI no GitHub

Aceitamos relatórios de bugs no repositório microsoft-ui-xaml no GitHub.