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
• --exe <path> - Caminho para o executável da aplicação. Requer --sparse. Gera um manifesto esparso apenas de identidade para o exe, em vez de uma configuração completa de pacote/SDK.
• --sparse - Gerar um manifesto de identidade esparso (appxmanifest.xml) para um ex-executante de ambiente de trabalho existente. Ignora a instalação do SDK/pacote. Utilizar com --exe.
• --name <name> - Sobrescrever o nome do pacote (apenas esparso; padrão: inferido a partir do exe)
• --publisher <CN> - Substituir o editor CN (apenas esparso; padrão: inferido a partir do nome da empresa do exe)
• --output-dir <path> - Diretório para escrever o manifesto esparso e Assets/ (apenas esparso; por defeito: uma sparse/ pasta no diretório atual)
• --force - Sobrescrever um existente appxmanifest.xml no diretório de destino (apenas esparso). Sem isso, o init falha em vez de substituir um manifesto/ativos existentes.
• --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)

Modo identidade esparso (--exe + --sparse):

Gera um manifesto de pacote esparso apenas de identidade para um executável de desktop existente — o primeiro passo do fluxo de trabalho de empacotamento esparso. Ao contrário do fluxo completo init , isto ignora toda a instalação de SDK/pacotes (pacotes de identidade esparsos não têm dependências de SDK) e gera apenas um manifesto e ativos de placeholder.

• Infere o nome do pacote, publicador, descrição e versão a partir do exe através FileVersionInfo de (sobrescrever com --name, --publisher, ou interativamente)
• Escreve appxmanifest.xml (com o nome do exe substituído em Executable) mais uma Assets/ pasta numa sparse/ pasta no diretório atual (ou --output-dir)
• Usa --use-defaults/--no-prompt para saltar os prompts interativos de substituição (compatível com CI)
• --exe sem --sparse é um erro

Os ativos são externos. O sparse .msix é apenas de identidade: os gerados Assets/ são resolvidos a partir do diretório de instalação da aplicação (a localização de conteúdo externo) em tempo de execução, não agrupados no .msixarquivo . Implemente-os juntamente com a sua aplicação.

Passos seguintes a winapp init --exe <exe> --sparseseguir: winapp pack <appxmanifest.xml> para construir a identidade .msix, então winapp embed-identity <exe>. Consulte o Guia de Embalagem Esparsa para o guia completo.

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

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

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.

novo

Crie uma nova aplicação WinUI a partir de um modelo oficial do SDK de Aplicações Windowsdotnet new. Interativo por defeito; usa automaticamente os valores predefinidos em ambientes não interativos.

winapp new [options]

Opções:

• -t, --template <short-name> - Nome curto modelo (ex.: winui, winui-navview, winui-mvvm, winui-lib, winui-unittest). Validado contra o pacote instalado em tempo de execução; Corre winapp new --list para ver tudo. Padrão: winui (aplicação em branco).
• -n, --name <name> - Nome da nova aplicação/projeto (por defeito: derivado de --output, else WinUIApp)
• -o, --output <path> - Diretório para criar a aplicação em (por defeito: ./<name>)
• --use-defaults, --no-prompt - Não solicite; use os valores predefinidos (modelo em branco, nome de --output/--name, e manter o pacote de templates instalado em vez de o atualizar)
• --force - Andaime mesmo que o diretório de saída já contenha ficheiros
• --template-version <latest|installed|version> - Versão do pacote de templates WinUI: latest instala o pacote mais recente publicado, installed mantém o que já está descarregado (sem rede) ou fixa uma versão explícita como 1.2.3. Predefinido: instalar o mais recente quando não houver pack presente, caso contrário será solicitado atualizar um pack obsoleto (guardado as-is em --use-defaults).
• --list - Listar os modelos disponíveis do WinUI e sair (instala primeiro o pacote mais recente se não estiver instalado nenhum)
• --json - Saída de formato como JSON

Modelos:

A lista de modelos é lida em direto a partir do pacote instalado, por isso reflete sempre a versão que tens — corre winapp new --list para ver o conjunto atual. Modelos comuns:

O nome curto canónico de cada modelo é a primeira lista de alias dotnet new para ele; qualquer alias listado (por exemplo, winui3, wasdk-single) também é aceite. Quando executado dentro de um projeto WinUI existente, dotnet new também surgem modelos de itens (por exemplo, uma página em branco), que winapp new se adicionam ao projeto atual em vez de criar um novo.

Versionamento de templates packs:

winapp new Já não fixa uma versão específica do pack template. Se não houver um pack instalado, instala o mais recente. Se um pack mais antigo já estiver instalado, verifica o feed e, quando existe um mais recente, pergunta se deve atualizar — exceto em runs/--use-defaults não interativos, que mantêm o pack instalado. Costumava --template-version latest pegar sempre no pacote mais recente sem que me pedissem, ou --template-version installed usar sempre o pack descarregado sem verificar a rede. Passar uma versão explícita (por exemplo, --template-version 1.2.3) instala sempre exatamente essa versão — reinstalando mesmo quando já existe um pacote mais recente — por isso a estrutura é reproduzível entre máquinas.

O que faz:

• Verifica que o SDK .NET está instalado (falha rapidamente com orientação se estiver em falta — winapp não instala as cadeias de ferramentas)
• Instala ou atualiza o pacote oficial de templates WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) a pedido
• Enumera os templates disponíveis do pacote instalado e delega a estrutura para dotnet new <short-name>

Os modelos de aplicações WinUI já incluem a embalagem e identidade do Windows (Package.appxmanifest), pelo que não é necessário nenhum passo separadowinapp init. Para modelos de aplicações, usa winapp run para construir e lançar a aplicação. O winui-lib modelo produz uma biblioteca de classes para consultar a partir de um projeto de aplicação (não tem manifesto de aplicação). O winui-unittest modelo é uma aplicação MSTest embalada cujos testes correm quando a aplicação é lançada (winapp run) — não via dotnet test. winapp newApoia-se no framework de destino do SDK .NET instalado e imprime o passo seguinte apropriado para o modelo que escolher.

Passe o flag global --verbose (-v) para ecoar todas as invocações subjacentes dotnet (consulta de pack, verificação de atualização, instalação, dotnet new list, scaffold) juntamente com a sua saída completa — útil para diagnosticar problemas de template-pack ou de andaime.

Exemplos:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

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

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. Para pacotes de identidade esparsos, passe diretamente um ficheiro esparso appxmanifest.xml em vez de uma pasta (ver pacotes de identidade esparsa abaixo).

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

Pacotes de identidade esparsos

Quando a entrada é um ficheiro esparso appxmanifest.xml (que declara <uap10:AllowExternalContent>true</uap10:AllowExternalContent> sob <Properties>) em vez de uma pasta, winapp pack constrói apenas uma identidade.msix — empacota apenas o manifesto, sem binários ou ativos de aplicação. Este é o passo 2 do fluxo de trabalho de empacotamento esparso.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

• A saída está por defeito no <PackageName>.identity.msix diretório atual (substitui com --output).
• A assinatura só acontece quando --cert (ou --generate-cert) é fornecido.
• Se, em vez disso, passar uma pasta cujo manifesto declara AllowExternalContent, aplica-se o comportamento existente de empacotamento de pastas, mas winapp pack avisa se encontrar assets (.ico/.jpg/.png) ou binários (.exe.dll//.so) — para pacotes esparsos estes pertencem à localização externa, não dentro do ..msix

Depois de empacotar, execute winapp embed-identity <exe> e registre o pacote no seu instalador com Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Consulte o Guia de Embalagens Esparsas.

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

Identidade embed-

Ligue uma aplicação de ambiente de trabalho ao seu pacote de identidade simples , incorporando o <msix> elemento no manifesto lado a lado (fusão) da aplicação. Este é o passo 3 do fluxo de trabalho de empacotamento esparso — indica ao Windows a que pacote de identidade pertence o exe em execução.

winapp embed-identity <target> [options]

Argumentos:

• target - O ficheiro a atualizar. Detetado automaticamente por extensão:
  • .exe (modo EXE) — incorpora o <msix> elemento diretamente no manifesto lado a lado do exe, usando mt.exe.
  • .xml / .manifest (modo XML) — insere ou substitui o <msix> elemento num ficheiro externo de manifesto SxS (criado caso não exista). Reconstrua a sua aplicação depois para que o manifesto atualizado fique incorporado no binário.

Opções:

• --manifest <path> - Caminho para a identidade esparsa appxmanifest.xml a ler (pacoteNome, publicador, applicationId). Quando omitido, o comando pesquisa primeiro numa sparse/ pasta ao lado do destino, depois no diretório atual, depois no diretório do destino e no diretório atual, para appxmanifest.xml.

Exemplos:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

Este comando é idempotente: reexecutá-lo substitui qualquer elemento existente <msix> em vez de o duplicar.

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:

• packaged - Manifesto padrão de aplicação empacotada
• sparse - Manifesto de aplicação usando empacotamento de localização esparsida/externa

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:

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.

winapp run Opera num de dois modos, escolhidos automaticamente a partir da entrada:

• Modo pasta — a entrada é uma pasta build-output (contém um Package.appxmanifest/AppxManifest.xml).
• Modo Project — a entrada é um .csproj, uma .sln/.slnx solução ou um diretório que contém um. winapp run constrói o projeto e lança-o, suportando tanto aplicações WinUI empacotadas como não empacotadas . Veja o modo Project abaixo.

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>] [options]

