Criar seu primeiro aplicativo WinUI

Crie seu primeiro aplicativo WinUI e veja-o ganhar vida em Windows. Este início rápido leva você da configuração da ferramenta para um aplicativo em execução e, em seguida, orienta você pela sua primeira atualização de interface.

Antes de começar

O que você aprenderá

• Escolha e configure suas ferramentas de desenvolvimento.
• Crie e execute um aplicativo WinUI.
• Atualize a interface e veja sua alteração no app em execução.

Escolha suas ferramentas de desenvolvimento

Siga um dos caminhos recomendados neste guia de início rápido:

• CLI do winapp: Trabalhe em um terminal no editor de sua preferência. Esse fluxo de trabalho de linha de comando também funciona bem para programação com agentes.
• Visual Studio: Use uma experiência integrada de desenvolvimento e depuração.

Se suas ferramentas já estiverem instaladas, vá para Criando seu primeiro aplicativo.

Instalação das ferramentas

winapp CLI

1. Habilitar o modo de desenvolvedor. Você pode abrir suas configurações com as configurações do Desenvolvedor.

2. Instale o SDK do .NET 10 e a CLI de desenvolvimento do aplicativo do Windows. Se você usa o WinGet, execute:

   winget install --id Microsoft.DotNet.SDK.10 --exact --source winget
   winget install --id Microsoft.WinAppCLI --exact --source winget
   

   Pule a instalação se a ferramenta necessária já estiver instalada.

3. Abra um novo terminal para que ele reconheça os comandos instalados e, em seguida, verifique as versões:

   dotnet --version
   winapp --version
   

   Use o .NET SDK 10 ou posterior e o winapp CLI 0.6 ou posterior para esse fluxo de trabalho.

Note

A CLI do winapp está em prévia pública. winapp new gerencia os modelos de projeto do WinUI, mas não instala o SDK do .NET. Consulte o comunicado da CLI 0.6 sobre os novos comandos project e run.

Visual Studio

Instale Visual Studio 2026 com a carga de trabalho de desenvolvimento de aplicativos WinUI e habilite o Modo de Desenvolvedor.

Configurar usando o WinGet

Abra Terminal do Windows e execute este comando do PowerShell para instalar as cargas de trabalho necessárias do Visual Studio e habilitar o Modo de Desenvolvedor por meio de um arquivo de configuração do WinGet:

winget configure -f https://aka.ms/winui-config

Você pode consultar a configuração e seus requisitos no README da configuração.

Configurar manualmente

Se você preferir a instalação manual ou não tiver o WinGet:

1. Habilitar o modo de desenvolvedor.

2. Baixe e instale Visual Studio 2026.

3. No instalador Visual Studio, selecione a carga de trabalho de desenvolvimento de aplicativos WinUI.

   

Criando seu primeiro aplicativo

Use o fluxo de trabalho instalado acima para criar e iniciar o projeto.

winapp CLI

Em uma pasta em que você mantém seus projetos, execute:

winapp new --name MyWinUIApp --template winui --use-defaults
cd MyWinUIApp
winapp run

winapp new cria o aplicativo WinUI em branco. winapp run compila o projeto e o inicia; você não precisa de um comando de build ou de registro de pacote separado.

Visual Studio

1. Abra o Visual Studio e selecione Criar um novo projeto.

2. Pesquise por WinUI, selecione o modelo C# WinUI Blank App (Packaged) e selecione Avançar.

   

3. Nomeie o project MyWinUIApp e selecione Create.

4. Pressione F5 para compilar e executar o aplicativo.

Seu aplicativo abre uma janela do desktop. Continue com a opção Fazer uma alteração abaixo.

Fazer uma alteração

Mantenha o projeto que você acabou de criar. Adicione uma mensagem à interface existente:

1. Feche o aplicativo em execução. Abra MainPage.xaml em seu editor. Se o modelo não contiver esse arquivo, abra MainWindow.xaml em vez disso.

2. Localize o painel de layout que contém o conteúdo do aplicativo. No modelo vazio atual da CLI, MainPage.xaml contém um <Grid /> vazio. Substitua essa grade vazia por:

   <Grid>
       <TextBlock
           Text="Hello, WinUI!"
           HorizontalAlignment="Center"
           VerticalAlignment="Center" />
   </Grid>
   

   Se o painel já contiver controles, adicione apenas o TextBlock dentro desse painel. Mantenha os controles, nomes e manipuladores de eventos existentes. Não substitua o entorno Page ou Windowa barra de quadros e título em MainWindow.xaml.

3. Salve o arquivo. Execute winapp run novamente na pasta do projeto ou pressione F5 em Visual Studio.

Parabéns! Você criou, executou e atualizou seu primeiro aplicativo WinUI. A janela agora exibe Hello, WinUI!

Solução de problemas

Problema	O que verificar
winapp ou dotnet não é reconhecido.	Reabra o terminal após a instalação. Use os comandos de versão na aba CLI para confirmar que ambas as ferramentas estão disponíveis.
winapp new não é reconhecido.	Esse fluxo de trabalho requer a CLI do winapp 0.6 ou posterior. Atualize a CLI usando o método de instalação escolhido.
Os modelos winUI não aparecem no Visual Studio.	Abra o Visual Studio Installer, selecione Modificar e confirme que a carga de trabalho de desenvolvimento de aplicativos WinUI está instalada. Reinicie o Visual Studio depois.
A compilação indica um erro do SDK ou de restauração.	Verifique os pré-requisitos do fluxo de trabalho selecionado e o primeiro erro na saída do build. Use o suporte do SDK do Aplicativo do Windows para verificar os requisitos de versão antes de alterar as propriedades do projeto.
Os relatórios de implantação informam que o Modo de Desenvolvedor está desabilitado.	Habilite Modo de Desenvolvedor e então execute o aplicativo novamente.
Sua nova mensagem não aparece.	Salve o arquivo XAML e reinicie o projeto. Em modelos com um MainPage.xaml, adicione a mensagem nessa página em vez de substituir o frame hospedeiro da janela.

Próximas etapas

Criar um aplicativo de anotações

O tutorial de Anotações usa um projeto WinUINotes separado para ensinar páginas, navegação, vinculação de dados e armazenamento local. Você também pode encontrar exemplos de controles específicos em Recursos.