Início rápido: Crie a sua primeira aplicação WinUI 3

Cria, constrói e executa a tua primeira aplicação WinUI 3. Escolha Visual Studio para uma experiência completa de IDE com suporte para estrutura visual, ou dotnet new para trabalhar na linha de comandos em qualquer editor. Utilize as abas abaixo para alternar entre as duas abordagens.

Visual Studio

Configurar seu ambiente de desenvolvimento

Para desenvolver aplicações WinUI 3 com o Visual Studio, precisa do Visual Studio 2026 com as cargas de trabalho necessárias e o Modo Desenvolvedor ativado.

Configurar com o WinGet (recomendado)

Abra o Terminal do Windows e execute o seguinte comando no PowerShell para instalar automaticamente o Visual Studio 2026 com as cargas de trabalho necessárias e ativar o Modo Desenvolvedor usando um ficheiro de configuração WinGet:

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

Para rever o ficheiro de configuração e saber mais, consulte o README na GitHub.

Note

Se o WinGet não estiver disponível no seu ambiente, instale-o primeiro:

Install-Module -Name Microsoft.WinGet.Client -Force
Repair-WinGetPackageManager -AllUsers

Consulte Usar o WinGet para mais informações.

Configurar manualmente

Se preferir instalar ferramentas manualmente:

1. Ative o Modo de Programador: abra as Definições do Windows, navegue até Sistema > Avançadas e altere Modo de Programador para Ativado.

2. Descarregue e instale o Visual Studio 2026. Para mais detalhes, veja Install Visual Studio.

3. No Visual Studio Installer, selecione a carga de trabalho de desenvolvimento de aplicações WinUI no separador Workloads. Para desenvolvimento em C++, selecione também as ferramentas de desenvolvimento de aplicações WinUI em C++ nessa carga de trabalho, no painel de detalhes da instalação.

   

Sugestão

Se não vires templates WinUI depois de instalares Visual Studio, abre o Instalador Visual Studio, seleciona Modificar e confirma que a carga de trabalho Desenvolvimento de aplicações WinUI está verificada. Reinicie o Visual Studio após modificar a instalação.

Crie e lance a sua primeira aplicação WinUI 3

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

2. Pesquise por WinUI, selecione o modelo de projeto WinUI Blank App (Packaged) C# e selecione Seguinte.

   

3. Introduza o nome de um projeto e selecione Criar.

   

4. Pressiona Iniciar (F5) para construir e executar a sua aplicação.

   

   A sua aplicação é construída, implementada e lançada em modo de depuração:

   

   Criou e lançou a sua primeira aplicação WinUI 3! 🎉

Linha de comandos

Prerequisites

• Windows 10 versão 1809 (build 17763) ou posterior
• Modo Desenvolvedor ativado (ms-settings:developers)
• .NET 10 SDK ou posterior (verificar com dotnet --version)

Crie e execute a sua primeira aplicação WinUI 3

1. Instale os templates de projeto WinUI 3 para dotnet new (execute uma vez):

   dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates
   

2. Crie um novo projeto e avance para ele:

   dotnet new winui -n MyWinUIApp
   cd MyWinUIApp
   

3. Compile o projeto:

   dotnet build
   

4. Execute o aplicativo:

   dotnet run
   

   O modelo inclui Microsoft.Windows.SDK.BuildTools.WinApp, que se integra no destino run da CLI do .NET para registar uma identidade de depuração e iniciar a aplicação com identidade de pacote MSIX — não é necessária nenhuma etapa manual de implantação.

   Abre-se uma janela de aplicação vazia. Criou e lançou a sua primeira aplicação WinUI 3! 🎉

Troubleshooting

Se tiveres problemas a construir ou a correr a tua primeira aplicação, experimenta estas soluções comuns:

Problema	Solução
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 da aplicação WinUI está verificada. Reinicie o Visual Studio após modificar a instalação. Consulte a dica em Configurar o seu ambiente de desenvolvimento para mais detalhes.
Falha na compilação com erros na versão do SDK	Abra o Instalador do Visual Studio e selecione Componentes Individuais. Verifique se a versão do SDK do Windows que o seu projeto pretende está instalada. No ficheiro do seu projeto, confirme que TargetFramework corresponde ao SDK instalado (por exemplo, net10.0-windows10.0.26100.0).
Falhas na restauração do NuGet	Limpa a cache local do NuGet e restaura novamente. Num terminal, executa: dotnet nuget locals all --clear então dotnet restore.
Erro "Modo Desenvolvedor não ativado"	Abra as Definições do Windows >Sistema > Avançadas e ative Modo de Programador para Ativado. Consulte Ativar o Modo Desenvolvedor para mais informações.
Alterações não reconhecidas após a primeira instalação do SDK	Depois de instalar ou atualizar as cargas de trabalho do SDK de Aplicações Windows ou Visual Studio pela primeira vez, reinicie o Visual Studio para que ele absorva os novos componentes.

Sugestão

Se nenhuma das opções acima resolver o seu problema, pesquise nos problemas do GitHub do SDK de Aplicações Windows ou pergunte no Microsoft Q&A.

Próximos passos

Constrói a tua primeira aplicação WinUI
Pronto para ir mais longe? Siga o tutorial passo a passo para construir uma aplicação WinUI completa.

Galeria WinUI 3
Explore exemplos interativos de controlos, funcionalidades e características do WinUI.

Exemplos e recursos
Consulte exemplos de código, projetos iniciais e ferramentas para acelerar o seu desenvolvimento.