Argumentos:

• input - A aplicação a executar: uma pasta build-output (modo pasta), um .csproj projeto, uma .sln/.slnx solução ou um diretório contendo um desses ao seu nível superior (modo projeto; o diretório não é pesquisado recursivamente). Use . para construir/executar o projeto no diretório atual. Opcional — por defeito para o diretório atual quando omitido (corresponde dotnet run).

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

Modo Project (projetos .NET SDK)

Quando a entrada é um .csproj, uma.slnx/.sln solução, ou um diretório contendo um (incluindo .),winapp run constrói o projeto com dotnet build e depois lança-o. Suporta aplicações WinUI tanto empacotadas como não empacotadas, e instala o Aplicação do Windows Runtime de arquitetura correspondente que a aplicação necessita antes do lançamento.

Entrada da solução: aponta winapp run para um .sln.slnx/(ou um diretório que o contenha — prefere-se uma solução a ficheiros soltos.csproj) e resolve o projeto da aplicação executável, depois constrói-o com $(SolutionDir) e as propriedades irmãs Solution* definidas, para que os projetos que dependam deles constroem como fazem no Visual Studio. Regras de resolução:

• Os projetos de teste são ignorados quando se seleciona automaticamente, por isso uma solução que contém uma aplicação mais os seus testes resolve-se para a aplicação sem --project necessidade de ser necessário. (Um projeto de teste WinUI é, ele próprio, uma aplicação empacotada, por isso o tipo de saída sozinho não o distingue.)
• Se o único projeto executável for um projeto de teste, ele corre.
• Se existirem mais do que um projeto de aplicação executável, winapp run não se adivinha um projeto de arranque — dá erro ao listar os candidatos. Use --project <name> para escolher, o que é sempre respeitado, incluindo para selecionar um projeto de teste.

Empacotado vs. não empacotado é detetado automaticamente pela propriedade MSBuild efetiva WindowsPackageType do projeto (nunca pela presença manifesta):

• Empacotado (WindowsPackageType=MSIX, o padrão empacotado do WinUI) — compila, depois regista a saída da compilação como um pacote de layout solto e lança via AUMID (o mesmo pipeline do modo de pasta).
• Unpackaged (WindowsPackageType=None) — compila, garante que o Aplicação do Windows Runtime dependente do framework está instalado, e depois lança diretamente o build.exe. Force isto para um projeto empacotado com -p WindowsPackageType=None.

O modo Project requer o SDK .NET 8.0.100 ou mais recente (para MSBuild--getProperty).

Opções do modo Project (ignoradas no modo de pasta):

• -c, --configuration <name> - Configuração de construção. Padrão: Debug.
• --arch <x64|arm64|x86> - Arquitetura alvo. Padrão: a arquitetura atual do processo. Determina tanto o build RID como a arquitetura do Aplicação do Windows Runtime que é instalado.
• -r, --runtime <rid>- Identificador de runtime .NET do alvo (por exemplo, win-x64). O modo Project utiliza apenas a arquitetura do RID, constrói sempre o canónico win-<arch>, e rejeita RIDs que não sejam do Windows (por exemplo, linux-x64). A sua arquitetura sobrepõe-se --archa .
• -f, --framework <tfm> - Nome de framework alvo para projetos multi-direcionados (por exemplo, net10.0-windows10.0.26100.0).
• --project <name-or-path> - Quando a entrada é uma solução (.sln/.slnx) ou um diretório com múltiplos projetos de aplicação executáveis, seleciona-se qual projeto lançar (por nome ou caminho).
• --no-build - Saltar a construção e executar a saída da build existente (ainda avaliando as propriedades da saída).
• --no-restore - Evite restaurar o projeto antes da construção.
• -p, --property <Name=Value> - Propriedade MSBuild, encaminhada tanto para a construção como para a avaliação da propriedade. Repetível (por exemplo, -p WindowsPackageType=None).

