Compartilhar via

Referência da CLI de Desenvolvimento de Aplicativos do Windows

Importante

A CLI de Desenvolvimento de Aplicativos do Windows está atualmente em prévia pública. Recursos e comandos podem ser alterados antes da versão final.

Esta página documenta todos os comandos disponíveis para a CLI do winapp.

Opções globais

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

Opção Descrição
--verbose, -v Habilitar saída detalhada para registros precisos em log
--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, ela é $UserProfile/.winapp.

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

$env:WINAPP_CLI_CACHE_DIRECTORY = "d:\temp\.winapp"

Comandos de instalação

Iniciar

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

winapp init [base-directory] [options]

Argumentos:

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

Opções:

Opção Descrição
--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: stable (padrão), previewexperimentalounone
--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 pedir e usar o padrão para todos os prompts
--config-only Manipular somente operações de arquivo de configuração, ignorar a instalação do pacote

O que faz:

  • Cria um winapp.yaml arquivo de configuração
  • Baixa pacotes do Windows SDK e do Windows App SDK
  • Gera cabeçalhos e binários do C++/WinRT
  • Cria AppxManifest.xml
  • Configura ferramentas de build e habilita o modo de desenvolvedor
  • Atualiza .gitignore para excluir arquivos gerados

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 o 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 appxmanifest.xml, 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

Se você executou init com --setup-sdks none e depois precisa dos SDKs, execute novamente winapp init --use-defaults --setup-sdks stable. Isso preserva os arquivos existentes (manifesto, etc.).

restauração

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

winapp restore [options]

Opções:

Opção Descrição
--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

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:

Opção Descrição
--config-dir <path> Diretório que contém winapp.yaml (padrão: diretório atual)
--setup-sdks Modo de instalação do SDK: stable (padrão), previewexperimentalounone

O que faz:

  • Lê a configuração existente winapp.yaml
  • 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

Comandos de empacotamento

pacote

Crie pacotes MSIX com base em diretórios de aplicativos preparados. Requer que o arquivo appxmanifest.xml esteja presente no diretório de destino, no diretório atual ou passado com a opção --manifest.

winapp pack <input-folder> [options]

Argumentos:

Argument Descrição
input-folder Diretório que contém os arquivos de aplicativo para empacotar

Opções:

Opção Descrição
--output <filename> Nome do arquivo MSIX de saída (padrão: <name>.msix)
--name <name> Nome do pacote (padrão: do manifesto)
--manifest <path> Caminho para AppxManifest.xml (padrão: detecção automática)
--cert <path> Caminho para assinar o certificado (habilita a assinatura automática)
--cert-password <password> Senha do certificado (padrão: "senha")
--generate-cert Gerar um novo certificado de desenvolvimento
--install-cert Instalar o certificado no computador
--publisher <name> Nome do Editor para a geração de certificado
--self-contained Tempo de execução do pacote Windows App SDK
--skip-pri Ignorar a geração de arquivos PRI
--executable <path> Caminho para o executável em relação à pasta de entrada. Usado para resolver $targetnametoken$ espaços reservados no manifesto.

O que faz:

  • Valida e processa arquivos AppxManifest.xml
  • Resolve tokens $placeholder$ no manifesto (consulte espaços reservados do manifesto)
  • Garante dependências de estrutura adequadas
  • Atualiza manifestos lado a lado com registros
  • Gerencia a implantação autocontida do SDK de Aplicativos do Windows
  • Assinar pacote se o certificado for fornecido

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 runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable
winapp pack ./dist --executable MyApp.exe

create-debug-identity

Crie a identidade do aplicativo para depuração sem a necessidade de empacotamento completo MSIX usando local externo/empacotamento esparso.

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

Argumentos:

Argument Descrição
entrypoint Caminho para executável (.exe) ou script que requer identificação

Opções:

Opção Descrição
--manifest <path> Caminho para AppxManifest.xml (padrão: ./appxmanifest.xml)
--no-install Não instale o pacote após a criação
--keep-identity Mantenha 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

Comandos de manifesto

geração de manifesto

Gere AppxManifest.xml de modelos.

winapp manifest generate [directory] [options]

Argumentos:

Argument Descrição
directory Diretório no qual gerar manifesto (padrão: diretório atual)

Opções:

Opção Descrição
--package-name <name> Nome do pacote (padrão: nome da pasta)
--publisher-name <name> Publicador CN (padrão: CN=<current user>)
--version <version> Versão (padrão: "1.0.0.0")
--description <text> Descrição (padrão: "Meu Aplicativo")
--entrypoint <path> Ponto de entrada: executável 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 se o arquivo já existir (padrão: Erro)

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" torna-se Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Sempre resolvido automaticamente

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

  • winapp pack $targetnametoken$ resolve usando a opção --executable ou detectando automaticamente o único .exe na pasta de entrada.
  • winapp create-debug-identity resolve $targetnametoken$ a partir do argumento de ponto de entrada quando fornecido.
  • winapp manifest generate --executable extrai metadados do executável, mas mantém $targetnametoken$.exe no manifesto para resolução posterior.

Dica

Manter $targetnametoken$ no manifesto de check-in evita a codificação rígida de nomes de executáveis e funciona com compilações de winapp pack e do 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 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:

Argument Descrição
image-path Caminho para o arquivo de imagem de origem (PNG, JPG, GIF etc.)

Opções:

Opção Descrição
--manifest <path> Caminho para AppxManifest.xml arquivo (padrão: pesquisar o diretório atual)

Usa uma única imagem de origem e gera automaticamente todos os 12 ativos de imagem MSIX necessários nas dimensões corretas. 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

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

Comandos de certificado e assinatura

Gerar certificado

Gerar certificados de desenvolvimento para assinatura de pacote.

winapp cert generate [options]

Opções:

Opção Descrição
--manifest <appxmanifest.xml> Extrair informação de publicador do appxmanifest.xml
--publisher <name> Nome do emissor do certificado
--output <path> Caminho do arquivo de certificado de saída
--password <password> Senha do certificado (padrão: "senha")
--valid-days <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> Comportamento se o arquivo de certificado já existir (padrão: Erro)

Instalação do certificado

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

winapp cert install <cert-path>

Argumentos:

Argument Descrição
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

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

assinar

Assinar pacotes MSIX e executáveis com certificados.

winapp sign <file-path> [options]

Argumentos:

Argument Descrição
file-path Caminho para o pacote MSIX ou o executável para assinar

Opções:

Opção Descrição
--cert <path> Caminho para assinar o certificado
--cert-password <password> Senha do 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

Comandos de utilidade

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 do 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. Este comando baixa a CLI de Desenvolvedor da Microsoft Store, se ainda não foi baixada. Saiba mais na CLI do Desenvolvedor da Microsoft Store.

winapp store [args...]

Argumentos:

Argument Descrição
args... Argumentos a serem passados diretamente para a msstore CLI

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]

Retorna caminhos para o diretório do .winapp workspace, os diretórios de instalação de pacotes e os locais de cabeçalhos gerados.

comandos Node.js/Electron

Esses comandos estão disponíveis somente no pacote NPM.

node create-addon

Gere modelos de complementos nativos em C++ ou C# com integração do SDK do Windows e do Windows App SDK.

npx winapp node create-addon [options]

Opções:

Opção Descrição
--name <name> Nome do complemento (padrão: "nativeWindowsAddon")
--template Selecione o tipo de complemento: 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 arquivos binding.gyp e addon com exemplos do SDK do Windows
  • Instala as dependências npm necessárias
  • Adiciona o script de build ao arquivo package.json

Exemplos:

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

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

node add-electron-debug-identity

Adicione a identidade do aplicativo ao processo de desenvolvimento do Electron usando o empacotamento esparso. Requer um appxmanifest.xml (crie um com winapp init ou winapp manifest generate).

Importante

Há um problema conhecido com o empacotamento esparso de aplicativos Electron que faz com que o aplicativo falhe no início ou não renderize o conteúdo da Web. O problema foi corrigido no Windows, mas ainda não foi propagado para todos os dispositivos. Você pode desabilitar o sandboxing em seu aplicativo Electron com o --no-sandbox flag como uma solução alternativa. 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 o appxmanifest.xml personalizado (padrão: appxmanifest.xml 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 Manter a identidade do manifesto como está, sem acrescentar .debug
--verbose Habilitar saída detalhada

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/appxmanifest.xml

node clear-electron-debug-identity

Remova a identidade do pacote do processo de depuração no Electron, restaurando o arquivo original electron.exe do backup.

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

Opções:

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

Exemplos:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity
  • Last updated on