Crie seu primeiro projeto WinUI 3 (Windows App SDK)

2025-03-27

Neste tópico, veremos como usar o Visual Studio para criar um novo projeto SDK do Aplicativo Windows para um aplicativo C#, .NET ou C++ que tenha uma interface do usuário (UI) WinUI 3. Também vamos dar uma olhada em alguns dos códigos no projeto resultante, o que ele faz e como funciona.

Os links para detalhes completos da instalação estão nas etapas abaixo. Recomendamos que o utilizador instale e ative a versão Stable mais recente do Windows App SDK (consulte as Notas de versão do canal Stable).

Sugestão

Não importa qual versão do SDK de Aplicativo Windows você escolha instalar e segmentar (ou qual versão do Visual Studio você usa), é importante verificar quaisquer limitações de e problemas conhecidos nas notas de versão dessa versão (consulte canais de lançamento do SDK de Aplicativo Windows). Ao conhecer quaisquer limitações e problemas conhecidos para a sua versão do SDK de Aplicativos Windows, poderá contorná-los caso se depare com algum deles enquanto segue as etapas neste tópico.

Se você encontrar outros problemas, provavelmente encontrará informações sobre eles em problemas do GitHub, ou na guia Discussões, do repositório WindowsAppSDK GitHub; ou através de uma pesquisa online.

Importante

Se você estiver trabalhando em um aplicativo UWP, consulte Migrar da UWP para o SDK do Aplicativo Windows.

Embalados, desembalados e embalados com localização externa

O empacotamento é uma consideração importante de qualquer projeto do SDK de aplicativos Windows. Para obter mais informações sobre suas opções de empacotamento, consulte Vantagens e desvantagens de empacotar seu aplicativo.

Empacotado: crie um novo projeto para um aplicativo de desktop WinUI 3 em C# ou C++ empacotado

Para configurar o computador de desenvolvimento, consulte Ferramentas de instalação para o SDK de aplicativos do Windows.
No Visual Studio, selecione Arquivo>Novo>Projeto.
Na caixa de diálogo Novo Projeto, nos filtros suspensos, selecione C# ou C++, Windowse WinUI, respectivamente.
Selecione o modelo de projeto Aplicação em Branco, Packaged (WinUI 3 na Área de Trabalho) e clique em Avançar. Esse modelo cria um aplicativo de área de trabalho com uma interface de usuário baseada em WinUI 3. O projeto gerado é configurado com o manifesto do pacote e outro suporte necessário para criar o aplicativo em um pacote MSIX (consulte O que é MSIX?). Para obter mais informações sobre este modelo de projeto, consulte empacote a sua aplicação usando o MSIX de projeto único.
Insira um nome de projeto, escolha quaisquer outras opções conforme desejado e clique em Criar.

O projeto que o Visual Studio gera contém o código do seu aplicativo. O arquivo de App.xaml e o(s) arquivo(s) code-behind definem uma classe derivada dode Aplicativoque representa seu aplicativo em execução. O arquivo MainWindow.xaml e o(s) arquivo(s) code-behind definem uma classe MainWindow que representa a janela principal exibida pelo seu aplicativo. Essas classes derivam de tipos no namespace Microsoft.UI.Xaml fornecido pelo WinUI 3.

O projeto também inclui o manifesto do pacote para compilar a aplicação num pacote MSIX .
Pressione F5 ou use a opção de menu Depurar>Iniciar Depuração para criar e executar sua solução no computador de desenvolvimento e confirmar se o aplicativo é executado sem erros.

O modelo Aplicativo em Branco cria um aplicativo simples com uma única janela para seu conteúdo. Normalmente, os aplicativos são mais complexos e você desejará adicionar elementos à medida que seu aplicativo progride, como novas janelas, páginas ou controles de usuário personalizados. Para obter mais detalhes sobre os itens disponíveis e instruções sobre como adicioná-los, consulte modelos WinUI 3 no Visual Studio.

Captura de tela da caixa de diálogo Adicionar Novo Item com os Itens Instalados do > Visual C sharp > WinUI selecionado e a opção Página em Branco realçada.

Não empacotado: crie um novo projeto para um aplicativo de área de trabalho C# ou C++ WinUI 3 não empacotado

Importante

