Documentação e Utilização da CLI

Conclusão da Concha

Ativar a completação de tabulação para comandos, opções e valores. Consulte o guia Shell Completion para instruções de configuração.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

Init

Inicialize um diretório com o SDK do Windows, o SDK de Aplicações Windows e os recursos necessários para o desenvolvimento moderno do Windows.

winapp init [base-directory] [options]

Argumentos:

  • base-directory - Diretório base/raiz para a app/workspace (predefinido: diretório atual)

Opções:

  • --config-dir <path> - Diretório para ler/armazenar configuração (por defeito: diretório atual)
  • --setup-sdks - Modo de instalação do SDK: 'estável' (predefinido), 'pré-visualização', 'experimental' ou 'nenhum' (saltar a instalação do SDK)
  • --ignore-config, --no-config - Não use ficheiro de configuração para gestão de versões
  • --no-gitignore - Não atualize o ficheiro .gitignore
  • --use-defaults, --no-prompt - Não faça um pedido e use o padrão de todos os prompts
  • --config-only - Apenas tratar de operações de ficheiros de configuração, saltar a instalação de pacotes
  • --add-js-bindings (apenas npm) - Adicionar winapp.jsBindings à package.json e gerar ligações JS/TypeScript, sem necessidade de pedido (incompatível com --setup-sdks none)

O que faz:

  • Cria winapp.yaml ficheiro de configuração (apenas quando os pacotes SDK são geridos; ignorado com --setup-sdks none)
  • Descarrega pacotes do Windows SDK e do SDK de Aplicações Windows
  • Gera cabeçalhos e binários em C++/WinRT
  • Cria o Package.appxmanifest
  • Configura ferramentas de compilação e ativa o modo de programador
  • Atualiza o .gitignore para excluir ficheiros gerados
  • Armazena ficheiros partilháveis no diretório global de cache
  • Gera ligações JS para APIs do SDK de Aplicações Windows quando ativadas (apenas npm)

Deteção automática de projetos:

Quando init é executado sem um argumento de diretório, realiza uma pesquisa em larga escala na árvore de diretórios atual para encontrar projetos compatíveis (até 10). Tipos de projetos suportados:

  • Tauri — tauri.conf.json encontrado um nível abaixo do diretório
  • Electron — package.json com electron dependências in ou devDependencies
  • Flutter — pubspec.yaml na raiz do projeto
  • .NET — .csproj na raiz do projeto
  • Ferrugem — Cargo.toml na raiz do projeto
  • C++ — CMakeLists.txt na raiz do projeto

A pesquisa ignora diretórios normalmente ignorados (node_modules, bin, obj, .git, etc.). Quando um projeto compatível é encontrado, os subdiretórios abaixo dele não são pesquisados.

  • Se for fornecido um argumento de diretório (por exemplo, winapp init . ou winapp init path/to/project), a pesquisa é ignorada e init verifica apenas esse diretório para um projeto compatível
  • Se --use-defaults (ou --no-prompt) estiver definido sem um argumento de diretório, init ignora a pesquisa e inicializa o diretório atual de forma não interativa, avisando primeiro se não for detetado nenhum tipo de projeto conhecido (por exemplo, winapp init --use-defaults)
  • Em ambientes não interativos (stdin canalizado, CI, entrada redirecionada), init usa --use-defaults automaticamente o comportamento e emite um aviso: Non-interactive environment detected. Using default values.
  • Se o diretório atual for um projeto compatível, init avança imediatamente
  • Se exatamente um projeto for encontrado noutro local, é solicitado a confirmar
  • Se forem encontrados vários projetos, pode selecionar qual inicializar — o diretório atual está sempre disponível como opção de remédio
  • Se não forem encontrados projetos, é avisado e perguntado se deve avançar na mesma
  • Se a pesquisa atingir o limite de 10 projetos, um aviso sugere fornecer um argumento de diretório

Fluxo automático do projeto .NET:

Quando um ficheiro .csproj é encontrado no diretório de destino, init utiliza um fluxo simplificado .NET específico:

  • Valida e atualiza o TargetFramework para um TFM compatível com Windows (por exemplo, net10.0-windows10.0.26100.0)
  • Adiciona Microsoft.WindowsAppSDK e Microsoft.Windows.SDK.BuildTools como entradas NuGet PackageReference diretamente no .csproj
  • Gera Package.appxmanifest, ativos e um certificado de desenvolvimento
  • Não cria winapp.yaml nem descarrega projeções em C++ (usa dotnet restore para pacotes NuGet)

Exemplos:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

Dica: Instale SDKs após a configuração inicial

Se executaste init ( --setup-sdks none ou ignoraste a instalação do SDK) e mais tarde precisaste dos SDKs:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

--setup-sdks preview Use ou --setup-sdks experimental para versões pré-visualizadas/experimentais do SDK.

repor

Restaurar pacotes e gerar ficheiros com base na configuração existente winapp.yaml .

winapp restore [options]

Opções:

  • --config-dir <path> - Diretório contendo winapp.yaml (predefinido: diretório atual)

O que faz:

  • Lê a configuração existente winapp.yaml
  • Downloads/atualizações de pacotes SDK para versões especificadas
  • Regenera cabeçalhos e binários C++/WinRT
  • Armazena ficheiros partilháveis no diretório global de cache

