Usando a CLI do winapp com WinUI

Este guia mostra como usar a CLI do winapp em todo o loop interno completo de um aplicativo WinUI 3: criar um projeto a partir de um modelo oficial, compilá-lo e iniciá-lo com identidade de pacote, depurar falhas, localizar controles e APIs, automatizar a interface do usuário e produzir um pacote MSIX assinado. Cada etapa é executada na linha de comando, portanto, ela funciona em qualquer editor, em CI e com agentes de codificação de IA.

Os modelos de projeto do WinUI já incluem um Package.appxmanifest, portanto, você não precisa executar winapp init para um aplicativo WinUI. Se você estiver adicionando a identidade do pacote a um aplicativo .NET existente que não usa o WinUI, consulte Usando a CLI do winapp com .NET em vez disso.

Prerequisites

  • Windows 10 versão 1809 ou posterior ou Windows 11.

  • O SDK .NET, versão 8.0.100 ou posterior. Os modelos experimentais do Reactor exigem o SDK .NET 10. A CLI do winapp não instala toolchains, portanto winapp new e winapp run interrompem a execução com orientações se o SDK do .NET estiver ausente.

  • CLI do winapp:

    winget install Microsoft.winappcli --source winget

  • Modo de Desenvolvedor, que o Windows requer para registrar o aplicativo a partir da saída da compilação. Ative-o em Configurações > Sistema > Para desenvolvedores. Para saber o que isso muda em seu computador, consulte Segurança.

Criar um aplicativo WinUI

winapp new gera a estrutura de um aplicativo WinUI a partir do pacote oficial Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Ele instala ou atualiza o pacote de modelos sob demanda e, em seguida, chama dotnet new para você.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Execute winapp new --list para ver os modelos no pacote instalado. O pacote inclui estes modelos:

Template Description
winui Aplicativo XAML em branco mínimo (padrão). Veja a captura de tela
winui-navview Aplicativo XAML com um shell NavigationView. Veja a captura de tela
winui-tabview Aplicativo XAML com um shell TabView. Veja a captura de tela
winui-mvvm Aplicativo XAML que usa o padrão MVVM com CommunityToolkit.Mvvm. Veja a captura de tela
winui-lib Biblioteca de classes WinUI
winui-unittest Projeto mstest empacotado para testes de unidade WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Experimental. Somente aplicativos WinUI escritos em C#, sem XAML

Note

Os modelos do Reactor fazem referência a pacotes Microsoft.UI.Reactor de pré-lançamento. Suas APIs podem ser alteradas ou removidas em uma versão futura.

Para cada opção, consulte a referência do newcomando.

Compilar e executar usando identidade

Na pasta do projeto, winapp run compila o projeto, instala o runtime do SDK do Aplicativo Windows correspondente à sua arquitetura, caso esteja ausente, registra o aplicativo com a identidade do pacote e o inicia.

cd MyApp
winapp run

winapp run aceita um arquivo de projeto, um arquivo de solução, uma pasta que contém um deles ou uma pasta de saída de build:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

A CLI do winapp lê a propriedade do WindowsPackageType projeto para decidir como iniciá-lo. Um projeto empacotado é executado com a identidade do pacote. Um projeto que define WindowsPackageType como None é executado como um aplicativo não empacotado sem identidade. Para executar um projeto empacotado como não empacotado, passe a propriedade na linha de comando:

winapp run -p WindowsPackageType=None

Outras opções úteis incluem --clean remover o registro anterior e os dados salvos do aplicativo (LocalState e configurações) para uma nova primeira execução, --no-launch registrar sem iniciar o aplicativo e --detach --json retornar a ID do processo e sair para que scripts e agentes possam continuar funcionando enquanto o aplicativo é executado. Para obter a lista completa, consulte modo de projeto (projetos do SDK .NET).

Use `dotnet run` em vez disso

Se preferir dotnet run, use o Microsoft.Windows.SDK.BuildTools.WinApp pacote NuGet. O pacote intercepta dotnet run para que ele chame winapp run e inicie o aplicativo com identidade. Os projetos que você cria com winapp new já fazem referência ao pacote, portanto dotnet run funcionam sem configuração extra. Para outros projetos, adicione o pacote primeiro:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

Você pode passar winapp run opções como WinAppRun* propriedades do MSBuild, por exemplo dotnet run -p:WinAppRunDebugOutput=true. Para desativar a integração, defina EnableWinAppRunSupport para false no arquivo de projeto. Para obter detalhes, consulte o suporte ao dotnet run.

Depurar falhas