A partir do SDK de Aplicativo Windows 1.0, a abordagem padrão para carregar o SDK de Aplicativo Windows de um aplicativo embalado com localização externa ou um aplicativo não embalado é utilizar inicialização automática através da propriedade de projeto <WindowsPackageType>, além de realizar alterações de configuração adicionais. Para as etapas envolvidas na inicialização automática no contexto do projeto WinUI 3, continue lendo esta seção. Ou, se você tiver um projeto existente que não seja WinUI 3, consulte Usar o SDK do Aplicativo Windows em um projeto existente.

Para configurar o computador de desenvolvimento, consulte Ferramentas de instalação para o SDK de aplicativos do Windows.
Transfira e execute o instalador mais recente para o SDK de Aplicações Windows a partir de Transferências para o SDK de Aplicações Windows. Isso instalará as dependências do pacote runtime necessárias para executar e implementar uma aplicação empacotada com localização externa ou uma aplicação não empacotada no dispositivo de destino (consulte o guia de implantação do SDK de Aplicações Windows para aplicações dependentes da estrutura empacotadas com localização externa ou não empacotadas).
C++. Instale o Microsoft Visual C++ Redistributable (VCRedist) apropriado para a arquitetura do dispositivo de destino.
- A versão mais recente do VCRedist é compatível com a versão do Visual Studio disponível de forma geral (GA), ou seja, que não sejam versões de pré-visualização, bem como todas as versões do Visual Studio que podem ser usadas para criar binários do Windows App SDK.
- Compilações internas do Visual Studio podem ter instalado uma versão posterior do VCRedist, e a execução da versão pública falhará com este erro (que você pode ignorar): 0x80070666 de erro: Não é possível instalar um produto quando uma versão mais recente é instalada.
Observação

Se você não tiver o VCRedist instalado no dispositivo de destino, os links dinâmicos para c:\windows\system32\vcruntime140.dll falharão. Essa falha pode se manifestar aos usuários finais de várias maneiras.
No Visual Studio, selecione Arquivo>Novo>Projeto.
Nos filtros suspensos da caixa de diálogo Novo Projeto, selecione C# ou C++ , Windows e WinUI , respectivamente.
Você precisa começar com um projeto empacotado para usar o diagnóstico XAML. Portanto, selecione o modelo de projeto Aplicativo em branco, empacotado (WinUI 3 na área de trabalho) e clique em Avançar.

Importante

Certifique-se de que o projeto que acabou de criar está a ter como alvo a versão do Windows App SDK que instalou com o instalador na etapa 2. Para fazer isso, no Visual Studio, clique em Ferramentas >Gerenciador de Pacotes NuGet>Gerenciar Pacotes NuGet para Solução...>Atualizações. E, se necessário, atualize a referência ao pacote Microsoft.WindowsAppSDK NuGet. Você pode ver qual versão está instalada no separador Instalado.
Adicione a seguinte propriedade ao seu arquivo de projeto — seu arquivo .csproj (C#) ou .vcxproj (C++). Coloque-o dentro do PropertyGroup elemento que já está lá (para C++, o elemento terá Label="Globals"):
```
<Project ...>
  ...
  <PropertyGroup>
    ...
    <WindowsPackageType>None</WindowsPackageType>
    ...
  </PropertyGroup> 
  ...
</Project>
```

C++. No seu arquivo de projeto C++ (.vcxproj), dentro do elemento PropertyGroup que já está lá, definir a propriedade AppxPackage para false:

<Project ...>
  ...
  <PropertyGroup Label="Globals">
    ...
    <AppxPackage>false</AppxPackage>
    ...
  </PropertyGroup> 
  ...
</Project>

C#. Para iniciar um aplicativo C# no Visual Studio (seja de Depuração ou Sem Depuração), selecione o perfil de inicialização Não empacotado na lista suspensa Iniciar. Se o perfil Package estiver selecionado, você verá um erro de implantação no Visual Studio. Esta etapa não é necessária se você iniciar o aplicativo (.exe) a partir da linha de comando ou do Explorador de Arquivos do Windows.
Compilar e executar.

A API do Bootstrapper

A definição da propriedade <WindowsPackageType>None</WindowsPackageType> do projeto faz com que o inicializador automático localize e carregue uma versão do SDK de Aplicativo Windows que seja mais adequada para a sua aplicação.

Se você tiver necessidades avançadas (como tratamento de erros personalizado ou para carregar uma versão específica do SDK do Aplicativo Windows), poderá chamar a API de bootstrapper explicitamente. Para obter mais informações, consulte Use o runtime do Windows App SDK para aplicações empacotadas com localização externa ou não empacotadas, e Tutorial: Utilize a API bootstrapper numa aplicação empacotada com localização externa ou não empacotada que usa o Windows App SDK.

Para obter mais informações sobre o bootstrapper, consulte Arquitetura de implantação e visão geral para aplicações dependentes de framework.

Uma olhada no código no modelo de projeto

Neste passo a passo, usamos o modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho), que cria um aplicativo de área de trabalho com uma interface de usuário baseada em WinUI 3. Vamos dar uma olhada em alguns dos códigos que acompanham esse modelo e o que ele faz. Para mais informações sobre os modelos de projeto e item WinUI 3 disponíveis, consulte modelos WinUI 3 no Visual Studio.