Observação

Para .NET projetos iniciados com winapp init, não existe winapp.yaml. Usei-o dotnet restore para restaurar pacotes NuGet em vez disso.

Exemplos:

# Restore from winapp.yaml in current directory
winapp restore

actualização

Atualize os pacotes para as versões mais recentes e atualize o ficheiro de configuração.

winapp update [options]

Opções:

  • --setup-sdks <stable|preview|experimental|none> - Modo de instalação do SDK: stable (por defeito), preview, experimental, ou none (saltar a instalação do SDK)

O que faz:

  • Lê a configuração existente winapp.yaml no diretório atual
  • Atualiza todos os pacotes para as versões mais recentes disponíveis
  • Atualiza o winapp.yaml ficheiro com novos números de versão
  • Regenera cabeçalhos e binários C++/WinRT

Exemplos:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Crie pacotes MSIX a partir de diretórios de aplicações preparados. Requer que um ficheiro manifesto (Package.appxmanifest preferencial, appxmanifest.xml também suportado) esteja presente no diretório de destino, no diretório atual, ou passado com a --manifest opção. (correr init ou manifest generate criar um manifesto)

Passe várias pastas de entrada para criar uma .msixbundle distribuição multi-arquitetura (ver pacotes Multi-arquitetura abaixo).

winapp pack <input-folder> [input-folder...] [options]

Argumentos:

  • input-folder - Um ou mais diretórios contendo os ficheiros de aplicação para empacotar. Passe várias pastas (por exemplo, ./publish/x64 ./publish/arm64) para criar um bundle MSIX.

Opções:

  • --output <filename> - Nome do ficheiro de saída. Para pacotes individuais: <name>_<version>_<arch>.msix (voltando para <name>_<version>.msix, <name>_<arch>.msix, ou <name>.msix). Para fibrados: <name>_<version>_<arch1>_<arch2>.msixbundle.
  • --name <name> - Nome do pacote (por defeito: do manifesto)
  • --manifest <path> - Caminho para o ficheiro de manifestos (Package.appxmanifest preferencial, appxmanifest.xml também suportado; padrão: auto-deteção)
  • --cert <path> - Caminho para o certificado de assinatura (ativa a assinatura automática)
  • --cert-password <password> - Palavra-passe do certificado (por defeito: "password")
  • --generate-cert - Gerar um novo certificado de desenvolvimento
  • --install-cert - Certificado de instalação na máquina
  • --publisher <name>- Publisher para geração de certificados. Aceita um nome distinto completo X.500 ou um nome simples (automaticamente embrulhado como CN=<name>)
  • --self-contained- Agrupar o tempo de execução do SDK de Aplicações Windows
  • --skip-pri - Saltar geração de ficheiros PRI
  • --executable <path> - Caminho para o executável relativo à pasta de entrada (também --exe). Usado para resolver $targetnametoken$ marcadores de posição no manifesto.

O que faz:

  • Valida e processa ficheiros Package.appxmanifest
  • Resolve $placeholder$ tokens no manifesto (ver marcadores de Manifesto abaixo)
  • Garante que as dependências do framework estão corretamente definidas
  • Atualiza manifestos lado a lado com registos
  • Descobre e agrupa automaticamente quaisquer ficheiros que não sejam imagem referenciados no manifesto (por exemplo, AppExtension manifest.json, ficheiros de configuração) do diretório do manifesto ou da pasta de entrada se estiverem em falta no staging
  • Descobre automaticamente componentes WinRT de terceiros e regista as suas classes ativables (ver descoberta de componentes WinRT abaixo)
  • Trata da implementação autónoma do WinAppSDK
  • Assina o pacote se o certificado for fornecido

Descoberta de componentes WinRT

Ao ser empacotado, winapp pack escaneia automaticamente os pacotes NuGet definidos no winapp.yaml ou *.csproj para componentes WinRT de terceiros (por exemplo, Win2D). Analisa .winmd ficheiros para extrair nomes de classes ativables e localiza as suas DLLs de implementação. As entradas descobertas são registadas da seguinte forma:

  • Dependente do framework (por defeito): Classes ativables são adicionadas como <InProcessServer> entradas no Package.appxmanifest
  • Auto-contido (--self-contained): Classes ativables estão incorporadas em manifestos lado a lado (SxS) dentro do executável

Resolução provisória durante a embalagem:

Se o manifesto contiver $targetnametoken$ no Executable atributo:

  1. Se --executable for fornecido (caminho relativo à pasta de entrada), o marcador é substituído pelo valor especificado
  2. Caso contrário, winapp pack analisa a raiz da pasta de entrada à procura .exe de ficheiros — se for encontrado exatamente um, é usado automaticamente
  3. Se forem encontrados zero ou múltiplos .exe ficheiros, aparece um erro a pedir que especifique --executable

Exemplos:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Pacotes multi-arquitetura

Quando várias pastas de entrada são passadas, winapp pack cria-se uma .msixbundle contendo uma .msix por arquitetura:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

O comando deteta automaticamente a arquitetura de cada pasta a partir do cabeçalho PE do executável principal, valida a consistência entre fatias (Identidade, Capacidades, Dependências) e produz um <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Resolução manifesta para fibrados:

