Documentação e uso da CLI

Conclusão do shell

Habilite a conclusão da guia para comandos, opções e valores. Consulte o guia de Conclusão do Shell para obter instruções de instalaçã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

Iniciar

Inicialize um diretório com o SDK do Windows, SDK do Aplicativo Windows e ativos necessários para o desenvolvimento moderno do Windows.

winapp init [base-directory] [options]

Argumentos:

  • base-directory - Diretório base/raiz para o aplicativo/workspace (padrão: diretório atual)

Opções:

  • --config-dir <path> - Diretório para leitura/configuração do repositório (padrão: diretório atual)
  • --setup-sdks - Modo de instalação do SDK: 'estável' (padrão), 'versão prévia', 'experimental' ou 'nenhum' (ignorar instalação do SDK)
  • --ignore-config, --no-config - Não use o arquivo de configuração para o gerenciamento de versão
  • --no-gitignore - Não atualize o arquivo .gitignore
  • --use-defaults, --no-prompt – Não solicitar e usar o padrão de todos os prompts
  • --config-only – Manipular somente as operações de arquivo de configuração, ignorar a instalação do pacote

O que faz:

  • Cria winapp.yaml o arquivo de configuração (somente quando os pacotes do SDK são gerenciados; ignorados com --setup-sdks none)
  • Baixa pacotes do Windows SDK e do SDK do Aplicativo Windows
  • Gera cabeçalhos e binários do C++/WinRT
  • Cria Package.appxmanifest
  • Configura ferramentas de build e habilita o modo de desenvolvedor
  • Atualiza .gitignore para excluir arquivos gerados
  • Armazena arquivos compartilháveis no diretório de cache global

Detecção automática de projeto .NET:

