WinApp CLI 0.8: o que muda com o WinUI DevTools
O WinApp CLI chegou à versão 0.8 com três frentes principais: o WinUI DevTools em preview experimental, o profiling de performance para apps WinUI e o suporte a projetos C++ do Visual Studio. Além disso, a versão traz identidade única para checkouts paralelos, gravações de interface mais legíveis e uma série de correções.
A Microsoft publicou o anúncio em 9 de novembro de 2026, no blog ifdef Windows. O foco continua o mesmo desde o lançamento da ferramenta: criar, executar, depurar e empacotar apps Windows a partir do terminal ou de um agente de código.
Neste texto, cada novidade aparece com o comando correspondente, o que ela resolve na prática e quais limites a própria Microsoft declara. Assim, fica mais fácil decidir o que testar primeiro no seu fluxo de trabalho.
O que é o WinApp CLI
O WinApp CLI, ou Windows App Development CLI, é uma ferramenta de linha de comando open source para criar, executar, depurar, testar e empacotar apps Windows. A Microsoft anunciou a ferramenta em preview público em janeiro de 2026.
Ela funciona com WinUI e também com outros frameworks, como .NET, WPF, WinForms, .NET MAUI, C++, Electron, Rust, Tauri e Flutter. Por isso, o mesmo conjunto de comandos atende tanto quem escreve apps nativos quanto quem traz recursos do Windows para uma aplicação multiplataforma.
Um conceito central da ferramenta é a identidade de pacote. Muitas APIs do Windows, como notificações e IA local, exigem que o app tenha essa identidade para funcionar.
O comando winapp run, por exemplo, registra a saída do build como um pacote e inicia o app com identidade, simulando uma instalação MSIX completa. Já o comando de empacotamento gera e assina o MSIX em uma única etapa.
Desde o início, a ferramenta também mira agentes de IA. Comandos como find-ui e find-api retornam saída em JSON, de modo que um agente consulta exemplos reais de WinUI antes de escrever código.
Novidades do WinApp CLI 0.8 em resumo
A versão 0.8.0 concentra as mudanças em três destaques e alguns complementos. A tabela abaixo resume o que entrou e qual comando aciona cada recurso.
| Novidade | Comando principal | Para que serve |
|---|---|---|
| WinUI DevTools | winapp run . e winapp devtools |
Inspecionar e testar a interface do app em execução |
| Profiling de performance | winapp run . --profile e winapp perf |
Encontrar trabalho caro de XAML, layout e renderização |
| Projetos C++ | winapp run .\MyApp.vcxproj |
Compilar, executar e empacotar projetos .vcxproj |
| Identidade única | --unique-identity |
Rodar checkouts do mesmo app lado a lado |
| Gravações com cursor | winapp ui record --cursor |
Mostrar o ponteiro e destacar os cliques |
Em seguida, cada item recebe uma seção própria, começando pelo maior destaque da versão.
WinUI DevTools no WinApp CLI
O WinUI DevTools permite inspecionar controles, experimentar valores de propriedades e deixar feedback sem sair do app em execução. Em outras palavras, ele leva para o WinUI uma experiência parecida com as ferramentas de desenvolvedor de um navegador.
A Microsoft classifica o recurso como preview experimental. Portanto, funcionalidades e comportamento podem mudar conforme o time recebe feedback da comunidade.
O DevTools suporta apps WinUI 3 escritos em C# e em C++. Ele inicia por padrão nos projetos WinUI compatíveis abertos com winapp run, mas não inicia por padrão em ambientes de CI nem no Windows Sandbox.
Como iniciar o DevTools pelo WinApp CLI
Para começar, basta executar o WinApp CLI no diretório do projeto WinUI:
# Compila, registra e inicia o app com o DevTools ativo
winapp run .
O app abre com uma barra de ferramentas do DevTools em um dos cantos. Em seguida, você escolhe a opção Select element e clica em um controle.
Então, a janela do DevTools abre ao lado do app com o elemento selecionado, sua posição na árvore visual e suas propriedades, bindings e layout. Caso queira desativar o recurso em uma execução, use a opção --devtools:
# Executa o app sem o DevTools
winapp run . --devtools off
A referência da CLI também aceita o valor headless, que não desenha nada dentro do app. Além disso, o comando winapp config set run.devtools define o padrão para a sua conta de usuário.
Árvore visual e o modo Just my XAML
A árvore visual mostra como a interface em execução foi montada. No entanto, um único botão já contém vários elementos internos do template do framework, o que polui a visualização.
Por isso, a opção Just my XAML do WinApp CLI mantém o foco nos elementos que você escreveu. Se você clicar no texto dentro de um botão, por exemplo, o DevTools seleciona o controle declarado no seu XAML.
Quando o DevTools consegue confirmar o elemento contra o projeto, ele mostra o arquivo XAML e a linha da declaração. Com isso, você sai de "quero mudar isto" direto para o código-fonte, sem procurar todos os rótulos parecidos no projeto.
Experimentos ao vivo com propriedades
No inspetor, você expande uma propriedade, edita o valor e vê o resultado no app em execução. Assim, dá para testar outra largura, ajustar espaçamentos ou trocar um brush sem perder o contexto da tela.
O painel de propriedades do WinApp CLI também explica de onde vem o valor atual. Afinal, um valor definido no próprio elemento, vindo de um estilo ou resolvido a partir de um recurso leva a lugares diferentes do código.
Para propriedades ligadas a recursos, o painel permite testar referências ThemeResource ou StaticResource. Além disso, ele sugere chaves compatíveis disponíveis para aquele elemento.
Contudo, essas edições são experimentos, não alterações no código. Elas desaparecem quando o app reinicia, então o valor escolhido precisa ir para o XAML antes de um novo build.
A Microsoft faz um alerta importante: substituir um valor ligado por binding pode substituir o próprio binding naquela execução. Por esse motivo, trate cada edição como teste, e não como correção definitiva.
Comentários para o agente de código
Às vezes, o jeito mais rápido de explicar uma mudança é apontar para ela. Para isso, o DevTools traz a opção Comments na barra de ferramentas.
Você clica em um elemento, escreve uma nota como "Change this label to Save changes" e salva. Então, um marcador permanece sobre o elemento na interface.
Depois, o agente de código lê esse feedback pelo terminal:
# Lista os comentários salvos no projeto
winapp devtools comments list
# Lê um comentário específico pelo ID
winapp devtools comments get cmt_example
Cada comentário carrega contexto sobre o elemento selecionado. Dessa forma, o agente confere a correspondência com o código-fonte, faz a alteração e marca o comentário como resolvido:
# Marca o comentário como resolvido com uma nota
winapp devtools comments update cmt_example --status resolved --note "Updated the label"
Os comentários ficam salvos junto com o projeto e continuam legíveis depois que o app fecha. Na prática, o WinApp CLI cria um ciclo de revisão visual em que a pessoa aponta e o agente executa.
Comandos do DevTools no terminal
Os comandos winapp devtools permitem inspecionar a árvore ao vivo, buscar elementos, ler fonte e propriedades e testar mudanças direto da linha de comando:
# Inspeciona a árvore visual do app em execução
winapp devtools inspect
# Busca elementos pelo texto
winapp devtools search Save
# Mostra onde o elemento foi declarado no XAML
winapp devtools get-source SaveButton
# Lê e altera uma propriedade ao vivo
winapp devtools get-property SaveButton Width
winapp devtools set-property SaveButton Width 200
Você usa o seletor retornado pela inspeção ou o nome único do elemento. Quando mais de um app estiver com o DevTools ativo, a opção -a <pid> indica qual processo inspecionar.
Além disso, a opção --json gera saída estruturada para scripts e agentes de código. Esse detalhe segue a linha de todo o WinApp CLI, que trata o agente como usuário de primeira classe.
Vale notar que winapp devtools complementa winapp ui, em vez de substituí-lo. Enquanto o UI Automation interage com o app como um usuário faria, o DevTools olha para dentro dos elementos WinUI, das propriedades e do XAML.
Profiling de performance com o WinApp CLI
Quando uma página demora para abrir, o primeiro passo é descobrir para onde foi o tempo. Para isso, a versão 0.8 traz os comandos winapp perf.
Esses comandos gravam a atividade do WinUI por meio do ETW, o sistema de rastreamento de eventos do Windows. Em seguida, eles transformam a gravação em relatórios que você consulta pelo terminal.
Como gravar e analisar uma sessão
Primeiro, você inicia a gravação junto com o app, apontando um diretório para o rastreamento:
# Inicia o app e começa a gravar o rastreamento
winapp run . --profile .\traces\navigation --detach
Depois, você navega pelo cenário que quer investigar. Por fim, encerra a gravação com o ID de captura retornado pelo run e gera a análise:
# Encerra a gravação e analisa o resultado
winapp perf stop CAPTURE_ID
winapp perf analyze .\traces\navigation
O relatório do WinApp CLI inclui o uso de recursos do processo e a atividade observada na thread de UI. Também traz visões para recursos XAML caros, operações de layout, elementos e intervalos entre frames.
Em apps .NET, as informações de garbage collection ajudam a verificar se uma coleta coincidiu com a operação lenta. Assim, você separa um problema de alocação de um problema de layout.
A recomendação da Microsoft é investigar as evidências, em vez de tratar todo frame lento como o mesmo problema. Por isso, existem visões específicas:
# Foca no custo de parsing de XAML
winapp perf analyze .\traces\navigation --view parsing
# Lista os hotspots em frames acima de 16,67 ms
winapp perf analyze .\traces\navigation --view hotspots --min-frame-ms 16.67
O valor de 16,67 ms corresponde ao orçamento de um frame a 60 quadros por segundo. Ou seja, o filtro mostra apenas os frames que estouraram esse limite.
Limites do profiling
Por padrão, a gravação começa depois que o app abre, então ela pode perder o início da inicialização. Nesse caso, a opção --profile-mode elevated grava desde o lançamento.
Com essa opção, o Windows pede aprovação de administrador apenas para o gravador. Enquanto isso, o app continua rodando com a sua conta normal.
O profiling do WinApp CLI funciona somente na máquina local. Além disso, os tempos da thread de UI não medem a execução na GPU nem a taxa de quadros exibida na tela.
Projetos C++ no WinApp CLI
O fluxo de projeto agora inclui projetos C++ do Visual Studio. Antes, o suporte a C++ da ferramenta estava centrado em projetos CMake.
Agora, basta apontar o winapp run para um .vcxproj. O WinApp CLI compila com o MSBuild do Visual Studio e inicia o app com identidade de pacote:
# Compila e executa um projeto C++ com identidade
winapp run .\MyApp.vcxproj
Também é possível compilar e criar um MSIX direto do projeto, já assinado com o certificado informado:
# Compila, empacota e assina o projeto C++
winapp package .\MyApp.vcxproj --cert .\devcert.pfx
Assim, um único comando leva o projeto C++ do código-fonte até o pacote assinado. Na referência da CLI, o mesmo fluxo aparece também com o comando winapp pack.
Para isso, você precisa do Visual Studio ou do Build Tools com os componentes C++ que o projeto exige. Em um app WinUI em C++, isso inclui as ferramentas de desenvolvimento WinUI.
Segundo a documentação, o build padrão do run usa a configuração Debug para a arquitetura atual. Por outro lado, o empacotamento usa Release por padrão.
Checkouts lado a lado com identidade única
Trabalhar em dois branches do mesmo app empacotado costuma gerar um conflito silencioso. Como as duas cópias usam a mesma identidade, o registro de uma substitui o da outra.
A nova opção --unique-identity resolve isso ao dar a cada checkout a própria identidade de pacote, que é o nome que o Windows usa para distinguir pacotes instalados:
# Cada checkout ganha a própria identidade de pacote
winapp run .\checkout-a\MyApp.csproj --unique-identity
winapp run .\checkout-b\MyApp.csproj --unique-identity
Com isso, o WinApp CLI permite comparar uma mudança contra outro branch sem desinstalar nada. Além disso, trabalhos paralelos de agentes de código deixam de sobrescrever o registro um do outro.
A identidade deriva do caminho do projeto, então o mesmo caminho sempre recebe a mesma identidade e mantém os dados do app. Por outro lado, um checkout movido ou renomeado ganha uma identidade nova.
Gravações de interface mais claras
As gravações de interface do WinApp CLI agora incluem menus, flyouts e tooltips do WinUI. Antes, esses elementos podiam ficar de fora do vídeo.
A opção --cursor mostra o ponteiro do mouse e um destaque curto em cada clique:
# Grava 20 segundos com o cursor e destaque de clique
winapp ui record -a MyApp --cursor --duration-sec 20 --output .\demo.mp4
Isso deixa um passo a passo mais fácil de acompanhar quando a ação importante acontece em um menu. Caso queira apenas o ponteiro, sem destaque de cliques, adicione --no-click-highlight:
# Mantém o cursor visível sem destacar os cliques
winapp ui record -a MyApp --cursor --no-click-highlight --duration-sec 20 --output .\demo-no-highlight.mp4
Outras mudanças do WinApp CLI 0.8
O comando find-ui agora busca também nas descrições dos controles. Além disso, ele reconhece mais formas de pedir controles, incluindo consultas por tabela, data grid e planilha.
As ações de interface ficaram mais precisas. Agora é possível clicar e passar o mouse em coordenadas explícitas, rolar na horizontal e usar filtros por tipo ou nome de classe sem uma consulta de texto.
Entre as correções, a versão resolve o travamento do winapp ui ao inspecionar apps WinUI 3 com WebView2. Também corrige builds duplicados de projetos referenciados, que podiam causar falhas no empacotamento.
Outras correções melhoram o direcionamento para janelas minimizadas e apps hospedados. A assinatura passou a usar o algoritmo de hash com que o pacote foi construído, e a seleção do template reactor deixou de conflitar com outros pacotes de templates.
No campo da segurança, a versão restringe o carregamento de DLLs pela CLI e pelas ferramentas de diagnóstico. Também atualiza dependências de criptografia e adiciona benchmarks para desenvolvimento assistido por agentes e automação de interface.
Como instalar ou atualizar o WinApp CLI
Para atualizar para a versão mais recente, o caminho mais simples é o WinGet:
# Instala ou atualiza a CLI pelo WinGet
winget install Microsoft.WinAppCLI
Em projetos Node.js, como apps Electron, a instalação acontece pelo npm como dependência de desenvolvimento:
# Instala a CLI como dependência de desenvolvimento
npm install --save-dev @microsoft/winappcli
Também há builds no GitHub Releases e uma action para pipelines de CI. Para conferir a instalação, rode winapp --help, e para ver a versão, rode winapp -V.
Lembre que o projeto ainda está em preview público, então comandos e opções podem mudar antes da versão final. A documentação oficial no Microsoft Learn traz a referência completa.
Se o seu foco é desktop com .NET, vale também comparar as opções de interface do ecossistema. O artigo sobre .NET MAUI vs Flutter ajuda nessa decisão, já que o MAUI usa o WinUI 3 no Windows.
Conclusão
A versão 0.8 mostra uma direção clara para o WinApp CLI: aproximar o desenvolvimento WinUI do ciclo rápido que o desenvolvimento web já oferece. Inspecionar, testar um valor e voltar ao código passou a acontecer em minutos, sem sair do app.
Ao mesmo tempo, o WinApp CLI reforça o papel dos agentes de código. Os comentários do DevTools, a saída em JSON e a identidade única para checkouts paralelos atendem diretamente a quem trabalha com agentes.
O profiling pelo terminal fecha outra lacuna, porque dá números concretos para discutir performance de XAML e layout. Já o suporte a .vcxproj traz os projetos C++ do Visual Studio para o mesmo fluxo de execução e empacotamento.
Por fim, convém lembrar que o DevTools está em preview experimental e o WinApp CLI inteiro ainda está em preview público. Portanto, teste os recursos em projetos reais, mas acompanhe as notas de versão antes de depender deles em pipelines críticos.
FAQ
O WinUI DevTools funciona com apps WinUI em C++?
Sim. O DevTools suporta apps WinUI 3 escritos em C# e em C++, e inicia por padrão nos projetos WinUI compatíveis abertos com winapp run.
As mudanças feitas no DevTools alteram o meu XAML?
Não. As edições são experimentos ao vivo que desaparecem quando o app reinicia, então o valor final precisa ser aplicado no XAML e recompilado.
Como desligar o DevTools em uma execução?
Use winapp run . --devtools off. Para mudar o padrão da sua conta, use winapp config set run.devtools off.
O profiling do WinApp CLI mede a taxa de quadros na tela?
Não. Os tempos da thread de UI não medem a execução na GPU nem a taxa de quadros exibida, e a gravação funciona apenas localmente.
Para que serve a opção unique-identity?
Ela dá a cada checkout do mesmo app a própria identidade de pacote. Assim, dois branches podem ficar registrados ao mesmo tempo sem que um substitua o outro.
Como atualizar o WinApp CLI para a versão 0.8?
Rode winget install Microsoft.WinAppCLI. Em projetos Node.js, use npm install --save-dev @microsoft/winappcli.