Cada fatia do feixe precisa de um manifesto. O comando resolve manifesta-se nesta ordem:

  1. --manifest <path> — Se especificado, este manifesto único é usado para todas as fatias. É ProcessorArchitecture automaticamente atualizado por fatia para corresponder à arquitetura detetada.

  2. Manifesto por pasta — Se cada pasta de entrada contiver um Package.appxmanifest (ou appxmanifest.xml), o manifesto dessa pasta é usado para a sua fatia.

  3. Alternativa do diretório atual — Se uma pasta não tiver manifesto, o comando procura Package.appxmanifest no diretório de trabalho atual e usa-o (com a arquitetura carimbada automaticamente).

Em todos os casos, o manifesto é atualizado automaticamente: os marcadores são resolvidos, as dependências são injetadas e ProcessorArchitecture o manifesto é forçado para a arquitetura detetada. Após a resolução, uma validação cross-slice assegura que a Identidade (Nome, Versão, Publisher), Capacidades e Dependências são consistentes em todas as fatias — apenas ProcessorArchitecture podem diferir. A versão do pacote definida nas fatias é atribuída à versão do bundle MSIX, exceto se for 0.0.0.0, caso em que uma versão baseada em carimbo temporal é gerada automaticamente.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

criar-identidade-debug

Criar identidade de aplicação para depuração usando empacotamento sparse. O exe mantém-se na sua localização original — Windows associa a identidade a ele através de Add-AppxPackage -ExternalLocation.

Quando usar isto ou winapp runquando usar: Usar create-debug-identity quando o exe está separado do código da sua aplicação (por exemplo, aplicações Electron onde electron.exe está inserido node_modules), ou quando testar especificamente o comportamento dos pacotes esparsos. Para a maioria dos frameworks onde o exe está na pasta de saída da build, use winapp run em vez disso — ele regista um pacote completo de layout solto e inicia a aplicação. Consulte o Guia de Depuração para uma comparação completa.

winapp create-debug-identity [entrypoint] [options]

Argumentos:

  • entrypoint - Caminho para executável (.exe) ou script que necessita de identidade

Opções:

  • --manifest <path> - Caminho para o ficheiro de manifesto da aplicação, seja Package.appxmanifest ou ou appxmanifest.xml (por defeito: auto-deteção Package.appxmanifest ou appxmanifest.xml no diretório atual)
  • --no-install - Não instalar o pacote após a criação
  • --keep-identity - Manter a identidade do manifesto as-is, sem acrescentar .debug ao nome do pacote e ao ID da aplicação

O que faz:

  • Modifica o manifesto lado a lado do executável
  • Regista pacote disperso para identidade
  • Permite depurar APIs que requerem identidade

Exemplos:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

manifesto

Gerar e gerir ficheiros Package.appxmanifest.

gerar manifesto

Gerar o Package.appxmanifest a partir de templates.

winapp manifest generate [directory] [options]

Argumentos:

  • directory - Diretório para gerar manifestos em (por defeito: diretório atual)

Opções:

  • --package-name <name> - Nome do pacote (por defeito: nome da pasta)
  • --publisher-name <name>- Publisher nome distinto (por defeito: CN=<utilizador> atual). Aceita qualquer DN X.500 válido; os nomes simples são automaticamente enrolados como CN=<nome>.
  • --version <version> - Versão (por defeito: "1.0.0.0")
  • --description <text> - Descrição (por defeito: "A Minha Candidatura")
  • --entrypoint <path> - Executável ou script de ponto de entrada
  • --template <type> - Tipo de modelo: packaged (por defeito) ou sparse
  • --logo-path <path> - Ficheiro de imagem do caminho para o logótipo
  • --if-exists <Error|Overwrite|Skip> - Comportamento quando o ficheiro manifest já existe no caminho de destino (padrão: Error)

Modelos:

Espaços reservados para manifestos

Os manifestos gerados usam $placeholder$ tokens (delimitados por sinal de dólar) que são resolvidos automaticamente no momento da embalagem:

Marcador de Posição Resolvo Exemplo
$targetnametoken$ Nome executável sem extensão Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Sempre resolvido automaticamente

Isto segue a mesma convenção usada pelos modelos de projeto do Visual Studio, pelo que os manifestos são portáteis entre ferramentas.

Como os placeholders são resolvidos:

  • winapp pack — Durante a embalagem, $targetnametoken$ é resolvido usando a --executable opção ou detetando automaticamente o single .exe na pasta de entrada. Se forem encontrados vários (ou zero) .exe ficheiros e --executable não for especificado, é apresentado um erro.
  • winapp create-debug-identity — Quando é apresentado um argumento de entrada, $targetnametoken$ é resolvido a partir dele. Sem um ponto de entrada, o marcador do executável deve já estar resolvido no manifesto.
  • winapp manifest generate --executable — Quando --executable é fornecido, os metadados do manifesto (versão, descrição) e ícones são extraídos do executável, mas o manifesto gerado ainda utiliza $targetnametoken$.exe; este marcador de posição é resolvido posteriormente (por exemplo, winapp pack ou winapp create-debug-identity).