Adicione --debug-output para capturar mensagens OutputDebugString e exceções de primeira chance enquanto o aplicativo é executado. Quando um aplicativo WinUI falha com uma stowed exception, a CLI do winapp analisa o despejo de falhas e imprime o erro original e a pilha de chamadas em vez de um código de falha genérico.

winapp run --debug-output

Adicione --symbols para fazer download de símbolos para nomes completos de funções nativas. Como --debug-output anexa a CLI do winapp como o depurador, você não pode anexar Visual Studio ou outro depurador ao mesmo processo. Para depurar com seu IDE em vez disso, consulte Depuração com a CLI do winapp. Para obter detalhes sobre a análise de exceção stowed, consulte triagem de stowed-exception do WinUI.

Localizar controles e APIs

winapp find-uipesquisa amostras de XAML e C# da WinUI Gallery e do Windows Community Toolkit por intenção e retorna o código para um cenário escolhido. winapp find-apipesquisa a superfície da API do Windows e do WinRT às quais seu projeto faz referência, como tipos, membros e enumerações do SDK do Aplicativo Windows e do Windows SDK.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Ambos os comandos dão suporte --json, portanto, os agentes de codificação de IA podem usá-los para escolher controles e verificar nomes de API. Para obter mais informações, consulte as referências find-api e find-ui.

Automatizar e verificar a interface do usuário

winapp ui controla um aplicativo em execução por meio de Microsoft Automação da Interface do Usuário. Use-a para inspecionar a árvore de elementos, invocar controles, aguardar as alterações de estado e fazer capturas de tela. Os agentes podem usar os mesmos comandos para verificar suas próprias alterações.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

O PART_PaneToggleButton seletor direciona o botão de menu no winui-navview template. Para seus próprios controles, copie um seletor da saída de winapp ui inspect ou winapp ui search.

Para executar o aplicativo no Windows Sandbox em vez de em sua área de trabalho, adicione --on sandbox a winapp run e winapp ui. Para obter mais informações, consulte automação da interface do usuário e execução da área restrita.

Empacotamento e assinatura

Quando estiver pronto para testar um pacote localmente, gere um certificado de desenvolvimento cujo publicador corresponda ao manifesto e, em seguida, compile e empacote o projeto em uma etapa:

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack cria o projeto e produz um .msix assinado. Para combinar builds para várias arquiteturas em uma .msixbundle, consulte bundles de várias arquiteturas. O projeto deve ser empacotado, portanto, um projeto que define WindowsPackageType como None não pode ser empacotado. Para projetos WinUI, o build do SDK do Aplicativo Windows é responsável pelo manifesto, pelo ponto de entrada e pela geração de recursos, portanto, --manifest, --executable e --skip-pri não são aceitos.

O certificado de desenvolvimento destina-se apenas a testes locais e usa uma senha padrão. Antes de distribuir seu aplicativo, assine-o com um certificado confiável, por exemplo, com winapp az-sign e Assinatura Confiável do Azure. Para obter mais informações, consulte Empacotar um projeto diretamente e Segurança.

Projetos WinUI existentes

A CLI do winapp funciona com projetos WinUI que você criou no Visual Studio. Aponte winapp run para o arquivo de projeto, o arquivo de solução ou a pasta que contenha um deles. Para winapp pack, passe o .csproj. Você pode continuar criando e depurando em Visual Studio e usar a CLI do winapp para scripts, CI e fluxos de trabalho do agente.

WinUI com C++

winapp runtambém compila e inicia projetos WinUI do C++/WinRT (.vcxproj) que você criou com base no modelo do Visual Studio WinUI Blank App (Empacotado). Ele cria o projeto com o MSBuild do Visual Studio, registra o aplicativo com a identidade do pacote e o inicia:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

Os projetos de C++ precisam do Visual Studio ou do Build Tools para Visual Studio com a workload Desktop development with C++ e ferramentas de desenvolvimento de aplicativos WinUI para C++. winapp packnão compila .vcxproj projetos, portanto, crie o pacote MSIX no Visual Studio. Para pré-requisitos e opções, consulte projetos C++ (.vcxproj). Para aplicativos C++ que não usam WinUI, consulte Usando a CLI do winapp com C++.

Samples

  • winui-app: um aplicativo WinUI empacotado com controles configurados para automação com winapp ui
  • winui-unpackaged-app: um aplicativo WinUI que é executado sem a identidade do pacote
  • winui-solution: uma solução de vários projetos que mostra como winapp run escolhe o projeto de aplicativo
  • cpp-winui-app: um aplicativo C++/WinRT WinUI empacotado (Visual Studio .vcxproj com XAML) que é executado comwinapp run

Próximas Etapas 

  • Última atualização em