Quando um arquivo .csproj é encontrado no diretório de destino, init usa 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 do NuGet PackageReference diretamente no .csproj
  • Gera Package.appxmanifest, ativos e um certificado de desenvolvimento
  • Não cria nem winapp.yaml baixa projeções do C++ (use 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: instalar SDKs após a instalação inicial

Se você executou init com --setup-sdks none (ou ignorou a instalação do SDK) e depois precisa dos SDKs:

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

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

restauração

Restaurar pacotes e regenerar arquivos com base na configuração existente winapp.yaml .

winapp restore [options]

Opções:

  • --config-dir <path> - Diretório que contém winapp.yaml (padrão: diretório atual)

O que faz:

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

Observação

Para projetos .NET inicializados com winapp init, não há winapp.yaml. Use o dotnet restore em vez disso para restaurar pacotes NuGet.

Exemplos:

# Restore from winapp.yaml in current directory
winapp restore

atualização

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

winapp update [options]

Opções:

  • --setup-sdks <stable|preview|experimental|none>- Modo de instalação do SDK: stable (padrão), previewexperimentalou none (ignorar instalação do SDK)

O que faz:

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

Exemplos:

# Update packages to latest versions
winapp update

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

pacote

Crie pacotes MSIX com base em diretórios de aplicativos preparados. Requer que um arquivo de manifesto (Package.appxmanifest preferencial, appxmanifest.xml também com suporte) esteja presente no diretório de destino, no diretório atual ou passado com a opção --manifest . (executar init ou manifest generate criar um manifesto)

winapp pack <input-folder> [options]

Argumentos:

  • input-folder – Diretório que contém os arquivos do aplicativo para empacotar

Opções:

  • --output <filename> - Nome do arquivo MSIX de saída (padrão: <name>_<version>_<arch>.msix, voltar para <name>_<version>.msix, <name>_<arch>.msixou <name>.msix quando a versão/arco não pode ser determinada)
  • --name <name> - Nome do pacote (padrão: do manifesto)
  • --manifest <path> - Caminho para o arquivo de manifesto (Package.appxmanifest preferencial, appxmanifest.xml também com suporte; padrão: detecção automática)
  • --cert <path> - Caminho para assinar o certificado (habilita a assinatura automática)
  • --cert-password <password> - Senha de certificado (padrão: "senha")
  • --generate-cert – Gerar um novo certificado de desenvolvimento
  • --install-cert – Instalar o certificado no computador
  • --publisher <name> – nome Publisher para geração de certificado
  • --self-contained – tempo de execução do pacote SDK do Aplicativo Windows
  • --skip-pri - Ignorar a geração de arquivos PRI
  • --executable <path> - Caminho para o executável em relação à pasta de entrada (também --exe). Usado para resolver $targetnametoken$ espaços reservados no manifesto.

O que faz:

  • Valida e processa arquivos Package.appxmanifest
  • Resolve tokens $placeholder$ no manifesto (consulte espaços reservados de manifesto abaixo)
  • Garante dependências de estrutura adequadas
  • Atualiza manifestos lado a lado com registros
  • Descobre automaticamente componentes winRT de terceiros e registra suas classes ativas (consulte a descoberta de componentes do WinRT abaixo)
  • Manipula a implantação autocontida do WinAppSDK
  • Assinar pacote se o certificado for fornecido

Descoberta de componente do WinRT

Ao empacotar, winapp pack verifica automaticamente os winapp.yaml pacotes NuGet definidos nos componentes WinRT de terceiros ( *.csproj por exemplo, Win2D). Ele analisa .winmd arquivos para extrair nomes de classe ativantes e localiza suas DLLs de implementação. As entradas descobertas são registradas da seguinte maneira:

  • Dependentes da estrutura (padrão): classes ativantes são adicionadas como <InProcessServer> entradas no Package.appxmanifest
  • Autocontido (--self-contained): classes ativas são inseridas em manifestos SxS (lado a lado) dentro do executável

Resolução de espaço reservado durante o empacotamento:

Se o manifesto contiver $targetnametoken$ no Executable atributo:

  1. Se --executable for fornecido (caminho relativo à pasta de entrada), o espaço reservado será substituído pelo valor especificado
  2. Caso contrário, winapp pack verifica a raiz da pasta de entrada em busca .exe de arquivos – se exatamente um for encontrado, ele será usado automaticamente
  3. Se zero ou vários .exe arquivos forem encontrados, um erro será mostrado solicitando que você 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

create-debug-identity

Crie a identidade do aplicativo para depuração usando o empacotamento esparso. O exe permanece em seu local original – Windows associa a identidade a ela por meio de Add-AppxPackage -ExternalLocation.

Quando usar isso vswinapp run: use create-debug-identity quando o exe estiver separado do código do aplicativo (por exemplo, aplicativos Electron em node_modulesque electron.exe está) ou ao testar especificamente o comportamento do pacote esparso. Para a maioria das estruturas em que o exe está em sua pasta de saída de build, use winapp run em vez disso : ele registra um pacote de layout solto completo e inicia o aplicativo. Consulte o Guia de Depuração para obter uma comparação completa.

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

Argumentos:

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

Opções:

  • --manifest <path>- Caminho para o arquivo de manifesto do aplicativo ou appxmanifest.xmlPackage.appxmanifest (padrão: detectar Package.appxmanifest automaticamente ou appxmanifest.xml no diretório atual)
  • --no-install - Não instale o pacote após a criação
  • --keep-identity – Manter a identidade do manifesto as-is, sem acrescentar .debug ao nome do pacote e à ID do aplicativo

O que faz:

  • Modifica o manifesto de execução paralela do executável
  • Registra o pacote esparso para identidade
  • Habilita a depuração de APIs que exigem 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

Gere e gerencie arquivos Package.appxmanifest.

geração de manifesto

Gere Package.appxmanifest a partir de modelos.

winapp manifest generate [directory] [options]

Argumentos:

  • directory - Diretório no qual gerar manifesto (padrão: diretório atual)

Opções:

  • --package-name <name> - Nome do pacote (padrão: nome da pasta)
  • --publisher-name <name> – CN de Publisher (padrão: CN=<usuário >)
  • --version <version> – Versão (padrão: "1.0.0.0")
  • --description <text> - Descrição (padrão: "Meu Aplicativo")
  • --entrypoint <path> – Executável de ponto de entrada ou script
  • --template <type> - Tipo de modelo: packaged (padrão) ou sparse
  • --logo-path <path> - Caminho para o arquivo de imagem do logotipo
  • --if-exists <Error|Overwrite|Skip> – Comportamento quando o arquivo de manifesto já existe no caminho de destino (padrão: Error)

Modelos:

Marcadores de posição de manifesto

Os manifests gerados no momento do empacotamento usam tokens $placeholder$ (delimitados por cifrão) que são resolvidos automaticamente:

Placeholder Resolvido para Exemplo
$targetnametoken$ Nome executável sem extensão Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Sempre resolvido automaticamente

Isso segue a mesma convenção usada por Visual Studio modelos de projeto, portanto, os manifestos são portáteis entre ferramentas.

Como os marcadores de posição são resolvidos:

  • winapp pack — Durante o empacotamento, $targetnametoken$ é resolvido usando a opção --executable ou detectando automaticamente o único .exe na pasta de entrada. Se vários arquivos (ou zero) .exe forem encontrados e --executable não forem especificados, um erro será mostrado.
  • winapp create-debug-identity — Quando um argumento de ponto de entrada é fornecido, $targetnametoken$ é resolvido a partir dele. Sem um ponto de entrada, o espaço reservado executável já deve ser resolvido no manifesto.
  • winapp manifest generate --executable — Quando --executable for fornecido, os metadados de manifesto (versão, descrição) e ícones são extraídos do executável, mas o manifesto gerado ainda usa $targetnametoken$.exe; esse espaço reservado é resolvido posteriormente (por exemplo winapp pack , ou winapp create-debug-identity).

PS: Keeping $targetnametoken$ in your check-in manifest avoids hard-coding executable names and works with winapp pack and Visual Studio builds.

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

suplemento de manifesto

Adicione um alias de execução (uap5:AppExecutionAlias) a um Package.appxmanifest. Isso permite iniciar o aplicativo empacotado na linha de comando digitando o nome do alias.

winapp manifest add-alias [options]

Opções:

  • --name <alias> - Nome do alias (por exemplo myapp.exe). Padrão: inferido do Executable atributo no manifesto.
  • --manifest <path> - Caminho para Package.appxmanifest (padrão: pesquisar o diretório atual)
  • --app-id <id> – ID do aplicativo para adicionar o alias (padrão: primeiro elemento Application)

O que faz:

  • Lê o manifesto e infere o alias do Executable atributo (preservando espaços reservados como $targetnametoken$.exe)
  • Adiciona a declaração de uap5 namespace se ainda não estiver presente
  • Adiciona um <Extensions> bloco com <uap5:AppExecutionAlias> o elemento Application de destino
  • Se o alias já existir, o relatará e sairá com êxito

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-recursos

Gere todos os ativos de imagem MSIX necessários de uma única imagem de origem.

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

Argumentos:

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

Opções:

  • --manifest <path> - Caminho para o arquivo Package.appxmanifest (padrão: pesquisar o diretório atual)
  • --light-image <path> - Caminho para uma imagem de origem separada para variantes de tema claro

Descrição:

Usa 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 do aplicativo (Square44x44Logo /AppList, 44×44 base):

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

Additionally:

  • app.ico — arquivo de ICO de várias resoluções (16, 24, 32, 48, 256) para integração de shell. Se um arquivo existente .ico for encontrado no diretório de ativos (por exemplo AppIcon.ico , de um modelo de projeto), ele será substituído no local em vez de criar uma duplicata

Com --light-image:

  • Variantes de targetsize de tema claro — .targetsize-{size}_altform-lightunplated (ícone do aplicativo)
  • Variantes de escala de tema claro — .scale-{factor}_altform-colorful_theme-light (blocos, logotipo da loja)

Suporte ao SVG: Os arquivos SVG têm suporte total como imagens de origem. Eles são renderizados como vetores diretamente em cada tamanho de destino, produzindo resultados perfeitos em todas as resoluções.

O comando dimensiona as imagens proporcionalmente, mantendo a taxa de proporção, centralizando-as com planos de fundo transparentes quando necessário. Os ativos são salvos no diretório Assets relativo ao local 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 de uma pasta de saída de build, registre-o com Windows usando a API Windows.Management.Deployment.PackageManager e inicie o aplicativo, simulando uma instalação msix completa para depuração. Retorna a ID do processo para anexo do depurador.

Esta é o comando preferencial para depuração com identidade do pacote para a maioria das estruturas (.NET, C++, Rust, Flutter, Tauri). Ao contrário do create-debug-identity que registra um pacote esparso para um único exe, winapp run registra a pasta inteira como um pacote de layout flexível, assim como uma instalação MSIX real. Consulte o Guia de Depuração para fluxos de trabalho comuns de depuração.

winapp run <input-folder> [options]

Argumentos:

  • input-folder - Diretório que contém o aplicativo a ser executado (obrigatório)

Opções:

  • --manifest <path> - Caminho para Package.appxmanifest (padrão: detectar automaticamente da pasta de entrada ou do diretório atual)
  • --output-appx-directory <path> - Diretório de saída para o pacote de layout solto (padrão: AppX dentro do diretório da pasta de entrada)
  • --args <string> - Argumentos de linha de comando a serem passados para o aplicativo. Como alternativa, use -- seguido de argumentos para evitar escape (por exemplo, winapp run . -- --flag value).
  • --no-launch - Crie apenas a identidade de depuração e registre o pacote sem iniciar o aplicativo
  • --with-alias – Inicie o aplicativo usando seu alias de execução em vez de ativação do AUMID. O aplicativo é executado no terminal atual com stdin/stdout/stderr herdado. Requer um uap5:ExecutionAlias no manifesto (use winapp manifest add-alias para adicionar um). Não é possível combinar com --no-launch. Não é possível combinar com --json.
  • --debug-output – Capturar OutputDebugString mensagens e exceções de primeira chance do aplicativo iniciado. O ruído da estrutura (WinUI, COM, DirectX) é filtrado da saída do console; o arquivo de log completo captura tudo. Se o aplicativo falhar, capturará automaticamente um minidump e o analisará para mostrar o tipo de exceção, a mensagem e o rastreamento de pilha com números de arquivo de origem:linha (resolvidos de PDBs na pasta de saída de build). Falhas gerenciadas (.NET) são analisadas instantaneamente sem ferramentas externas. Falhas nativas (C++/WinRT) mostram os nomes e deslocamentos do módulo. Somente um depurador pode anexar a um processo de cada vez, portanto, outros depuradores (Visual Studio, VS Code) não podem ser usados simultaneamente. Em vez disso, use --no-launch se precisar anexar um depurador diferente. Não é possível combinar com --no-launch. Não é possível combinar com --json.
  • --symbols – Baixe símbolos PDB do servidor de símbolos Microsoft para uma análise de falha nativa mais avançada com nomes de função resolvidos. Usado somente com --debug-output. Se ocorrer omitido e ocorrer uma falha nativa, a saída sugerirá a adição desse sinalizador. A primeira execução baixa símbolos e os armazena em cache localmente; as execuções subsequentes usam o cache.
  • --unregister-on-exit - Cancele o registro do pacote de desenvolvimento após a saída do aplicativo. Remove apenas os pacotes registrados no modo de desenvolvimento. Não é possível combinar com --no-launch.
  • --detach – Inicie o aplicativo e retorne imediatamente sem esperar que ele saia. Útil para CI/automação em que você precisa interagir com o aplicativo após a inicialização. Imprime o PID para stdout (ou em JSON com --json). Não é possível combinar com --no-launch, --debug-output, --with-aliasou --unregister-on-exit.
  • --clean - Remova os dados do aplicativo do pacote existente (LocalState, configurações etc.) antes de implantar novamente. Por padrão, os dados do aplicativo são preservados em relançamentos.
  • --json - Formatar a saída como JSON para consumo programático (por exemplo, CI/automação). Útil para --detach capturar o PID. Não é possível combinar com --with-alias ou --debug-output.

Persistência de dados do aplicativo:

Por padrão, winapp run preserva os dados do aplicativo (LocalState, RoamingState, Settingsetc.) ao implantar novamente. Se o aplicativo gravar dados no ApplicationData.Current.LocalFolder contexto ou Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dentro do pacote, esses dados sobreviverão entre winapp run invocações.

Use --clean quando precisar de um novo início (por exemplo, para redefinir o estado corrompido ou testar o comportamento de primeira execução).

O que faz:

  • Localiza ou gera o Package.appxmanifest
  • Cria e registra uma identidade de depuração usando um pacote de layout flexível
  • Calcula a ID do modelo de usuário do aplicativo (AUMID)
  • Inicia o aplicativo usando a identidade registrada (a menos que --no-launch seja especificado)
  • ID do processo impresso (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 seu .csproj comportamento de controle:

Propriedade Padrão Descrição
EnableWinAppRunSupport true Habilitar/desabilitar a funcionalidade de suporte de execução
WinAppLaunchArgs (vazio) Argumentos a serem passados para o aplicativo na inicialização
WinAppRunUseExecutionAlias false Iniciar por meio de alias de execução em vez de ativação do AUMID
WinAppRunNoLaunch false Registrar apenas a identidade sem iniciar
WinAppRunDebugOutput false Capturar OutputDebugString mensagens e exceções de primeira chance. Somente um depurador pode anexar por vez (impede VS/VS Code). Em vez disso, use WinAppRunNoLaunch para anexar um depurador diferente. 
<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Unregister

Cancele o registro de um pacote de desenvolvimento sideload. Remove apenas os pacotes que foram registrados no modo de desenvolvimento (por exemplo, via winapp run ou create-debug-identity). Os pacotes instalados na loja ou instalados pelo MSIX nunca são removidos.

winapp unregister [options]

Opções:

  • --manifest <path> - Caminho para Package.appxmanifest (padrão: detecção automática do diretório atual)
  • --force - Ignorar a verificação do diretório de local de instalação e cancelar o registro, mesmo que o pacote tenha sido registrado de uma árvore de projeto diferente
  • --json - Formatar saída como JSON

O que faz:

  • Lê o nome do pacote do manifesto
  • Pesquisa pacotes e pacotes {name} (a variante de depuração é criada por create-debug-identity){name}.debug
  • Verifica se cada pacote foi registrado no modo de desenvolvimento (IsDevelopmentMode == true)
  • Verifica se o local de instalação do pacote está na árvore de diretório atual (a menos --forceque )
  • Cancelar o registro de 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

Gere, inspecione e instale certificados de desenvolvimento.

Gerar certificado

Gerar certificados de desenvolvimento para assinatura de pacote.

winapp cert generate [options]

Opções:

  • --manifest <Package.appxmanifest> – Extrair informações do editor de Package.appxmanifest
  • --publisher <name> – Publisher nome do certificado
  • --output <path> - Caminho do arquivo de certificado de saída (dá suporte a caminhos absolutos e relativos)
  • --password <password> - Senha de certificado (padrão: "senha")
  • --valid-days <valid-days> - Número de dias em que o certificado é válido (padrão: 365)
  • --install – Instalar o certificado no repositório de máquinas local após a geração
  • --if-exists <Error|Overwrite|Skip> - Definir o comportamento se o arquivo de certificado já existir (padrão: Erro)
  • --export-cer - Exportar um .cer arquivo (somente chave pública) ao lado do .pfx. Útil para distribuir o certificado público separadamente para a instalação de confiança.
  • --json - Formatar a saída como JSON para consumo programático. Os erros também são retornados como JSON ({"error": "..."}).

Informações de certificado

Exibir detalhes do certificado de um arquivo PFX. Útil para verificar se um certificado corresponde ao manifesto antes de assinar.

winapp cert info <cert-path> [options]

Argumentos:

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

Opções:

  • --password <password> - Senha para o arquivo PFX (padrão: "senha")
  • --json - Formatar saída como JSON

Instalação do certificado

Instale o certificado no repositório de certificados do computador.

winapp cert install <cert-path> [options]

Argumentos:

  • cert-path - Caminho para o arquivo de certificado a ser instalado

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

assinar

Assinar pacotes MSIX e executáveis 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 assinar o certificado
  • --cert-password <password> - Senha de certificado (padrão: "senha")

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

Gere um CodeIntegrityExternal.cat arquivo de catálogo contendo hashes de arquivos executáveis de diretórios especificados. Esse catálogo é usado com o sinalizador TrustedLaunch em manifestos de pacote esparsos MSIX (AllowExternalContent) para permitir a execução de arquivos externos não incluídos no próprio pacote.

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

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

Argumentos:

  • input-folder - Um ou mais diretórios que contêm arquivos executáveis a serem processados. Separar vários diretórios com ponto-e-vírgula (por exemplo, "dir1;dir2")

Opções:

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

O que faz:

  • Verifica os diretórios especificados para arquivos executáveis (binários PE com seções de código)
  • Gera um CDF (Arquivo de Definição de Catálogo) com hashes de todos os executáveis encontrados
  • Usa APIs Windows CryptoCAT para produzir o arquivo de catálogo .cat
  • Arquivos não executáveis (por exemplo, .txt.dll sem seções de código) são ignorados automaticamente

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 criar um pacote MSIX esparso que usa 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 de código para os executáveis do aplicativo
  3. winapp pack — Empacotar o manifesto, os ativos e o catálogo em um MSIX

ferramenta

Acesso às ferramentas do SDK do Windows diretamente. Usa ferramentas disponíveis em Microsoft.Windows. SDK. BuildTools

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

Ferramentas disponíveis:

  • makeappx – Criar e manipular pacotes de aplicativos
  • signtool – Assinar arquivos e verificar assinaturas
  • mt - Ferramenta de manifesto para conjuntos lado a lado
  • E outras ferramentas do SDK Windows do Microsoft.Windows. SDK. BuildTools

Exemplos:

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

armazenar

Execute um comando da CLI do Desenvolvedor da Microsoft Store. Esse comando baixará a CLI do desenvolvedor do Microsoft Store se ainda não tiver sido baixado. Saiba mais sobre a CLI Microsoft Store Developer.

winapp store [args...]

Argumentos:

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

O que faz:

  • Garante que a CLI do Desenvolvedor do Microsoft Store (msstore) esteja baixada e disponível em seu sistema.
  • Encaminha todos os argumentos para a msstore CLI.
  • Executa o comando mostrando a saída diretamente no 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

Obter caminhos para componentes do SDK do Windows instalados.

winapp get-winapp-path [options]

O que ele retorna:

  • Caminhos para o .winapp diretório do workspace
  • Diretórios de instalação do pacote
  • Locais de cabeçalho gerados

node create-addon

(Disponível somente no pacote NPM) Gerar modelos de complemento C++ ou C# nativos com Windows SDK e integração SDK do Aplicativo Windows.

npx winapp node create-addon [options]

Opções:

  • --name <name> - Nome do complemento (padrão: "nativeWindowsAddon")
  • --template - Selecione o tipo de complemento. As opções são cs ou cpp (padrão: cpp)
  • --verbose - Habilitar saída detalhada

O que faz:

  • Cria o diretório de complemento com arquivos de modelo
  • Gera binding.gyp e addon.cc com exemplos de SDK Windows
  • Instala as dependências npm necessárias (nan, node-addon-api, node-gyp)
  • Adiciona o script de build ao arquivo package.json

Exemplos:

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

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

node add-electron-debug-identity

(Disponível somente no pacote NPM) Adicione a identidade do aplicativo ao processo de desenvolvimento do Electron usando o empacotamento esparso. Requer um Package.appxmanifest (crie um com winapp init ou winapp manifest generate se você não tiver um).

Importante

Há um problema conhecido com o empacotamento esparso de aplicativos Electron que faz com que o aplicativo falhe ao iniciar ou não renderize o conteúdo da Web. O problema foi corrigido em Windows mas ainda não foi propagado para dispositivos de Windows externos. Se você estiver vendo esse problema após a chamada add-electron-debug-identity, poderá desabilitar a área restrita em seu aplicativo Electron para fins de depuração com o --no-sandbox sinalizador. Esse problema não afeta o empacotamento MSIX completo.

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

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

Opções:

Opção Descrição
--manifest <path> Caminho para Package.appxmanifest personalizado (padrão: Package.appxmanifest no diretório atual)
--no-install Não instale nem modifique as dependências; apenas configure a identidade de depuração do Electron
--keep-identity Mantenha a identidade do manifesto as-is, sem acrescentar .debug ao nome do pacote e à ID do aplicativo
--verbose Habilitar saída detalhada

O que faz:

  • Registra a identidade de depuração para electron.exe processo
  • Habilita o teste de APIs que exigem identidade no desenvolvimento do Electron
  • Usa 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

node clear-electron-debug-identity

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

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

Opções:

Opção Descrição
--verbose Habilitar saída detalhada

O que faz:

  • Restaura electron.exe do backup criado por add-electron-debug-identity
  • Remove os arquivos de backup após a restauração
  • Retorna o Electron ao estado original sem a identidade do pacote

Exemplos:

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

Opções globais

Todos os comandos dão suporte a estas opções globais:

  • --verbose, -v – Habilitar a saída detalhada para registro em log detalhado
  • --quiet, -q – Suprimir mensagens de progresso
  • --help, -h – Mostrar ajuda de comando

Diretório de Cache Global

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

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

Para usar um local diferente, defina a variável de WINAPP_CLI_CACHE_DIRECTORY ambiente.

No 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á esse diretório automaticamente quando você executar comandos como init ou restore.

ui

Inspecione e interaja com a execução Windows UIs do aplicativo usando Automação da Interface do Usuário (UIA).

winapp ui [command] [options]

Comandos:

  • status – Conectar-se ao aplicativo e mostrar informações
  • inspect - Exibir árvore de elementos
  • search - Localizar elementos por seletor
  • get-property – Ler propriedades do elemento
  • get-text / get-value - Ler valor/texto do elemento (TextPattern, ValuePattern ou Name)
  • screenshot - Capturar janela/elemento como PNG (captura automaticamente caixas de diálogo separadamente)
  • invoke - Ativar elemento (clique, alterne, expanda)
  • click - Clique no elemento por meio da simulação do mouse (para controles que não dão suporte à invocação)
  • set-value - Definir valor no elemento editável (texto, número)
  • focus – Mover o foco do teclado
  • scroll-into-view - Elemento scroll visível
  • wait-for - Aguarde o estado do elemento
  • list-windows - Listar todas as janelas de um aplicativo
  • get-focused - Relatar o elemento focado no momento

Opções:

  • -a, --app <app> - Aplicativo de destino (nome, título ou PID)
  • -w, --window <hwnd> - Janela de destino por HWND (estável)

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

  • Last updated on