PS: Manter $targetnametoken$ no seu manifesto check-in evita codificar nomes executáveis rígidos e funciona tanto com compilações winapp pack como Visual Studio.

Exemplos:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

Manifest Add-Alias

Adicione um alias de execução (uap5:AppExecutionAlias) a um Package.appxmanifest. Isto permite iniciar a aplicação empacotada a partir da linha de comandos, escrevendo o nome do alias.

winapp manifest add-alias [options]

Opções:

  • --name <alias> - Nome do pseudónimo (por exemplo myapp.exe, ). Padrão: inferido a partir do Executable atributo no manifesto.
  • --manifest <path> - Caminho para Package.appxmanifest (por defeito: pesquisa no diretório atual)
  • --app-id <id> - ID de aplicação para adicionar o alias a (por defeito: primeiro elemento de aplicação)

O que faz:

  • Lê o manifesto e infere o alias a partir do Executable atributo (preservando marcadores como $targetnametoken$.exe)
  • Adiciona a uap5 declaração do namespace se já não estiver presente
  • Adiciona um <Extensions> bloco com <uap5:AppExecutionAlias> dentro do elemento de aplicação alvo
  • Se o alias já existir, reporta-o e sai com sucesso

Exemplos:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifest atualizar ativos

Gerar todos os ativos de imagem MSIX necessários a partir de uma única imagem de origem.

winapp manifest update-assets <image-path> [options]

Argumentos:

  • image-path - Caminho para ficheiro de imagem de origem (PNG, JPG, SVG, ICO, GIF, BMP, etc.)

Opções:

  • --manifest <path> - Caminho para o ficheiro Package.appxmanifest (por defeito: pesquisar diretório atual)
  • --light-image <path> - Caminho para uma imagem de origem separada para variantes de tema de luz

Description:

Toma uma única imagem de origem e gera um conjunto abrangente de ativos de imagem MSIX com base nas referências de ativos do manifesto:

Para cada ativo referenciado no manifesto:

  • 5 variantes de escala — base (sem sufixo), .scale-125, .scale-150, .scale-200, .scale-400

Para o ícone da aplicação (Square44x44Logótipo / AppList, base 44×44):

  • 14 variantes de tamanho alvo banhadas — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
  • 14 variantes de tamanho alvo não placadas — .targetsize-{size}_altform-unplated

Additionally:

  • app.ico — ficheiro ICO multi-resolução (16, 24, 32, 48, 256) para integração shell. Se um ficheiro existente .ico for encontrado no diretório de ativos (por exemplo, AppIcon.ico a partir de um modelo de projeto), ele é substituído no local em vez de criar um duplicado

Com --light-image:

  • Variantes de tamanho alvo do tema de luz — .targetsize-{size}_altform-lightunplated (ícone da app)
  • Variantes de escala com tema de luz — .scale-{factor}_altform-colorful_theme-light (azulejos, logótipo da loja)

Suporte SVG: Os ficheiros SVG são totalmente suportados como imagens de origem. São renderizados como vetores diretamente em cada tamanho alvo, produzindo resultados pixel-perfeitos em todas as resoluções.

O comando escala as imagens proporcionalmente, mantendo a proporção de aspeto, centrando-as com fundos transparentes quando necessário. Os ativos são guardados no diretório Assets relativamente à localização do manifesto.

Exemplos:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

execução

Crie um pacote de layout solto a partir de uma pasta de saída de compilação, regista-o com Windows usando a API Windows.Management.Deployment.PackageManager e inicie a aplicação — simulando uma instalação completa do MSIX para depuração. Devolve o ID do processo para anexo do depurador.

Este é o comando preferido para depuração com identidade de pacote para a maioria dos frameworks (.NET, C++, Rust, Flutter, Tauri). Ao contrário create-debug-identity de que regista um pacote esparso para um único exe, winapp run regista toda a pasta como um pacote de layout solto, tal como numa instalação real do MSIX. Consulte o Guia de Depuração para fluxos de trabalho comuns de depuração.

winapp run <input-folder> [options]

Argumentos:

  • input-folder - Diretório contendo a aplicação a executar (obrigatório)