O ponto de entrada do aplicativo

Quando o sistema operacional Windows executa um aplicativo, o sistema operacional inicia a execução no ponto de entrada do aplicativo. Esse ponto de entrada assume a forma de uma função Main (ou wWinMain for C++/WinRT). Normalmente, um novo projeto configura essa função para ser gerada automaticamente pelo processo de compilação do Visual Studio. E ele está oculto por padrão, então você não precisa se preocupar com isso. Mas se estiveres curioso para obter mais informações, então consulta Instanciação única em Main ou wWinMain.

A classe App

O aplicativo como um todo é representado por uma classe que normalmente é chamada simplesmente de App. Essa classe é definida em App.xaml e nos seus ficheiro(s) code-behind (App.xaml.cs, ou em App.xaml.h e .cpp). App é derivado da classe WinUI 3 Microsoft.UI.Xaml.Application.

O código gerado no ponto de entrada cria uma instância de Appe coloca-a em execução.

No construtor de App, você verá o InitializeComponent método sendo chamado. Esse método essencialmente analisa o conteúdo de App.xaml, que é a marcação XAML. E isso é importante porque App.xaml contém recursos mesclados que precisam ser resolvidos e carregados em um dicionário para o aplicativo em execução usar.

Outro método interessante de App é OnLaunched. Ali, criamos e ativamos uma nova instância da classe MainWindow (que veremos a seguir).

A classe MainWindow

A janela principal exibida pelo aplicativo é, naturalmente, representada pela classe MainWindow. Essa classe é definida no MainWindow.xaml e no(s) seu(s) ficheiro(s) subjacente(s) (MainWindow.xaml.cs, ou MainWindow.xaml.h e .cpp). MainWindow é derivado da classe Microsoft.UI.Xaml.Window do WinUI 3.

O construtor de MainWindow chama o seu próprio método InitializeComponent. Novamente, seu trabalho é transformar a marcação XAML dentro MainWindow.xaml em um gráfico de objetos de interface do usuário (UI).

Em MainWindow.xaml, você verá o layout básico de MainWindow. Na raiz do layout há um painel dinâmico chamado Microsoft.UI.Xaml.Controls.StackPanel. Para obter mais informações sobre painéis de layout, consulte Painéis de layout.

Dentro do StackPanel está um botão Microsoft.UI.Xaml.Controls. E esse botão usa a marcação Click="myButton_Click" para conectar declarativamente um método manipulador de eventos para o evento de clique .

Esse método é chamado myButton_Click, e você pode encontrar a implementação desse método em MainWindow.xaml.cs, ou em MainWindow.xaml.cpp. Nele, o conteúdo do botão é alterado do padrão "Click Me" para "Clicked".

C++. Se você criou um projeto C++, também verá um arquivo MainWindow.idl. Para obter mais informações, consulte a documentação do C++/WinRT. controles XAML; ligar a uma propriedade do C++/WinRT é uma boa maneira de começar a aprender sobre a finalidade e o uso de arquivos .idl.

Próximos passos

Este tópico mostrou como criar um projeto do Visual Studio para um aplicativo empacotado ou não empacotado. Para obter um exemplo de como adicionar funcionalidade a esse aplicativo, consulte Tutorial: Criar um visualizador de fotos simples com WinUI 3. Esse tópico percorre o processo de criação de um aplicativo simples para exibir fotos.

Em seguida, para continuar sua jornada de desenvolvimento com o SDK de Aplicativos Windows, consulte Desenvolver aplicativos da área de trabalho do Windows.