Saída da build & verbosidade: o projeto é construído em dois passos — dotnet build a cuja saída transmite diretamente para a sua consola, seguida de uma rápida avaliação de propriedades. O WinApp imprime a invocação exata dotnet build … antes da saída e transmite avisos mesmo numa build bem-sucedida. Verborrosidade:

Por baixo --json de ou --quiet a invocação e a saída de build vão para stderr, por isso o stdout mantém-se puramente JSON / limpo.

Aplicabilidade das opções: as opções de identidade/layout solto (--manifest, --output-appx-directory, --no-launch, --with-alias, --unregister-on-exit, --clean, , ) --executableaplicam-se apenas a aplicações empacotadas. São rejeitadas com um erro claro para aplicações não empacotadas (que não têm pacote MSIX). As opções de lançamento/depuração (--args/--, --detach, --debug-output, --symbols, --json) funcionam em ambos.

Exemplos em modo Project:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

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:

Contextos mutuamente exclusivos. WinAppRunNoLaunch e WinAppRunDetach cada um descreve um comportamento de lançamento diferente, por isso entram em conflito com as outras propriedades de lançamento e entre si. Definir um par conflituoso falha a execução com --X and --Y cannot be used together:

WinAppRunUseExecutionAlias, WinAppRunDebugOutput, e WinAppRunUnregisterOnExit podem ser combinadas entre si. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutable, e WinAppLaunchArgs não têm restrições. WinAppRunArgs Não adiciona restrições próprias, mas um interruptor que passa por ele é verificado como qualquer outro, por isso WinAppRunArgs="--detach" continua a entrar em conflito com WinAppRunNoLaunch.

<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

az-sign

Code-sign num ficheiro (exe, MSIX ou MSIX bundle) usando o Assinatura Confiável do Azure — uma identidade de assinatura gerida na cloud, pelo que nenhuma chave privada (PFX) alguma vez vive na máquina local.

winapp az-sign <file-path> [options]

Argumentos:

• file-path - Caminho para o ficheiro a assinar (exe, msix ou msixbundle)

Opções:

• --subscription, -s - ID de subscrição Azure para usar. Se não for fornecida e existirem várias subscrições, será solicitado
• --resource-group, -r - Grupo de recursos para restringir contas de assinatura
• --account - Assinar nome da conta. Deve ser usado com --resource-group
• --profile, -p - Nome do perfil do certificado. Deve ser usado com --account
• --metadata-file, -m - Caminho para um existente metadata.json. Ignora a descoberta de recursos e os prompts de seleção de conta/perfil e assina diretamente. Uma credencial Azure não interativa já deve estar disponível; a CLI pode, caso contrário, recorrer a um prompt interativo de inquilino ou az login, mas a API programática npm é sempre não interativa e falha em vez de ser solicitada

Authentication: (Autenticação)

az-signutiliza a cadeia de credenciais padrão do Azure (DefaultAzureCredential). Para CI/CD, defina AZURE_TENANT_ID, AZURE_CLIENT_ID, e AZURE_CLIENT_SECRET (ou use GitHub Actions OIDC / identidade gerida). Uma sessão existente do CLI do Azure (az login, incluindo a azure/login Ação do GitHub) também é aceite em qualquer ambiente. Só quando não forem encontradas credenciais e a sessão for interativa será az-sign iniciada az login para si.

Pré-requisitos:

• Uma conta de assinatura de código Azure e um perfil de certificado (criado no portal Azure após validação de identidade), além do papel de Signatário do Perfil de Certificado de Assinatura atribuído à sua identidade. Para mais orientações, visite a documentação de início rápido do Azure Artifact Signing.
• Foi instalado um runtime x64 .NET 8 (ou posterior) para toda a máquina. A biblioteca cliente de assinatura do Azure é um assembly gerido que signtool.exe carrega num processo separado; o tempo de execução autónomo do winapp não a satisfaz. Instala-o a partir https://dotnet.microsoft.com/download de quando a assinatura falhar com um erro de carregamento em tempo de execução.
• O Microsoft Visual C++ Redistributable (x64). A biblioteca cliente de assinatura do Azure depende do runtime VC++ e, como o winapp descarrega o pacote NuGet bruto em vez do instalador oficial das ferramentas cliente, esta dependência não é instalada automaticamente. Uma máquina limpa pode carregar e falhar mesmo com .NET e SignTool presentes. Instale o último x64 redistributable a partir https://aka.ms/vs/17/release/vc_redist.x64.exe de se a assinatura falhar, com um 0xc000007berro de DLL em falta de , "A aplicação não conseguiu iniciar corretamente" ou DLL em falta do dlib.