Opções:

  • --manifest <path> - Caminho para Package.appxmanifest (padrão: auto-deteção a partir da pasta de entrada ou diretório atual)
  • --output-appx-directory <path> - Diretório de saída para o pacote de layout solto (predefinido: AppX dentro do diretório da pasta de entrada)
  • --args <string> - Argumentos de linha de comandos para passar à aplicação. Alternativamente, use -- seguido de argumentos para evitar escapar-se (por exemplo, winapp run . -- --flag value).
  • --no-launch - Apenas criar a identidade de depuração e registar o pacote sem iniciar a aplicação
  • --with-alias - Iniciar a aplicação usando o seu alias de execução em vez da ativação AUMID. A aplicação corre no terminal atual com o stdin/stdout/stderr herdado. Requer um uap5:ExecutionAlias no manifesto (usar winapp manifest add-alias para adicionar um). Não pode ser combinado com --no-launch. Não pode ser combinado com --json.
  • --debug-output - Capturar OutputDebugString mensagens e exceções de primeira oportunidade da aplicação lançada. O ruído do framework (WinUI, COM, DirectX) é filtrado da saída da consola; O ficheiro de registo completo regista tudo. Se a aplicação crashar, captura automaticamente um minidump e analisa-o para mostrar o tipo de exceção, a mensagem e o traço da pilha com o ficheiro de origem:números de linha (resolvido a partir dos PDBs na pasta de saída da compilação). As falhas geridas (.NET) são analisadas instantaneamente sem ferramentas externas. Crashes nativos (C++/WinRT) mostram nomes e deslocamentos de módulos. Quando a aplicação com falha é uma aplicação WinUI 3 (Microsoft.UI.Xaml.dll está carregada), uma passagem extra de triagem de exceções armazenadas é executada automaticamente para repor o HRESULT de origem, a sua cadeia ErrorContext e a pilha nativa completa de despacho XAML; os componentes de depuração necessários são descarregados na primeira utilização (ver Debugging, overridable via a WINAPP_DBGTOOLS_DIR variável de ambiente). Apenas um depurador pode ser ligado a um processo de cada vez, pelo que outros depuradores (Visual Studio, VS Code) não podem ser usados simultaneamente. Usa --no-launch em vez disso se precisares de anexar um depurador diferente. Não pode ser combinado com --no-launch. Não pode ser combinado com --json.
  • --symbols - Descarregue símbolos PDB do Microsoft Symbol Server para uma análise nativa de falhas mais rica com nomes de funções resolvidos. Utilizado apenas com --debug-output. Se for omitido e ocorrer um crash nativo, a saída sugerirá adicionar esta bandeira. Este flag também melhora a pilha de triagem de exceções armazenadas do WinUI para aplicações WinUI 3. A primeira corrida descarrega símbolos e armazena-os em cache localmente; As execuções subsequentes utilizam a cache.
  • --unregister-on-exit - Desregistar o pacote de desenvolvimento após o encerramento da aplicação. Apenas remove pacotes registados em modo de desenvolvimento. Não pode ser combinado com --no-launch.
  • --detach - Iniciar a aplicação e regressar imediatamente, sem esperar que saia. Útil para CI/automação, onde precisas de interagir com a aplicação após o lançamento. Imprime o PID para stdout (ou em JSON com --json). Não pode ser combinado com --no-launch, --debug-output, --with-alias, ou --unregister-on-exit.
  • --clean - Remover os dados da aplicação do pacote existente (LocalState, definições, etc.) antes de o reimplantar. Por defeito, os dados da aplicação são preservados durante as reimplantações.
  • --json - Formatar a saída como JSON para consumo programático (por exemplo, CI/automação). Útil para --detach capturar o PID. Não pode ser combinado com --with-alias ou --debug-output.

Persistência dos dados da aplicação:

Por defeito, winapp run preserva os dados da sua aplicação (LocalState, RoamingState, Settings, etc.) ao reimplantar. Se a sua aplicação gravar dados no ApplicationData.Current.LocalFolder contexto do pacote ou Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dentro dele, esses dados sobreviverão através das winapp run invocações.

Use --clean quando precisar de um novo começo (por exemplo, para reiniciar o estado corrompido ou testar o comportamento da primeira execução).

O que faz:

  • Localiza ou gera o Package.appxmanifest
  • Cria e regista uma identidade de depuração usando um pacote de layout frouxo
  • Calcula o ID do Modelo de Utilizador da Aplicação (AUMID)
  • Lança a aplicação usando a identidade registada (a menos que --no-launch seja especificado)
  • Imprime o ID do processo (PID) para anexo do depurador

Exemplos:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Propriedades do MSBuild (pacote NuGet):

Ao usar o pacote NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run invoca automaticamente winapp run. As seguintes propriedades do MSBuild podem ser definidas em your .csproj to control behavior:

Property Predefinição Descrição
EnableWinAppRunSupport true Ativar/desativar a funcionalidade de suporte à execução
WinAppLaunchArgs (vazio) Argumentos para passar à aplicação no lançamento
WinAppRunUseExecutionAlias false Lançamento via alias de execução em vez de ativação AUMID
WinAppRunNoLaunch false Regista apenas a identidade sem iniciar
WinAppRunDebugOutput false Capturar OutputDebugString mensagens e exceções de primeira oportunidade. Apenas um depurador pode ser ligado de cada vez (previne o VS/VS Code). Use WinAppRunNoLaunch antes para anexar um depurador diferente. 
<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

desregisto

Desregistar um pacote de desenvolvimento sideloaded. Apenas remove pacotes que foram registados em modo de desenvolvimento (por exemplo, via winapp run ou create-debug-identity). Os pacotes instalados na loja ou instalados no MSIX nunca são removidos.

winapp unregister [options]

Opções:

  • --manifest <path> - Caminho para Package.appxmanifest (padrão: deteção automática a partir do diretório atual)
  • --force - Saltar a verificação do diretório de localização de instalação e cancelar o registo mesmo que o pacote tenha sido registado de uma árvore de projeto diferente
  • --json - Saída de formato como JSON

O que faz:

  • Lê o nome do pacote no manifesto
  • Pesquisas por ambos {name} e {name}.debug pacotes (a variante de depuração é criada por create-debug-identity)
  • Verifica se cada pacote estava registado em modo de desenvolvimento (IsDevelopmentMode == true)
  • Verifica que a localização de instalação do pacote está na árvore de diretórios atual (a menos que --force)
  • Desregistar pacotes correspondentes

