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

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

Deteção automática de 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

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)

winapp pack <input-folder> [options]

Argumentos:

• input-folder - Diretório contendo os ficheiros de aplicação a empacotar

Opções:

• --output <filename> - Nome do ficheiro MSIX de saída (por defeito: <name>_<version>_<arch>.msix, voltando a <name>_<version>.msix, <name>_<arch>.msix, ou <name>.msix quando a versão/arquitetura não pode ser determinada)
• --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 nome para geração de certificados
• --self-contained - Bundle SDK de Aplicações Windows runtime
• --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 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

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 CN (padrão: CN=<utilizador atual>)
• --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.

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

<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 nome do certificado
• --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:

• 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

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.

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)
• invoke - Ativar elemento (clicar, alternar, expandir)
• click - Clique no elemento via simulação de rato (para controlos que não suportam invocação)
• set-value - Definir valor no elemento editável (texto, número)
• 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)

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