IC de menor privilégio: A descoberta automática (listando subscrições, grupos de recursos, contas e perfis) requer acesso de leitura num âmbito parental. Para evitar todas as chamadas de listagem de coleções, passa as quatro de --subscription, --resource-group, --account, e --profile: e depois az-sign valida a conta e o perfil com leituras diretas de recursos (um GET em cada recurso nomeado) em vez de enumerar a coleção pai, pelo que um principal com âmbito apenas para essa conta e perfil é suficiente. Omitir qualquer uma delas reintroduz uma chamada de listagem — por exemplo, excluir --subscription faz az-sign lista das subscrições a que a sua identidade pode aceder — o que um principal com âmbito restrito pode não ser autorizado a fazer. Um principal com âmbito apenas para um único perfil de certificado pode saltar completamente a validação ao passar um ponto pré-gerado --metadata-file (que especifica diretamente o endpoint da conta e o perfil).

Exemplos:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

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:

• args... – Argumentos a passar diretamente para a msstore CLI. Consulte a documentação da CLI do MSStore para comandos e opções disponíveis.

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

Find-ui

Procure controlos e exemplos do WinUI para um exemplo de código funcional. Apenas WinUI: o corpus é a WinUI 3 Gallery e o Windows Community Toolkit (mais alguns padrões centrais selecionados) — não cobre WPF, WinForms ou outros frameworks de interface. Uma terceira fonte, o microsoft-ui-reactor ReactorGallery, é o opt-in: é excluído de uma pesquisa normal e só é pesquisado quando passa --source reactor (as suas amostras declarativas apenas em C# não são coladas numa aplicação XAML padrão, por isso procure-as apenas ao construir um projeto Reactor/MVU).

winapp find-ui "<query>" [options]

O corpus é obtido do GitHub na primeira utilização e armazenado em cache por utilizador em <global .winapp>/cache/find-ui, pelo que a primeira execução requer acesso à rede. As corridas subsequentes são servidas a partir da cache local (atualizada no máximo a cada 7 dias, ou a pedido com --refresh).

Opções:

• --id <id> - Buscar o código (Gallery/Toolkit retornam XAML e/ou C#; O reator é apenas C#) mais notas pré-requisito para um ou mais IDs de cenários de uma pesquisa anterior (por exemplo, gallery-tabview-1). Repetível. Os IDs são insensíveis a maiúsculas minúsculas — GALLERY-TABVIEW-1 resolvem da mesma forma que gallery-tabview-1.
• --list - Listar todos os ids de controlo/amostra descobertos em vez de pesquisar (Galeria + Toolkit + núcleo; a fonte opcional do Reator está excluída).
• --source <gallery|toolkit|reactor|core> - Restringir os resultados da pesquisa a uma única fonte. (Apenas pesquisa — não válido com --list/--id.) O reator é opt-in — está excluído de uma pesquisa normal, por isso --source reactor é a única forma de o pesquisar.
• --max <N> - Número máximo de controlos combinados a regressar (padrão: 3). Aplica-se apenas à pesquisa; ignorado com --list/--id.
• --refresh- Contornar a cache local e recuperar o corpus WinUI do GitHub.
• --json - Emitir JSON estruturado (amigo do agente). Para pesquisa, cada correspondência transporta source, control, score, description, e um scenarios array cujas entradas contêm o per-cenário id e header; para --id, código completo. Em --jsoncada falha — incluindo erros de argumento/analisador como um não inteiro --max — é emitido como um objeto plano {"error": "..."} em stdout com um código de saída diferente de zero, pelo que a saída permanece legível pela máquina.

Fluxo de trabalho: procure de forma compacta para encontrar o controlo certo e os seus IDs de cenário, depois busque o código completo para a melhor correspondência com --id.

Exemplos:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

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 winapp.jsBindings escrito pelo último package.json, depois emite ligações digitadas winmds.lock.jsonwinapp restore.js em + .d.ts.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

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).

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

Opções:

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:

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 uma janela ou região de elemento num MP4 H.264.

# 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

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o demo.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).
• --frames - Escrever JPEGs com carimbo temporal, frames.ndjson, e manifest.json para <output-name>.frames. Suporta 1-30 fps e --max-edge 64-4096 (padrão 1280), com limite de 1 GiB de dados de frames.

Com --json, o resultado final inclui o caminho de saída, dimensões, codec, modo de captura, cadência, razão de paragem, opcional frameArtifacts, e avisos.

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.