Exemplos:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# JSON output for scripting
winapp unregister --json

cert

Gerar, inspecionar e instalar certificados de desenvolvimento.

Gerar certificado

Gerar certificados de desenvolvimento para assinatura de pacotes.

winapp cert generate [options]

Opções:

  • --manifest <Package.appxmanifest> - Extrair informações do editor a partir do Package.appxmanifest
  • --publisher <name>- Publisher para o certificado. Aceita um nome distinto completo X.500 (por exemplo, CN=Contoso, O=Contoso Ltd, C=US) ou um nome simples que é automaticamente enrolado como CN=<name>
  • --output <path> - Caminho de ficheiro de certificado de saída (suporta caminhos absolutos e relativos)
  • --password <password> - Palavra-passe do certificado (por defeito: "password")
  • --valid-days <valid-days> - Número de dias em que o certificado é válido (padrão: 365)
  • --install - Instalar o certificado na loja local de máquinas após a geração
  • --if-exists <Error|Overwrite|Skip> - Definir comportamento se o ficheiro de certificado já existir (por defeito: Erro)
  • --export-cer - Exportar um .cer ficheiro (apenas chave pública) juntamente com o .pfxarquivo . Útil para distribuir o certificado público separadamente para instalação do trust.
  • --json - Formatar a saída como JSON para consumo programático. Os erros também são devolvidos como JSON ({"error": "..."}).

Informação da certificação

Mostrar detalhes do certificado a partir de um ficheiro PFX. Útil para verificar se um certificado corresponde ao seu manifesto antes de assinar.

winapp cert info <cert-path> [options]

Argumentos:

  • cert-path - Caminho para o ficheiro de certificado (PFX)

Opções:

  • --password <password> - Palavra-passe para o ficheiro PFX (por defeito: "password")
  • --json - Saída de formato como JSON

Instalação do certificado

Instalar o certificado no repositório de certificados da máquina.

winapp cert install <cert-path> [options]

Argumentos:

  • cert-path - Caminho para o ficheiro de certificado a instalar

Exemplos:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

símbolo

Assinar pacotes e executáveis MSIX com certificados.

winapp sign <file-path> [options]

Argumentos:

  • file-path - Caminho para o pacote MSIX ou executável para assinar

Opções:

  • --cert <path> - Caminho para a assinatura do certificado
  • --cert-password <password> - Palavra-passe do certificado (por defeito: "password")

Exemplos:

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

create-external-catalog

Gerar um CodeIntegrityExternal.cat ficheiro de catálogo contendo hashes de ficheiros executáveis a partir de diretórios especificados. Este catálogo é usado com a flag TrustedLaunch nos manifestos de pacotes esparsos do MSIX (AllowExternalContent) para permitir a execução de ficheiros externos não incluídos no próprio pacote.

Isto é semelhante a como signtool.exe se cria AppxMetadata\CodeIntegrity.cat ao assinar um pacote MSIX, mas gera um catálogo externo para uso com embalagens de localização escassa/externa.

winapp create-external-catalog <input-folder> [options]

Argumentos:

  • input-folder - Um ou mais diretórios contendo ficheiros executáveis a processar. Separe vários diretórios com ponto e vírgula (por exemplo, "dir1;dir2")

Opções:

  • --recursive, -r - Incluir ficheiros de subdiretórios
  • --use-page-hashes - Incluir hashes de página na geração do catálogo (produz um catálogo maior com dados de hash por página)
  • --compute-flat-hashes - Incluir hashes em ficheiros planos ao gerar o catálogo
  • --if-exists <Error|Overwrite|Skip> - Comportamento quando o ficheiro de saída já existe (padrão: Error)
  • --output, -o - Caminho do ficheiro de catálogo de saída. Se não for especificado, CodeIntegrityExternal.cat é criado no diretório atual. Se for especificado um diretório, o nome de ficheiro predefinido é adicionado.

O que faz:

  • Analisa diretórios especificados para ficheiros executáveis (binários PE com secções de código)
  • Gera um Ficheiro de Definição de Catálogo (CDF) com hashes de todos os executáveis encontrados
  • Utiliza APIs Windows CryptoCAT para produzir o ficheiro de catálogo .cat
  • Ficheiros não executáveis (por exemplo, .txt, .dll sem secções de código) são automaticamente ignorados

Exemplos:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Quando usar:

Use este comando ao construir um pacote MSIX esparso que utilize o TrustedLaunch para verificar executáveis externos. O fluxo de trabalho típico é:

  1. winapp manifest generate --template sparse — Criar um manifesto esparso com AllowExternalContent
  2. winapp create-external-catalog ./bin — Gerar o catálogo de integridade do código para os executáveis da sua aplicação
  3. winapp pack — Empacotar o manifesto, os ativos e o catálogo num MSIX

ferramenta

Acess diretamente às ferramentas do SDK do Windows. Utiliza ferramentas disponíveis em Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Ferramentas disponíveis:

  • makeappx - Criar e manipular pacotes de aplicações
  • signtool - Assinar ficheiros e verificar assinaturas
  • mt - Ferramenta de manifestação para conjuntos lado a lado
  • E outras ferramentas Windows SDK do Microsoft.Windows. SDK. BuildTools

Exemplos:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

armazenar

Executa um comando CLI do Microsoft Store Developer. Este comando irá descarregar a CLI do Microsoft Store Developer se ainda não estiver descarregada. Saiba mais sobre o Developer CLI Microsoft Store .

winapp store [args...]

Argumentos:

O que faz:

  • Garante que a CLI do Desenvolvedor Microsoft Store (msstore) está descarregada e disponível no seu sistema.
  • Encaminha todos os argumentos para a msstore CLI.
  • Executa o comando que mostra a saída diretamente no teu terminal.

Exemplos:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Obtenha caminhos para os componentes instalados do SDK do Windows.

winapp get-winapp-path [options]

O que devolve:

  • Caminhos para .winapp o diretório do espaço de trabalho
  • Diretórios de instalação de pacotes
  • Localizações de cabeçalhos geradas

Ligações de geração de nós

(Disponível apenas no pacote NPM) Gerar ligações JS para APIs do SDK de Aplicações Windows. As ligações são declaradas por um "winapp": { "jsBindings": {...} } namespace em package.json e escritas em .winapp/bindings/.

npx winapp node generate-bindings [options]

Opções:

  • --verbose, -v - Ativar a saída de codegen verbosa por ficheiro
  • --quiet, -q - Suprimir o progresso e a produção informativa

O que faz:

  • Lê o bloco de e o winmds.lock.json escrito pelo último winapp restore, depois emite ligações digitadas .js + .d.ts em package.jsonwinapp.jsBindings.winapp/bindings/
  • Não se modifica package.json — é um regenerador passivo. Adicionar o bloco winapp.jsBindings e a @microsoft/dynwinrt dependência de tempo de execução ocorre durante winapp init o período em que as ligações JS estão ativadas; este comando falha rapidamente se o bloco estiver ausente
  • Avisa (mas não escreve) se @microsoft/dynwinrt estiver em falta nas suas dependências — run npm install after init o adicionou

Observação

As ligações são apenas npm — requerem invocação via npx winapp (o @microsoft/winappcli pacote npm); a CLI winget autónoma não as apresenta. Execute winapp init interativamente e opte, ou use winapp init . --use-defaults --add-js-bindings, antes de usar este comando para regenerar bindings. Se editareswinapp.yaml, corre npx winapp restore para atualizar as dependências do Windows antes de regenerar.

Exemplos:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Consulte o guia de ligações JS para o fluxo de trabalho de ponta a ponta e as winapp.jsBindings opções de configuração.

Node Create-Addon

(disponível apenas no pacote NPM) Gerar templates de addons nativos em C++ ou C# com Windows SDK e integração SDK de Aplicações Windows.

npx winapp node create-addon [options]

Opções:

  • --name <name> - Nome do addon (por defeito: "nativeWindowsAddon")
  • --template - Selecionar o tipo de addon. As opções são cs ou cpp (por defeito: cpp)
  • --verbose - Ativar a saída verbosa

O que faz:

  • Cria diretório de addons com ficheiros modelo
  • Gera binding.gyp e addon.cc com exemplos de SDK Windows
  • As instalações exigiam dependências npm (nan, node-addon-api, node-gyp)
  • Adiciona um script de build à package.json

Exemplos:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

Nó adição-eletrão-debug-identidade

(Disponível apenas no pacote NPM) Adicione identidade de aplicação ao processo de desenvolvimento do Electron usando embalagens esparsas. Requer um Package.appxmanifest (cria um com winapp init ou winapp manifest generate se não tiveres).

Importante

Existe um problema conhecido com aplicações Electron com embalagens esparsas que faz com que a aplicação crashe ao iniciar ou não renderize o conteúdo web. O problema foi resolvido no Windows, mas ainda não se propagou para dispositivos Windows externos. Se estiver a ver este problema depois de ligar add-electron-debug-identity, pode desativar o sandboxing na sua aplicação Electron para efeitos de depuração com o --no-sandbox flag. Este problema não afeta a embalagem completa do MSIX.

Para desfazer a identidade de depuração do Electron, use winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Opções:

Option Descrição
--manifest <path> Caminho para o Package.appxmanifest personalizado (padrão: Package.appxmanifest no diretório atual)
--no-install Não instale nem modifique dependências; configure apenas a identidade de depuração do Electron
--keep-identity Mantenha a identidade do manifesto como está, sem adicionar .debug ao nome do pacote e ao identificador da aplicação.
--verbose Ativar saída detalhada

O que faz:

  • Registos depuram identidade para electron.exe processo
  • Permite testar APIs que exigem identidade no desenvolvimento Electron
  • Utiliza o Package.appxmanifest existente para configuração de identidade

Exemplos:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

nó clear-electron-debug-identity

(Disponível apenas no pacote NPM) Remova a identidade do pacote do processo de depuração do Electron restaurando o electron.exe original a partir do backup.

npx winapp node clear-electron-debug-identity [options]

Opções:

Option Descrição
--verbose Ativar saída detalhada

O que faz:

  • Restaura electron.exe a partir do backup criado por add-electron-debug-identity
  • Remove os ficheiros de backup após a restauração
  • Devolve o Electrão ao seu estado original sem identidade de pacote

Exemplos:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Opções Globais

Todos os comandos suportam estas opções globais:

  • --verbose, -v - Ativar saída verbosa para registos detalhados
  • --quiet, -q - Suprimir mensagens de progresso
  • --help, -h - Mostrar ajuda com comandos

Diretório Global de Cache

O Winapp cria um diretório para armazenar ficheiros em cache que podem ser partilhados entre vários projetos.

Por defeito, o winapp cria um diretório em $UserProfile/.winapp como diretório global de cache.

Para usar uma localização diferente, define a WINAPP_CLI_CACHE_DIRECTORY variável de ambiente.

Em cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

No PowerShell e pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

O Winapp criará este diretório automaticamente quando executares comandos como init ou restore.

Verificações de Atualização

A linha de comando winapp verifica periodicamente novas versões e apresenta um aviso de uma linha quando uma atualização está disponível. Esta verificação corre em segundo plano e não adiciona latência aos comandos.

As verificações de atualização são automaticamente desativadas em ambientes CI (GitHub Actions, Azure Pipelines, etc.).

Para desativar manualmente as verificações de atualização, defina a WINAPP_CLI_UPDATE_CHECK variável ambiente para 0.

Em cmd:

set WINAPP_CLI_UPDATE_CHECK=0

No PowerShell e pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Para tornar isto permanente:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

ui

Inspecione e interaja com interfaces de utilizadores de aplicações Windows em execução usando Automatização da Interface de Utilizador (UIA).

winapp ui [command] [options]

Comandos:

  • status - Ligar à aplicação e mostrar informações
  • inspect - Árvore de elementos de visualização
  • search - Encontrar elementos por seletor
  • get-property - Propriedades dos elementos de leitura
  • get-text / get-value - Ler valor/texto a partir do elemento (TextPattern, ValuePattern ou Name)
  • screenshot - Capturar janela/elemento como PNG (captura automaticamente os diálogos separadamente)
  • record- Gravar uma região de janela/elemento num vídeo MP4 H.264 (Windows Graphics Capture + Media Foundation)
  • invoke - Ativar elemento (clicar, alternar, expandir)
  • click - Clique no elemento via simulação de rato (para controlos que não suportam invocação)
  • hover - Mover o rato para o elemento para ativar dicas de ferramenta, flyouts e estados de hover (dwell padrão: 800ms)
  • drag - Arrastar o rato de um ponto para outro, por seletor de elementos ou coordenadas do ecrã x,y (reordenar, redimensionar, deslizar, arrastar e largar)
  • touch- Injetar gestos táteis sintéticos (toque, duplo toque, pressão longa, deslizar, beliscar, esticar) no centro de um elemento ou coordenadas do ecrã x,y
  • pen - Injetar entrada sintética de caneta/caneta — toques e traços de tinta com modo de pressão, inclinação e borracha configuráveis
  • send-keys - Enviar entrada sintética do teclado (teclas nomeadas, combos, raw vk=0xNN, ou texto literal) para uma janela
  • set-value - Definir valor no elemento editável (texto, número); recorre ao LegacyIAccessible put_accValue para controlos de edição rica apenas com TextPattern
  • focus - Mover o foco do teclado
  • scroll-into-view - Elemento de pergaminho visível
  • wait-for - Esperar pelo estado do elemento
  • list-windows - Listar todas as janelas de uma aplicação
  • get-focused - Reportar o elemento atualmente focado

Opções:

  • -a, --app <app> - Aplicação alvo (nome, título ou PID)
  • -w, --window <hwnd> - Janela-alvo por HWND (estável)

Registo UI

Grave a janela alvo — ou a região de um único elemento — num vídeo H.264 MP4. Os frames são capturados através do Windows Graphics Capture (com um PrintWindow de reserva) e codificados incrementalmente com o Media Foundation, pelo que gravações longas nunca ficam em buffer na memória.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

Opções de gravação:

  • --duration-sec <n> - Duração da gravação em segundos. 0 regista até Ctrl+C (padrão 0).
  • --fps <n> - Frames por segundo para capturar (por defeito 15).
  • --max-edge <px> - Redução de escala para que a aresta mais longa tenha no máximo este número de píxeis (0 = sem redução de escala).
  • --capture-screen - Capturar a partir do ecrã para incluir sobreposições/pop-ups (pode capturar janelas a ocluir).
  • -o, --output <path> - Caminho de saída .mp4 (por defeito para recording-<timestamp>-<guid>.mp4).

Com --json, emite um UiRecordResult envelope que inclui a saída path, frames, width, height, fileSize, codec ("h264"), e mode — o caminho de captura efetivamente usado (wgc, printwindow, ou screen).

Limitação conhecida: gravar um elemento específico dentro de um pop-up que é renderizado na sua própria janela de topo (WinUI/XAML, dica de ensino, dica de ferramenta) pode capturar a janela principal subjacente em vez disso. Grava toda a janela ou usa ui screenshot --capture-screen para fotos pop-up. Rastreado no #646.

Para documentação completa, consulte docs/ui-automation.md.

  • Last updated on