Partilhar via

Referência de CLI para desenvolvimento de Windows App

Importante

O CLI de Desenvolvimento de Aplicações do Windows encontra-se atualmente em pré-visualização pública. As funcionalidades e comandos podem mudar antes do lançamento final.

Esta página documenta todos os comandos disponíveis para a linha de comando winapp.

Opções globais

Todos os comandos suportam estas opções globais:

Option Descrição
--verbose, -v Ativar a saída verbosa para registos detalhados
--quiet, -q Suprimir mensagens de progresso
--help, -h Mostrar ajuda do comando

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 padrão, isso é $UserProfile/.winapp.

Para usar uma localização diferente, defina a WINAPP_CLI_CACHE_DIRECTORY variável ambiente:

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

Comandos de configuração

Init

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

winapp init [base-directory] [options]

Argumentos:

Argumento Descrição
base-directory Diretório base/raiz da app/espaço de trabalho (por defeito: diretório atual)

Opções:

Option Descrição
--config-dir <path> Diretório para ler/armazenar configuração (predefinido: diretório atual)
--setup-sdks Modo de instalação do SDK: stable (por defeito), preview, experimental, ou none
--ignore-config, --no-config Não uses ficheiros de configuração para gestão de versões
--no-gitignore Não atualize o ficheiro .gitignore
--use-defaults, --no-prompt Não solicitar e usar o padrão de todos os prompts
--config-only Só trata das operações de ficheiros de configuração, salta a instalação de pacotes

O que faz:

  • Cria winapp.yaml ficheiro de configuração
  • Descarrega pacotes do Windows SDK e do Windows App SDK
  • Gera cabeçalhos e binários em C++/WinRT
  • Cria AppxManifest.xml
  • Configura ferramentas de compilação e ativa o modo de programador
  • Atualiza o .gitignore para excluir ficheiros gerados

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

Sugestão

Se executou init com --setup-sdks none e depois precisar dos SDKs, execute novamente winapp init --use-defaults --setup-sdks stable. Isto preserva ficheiros existentes (manifestos, etc.).

repor

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

winapp restore [options]

Opções:

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

Observação

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

Exemplos:

# Restore from winapp.yaml in current directory
winapp restore

actualização

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

winapp update [options]

Opções:

Option Descrição
--config-dir <path> Diretório contendo winapp.yaml (predefinido: diretório atual)
--setup-sdks Modo de instalação do SDK: stable (por defeito), preview, experimental, ou none

O que faz:

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

Comandos de empacotamento

pack

Crie pacotes MSIX a partir de diretórios de aplicações preparados. Requer que o ficheiro appxmanifest.xml esteja presente no diretório de destino, no diretório atual ou com a opção --manifest passada.

winapp pack <input-folder> [options]

Argumentos:

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

Opções:

Option Descrição
--output <filename> Nome do ficheiro de saída MSIX (por defeito: <name>.msix)
--name <name> Nome do pacote (por defeito: do manifesto)
--manifest <path> Caminho do AppxManifest.xml (predefinido: detecção automática)
--cert <path> Caminho para a assinatura do certificado (ativa a assinatura automática)
--cert-password <password> Palavra-passe do certificado (por defeito: "palavra-passe")
--generate-cert Gerar um novo certificado de desenvolvimento
--install-cert Instalar certificado na máquina
--publisher <name> Nome do Publisher para geração de certificados
--self-contained Incluir o runtime do Windows App SDK
--skip-pri Saltar a geração de ficheiros PRI
--executable <path> Caminho do executável em relação à pasta de entrada. Usado para resolver $targetnametoken$ marcadores de posição no manifesto.

O que faz:

  • Valida e processa ficheiros AppxManifest.xml
  • Resolve $placeholder$ tokens no manifesto (ver marcadores do manifesto)
  • Garante que as dependências do framework estão corretamente definidas
  • Atualiza manifestos lado a lado com registos
  • Gere a implementação autónoma do Windows App SDK
  • Assina o 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

criar-identidade-debug

Criar identidade da aplicação para depuração sem pacotes MSIX completos usando uma localização externa/empacotamento esparso.

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

Argumentos:

Argumento Descrição
entrypoint Caminho para ficheiro executável (.exe) ou script que requer identidade

Opções:

Option 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 como está, sem adicionar .debug ao nome do pacote e ao identificador 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

Comandos manifestos

gerar manifesto

Gera AppxManifest.xml a partir de templates.

winapp manifest generate [directory] [options]

Argumentos:

Argumento Descrição
directory Diretório para gerar o manifesto (padrão: diretório atual)

Opções:

Option Descrição
--package-name <name> Nome do pacote (por defeito: nome da pasta)
--publisher-name <name> Publisher CN (padrão: CN=<current user>)
--version <version> Versão (por defeito: "1.0.0.0")
--description <text> Descrição (por defeito: "A Minha Candidatura")
--entrypoint <path> Ponto de entrada executável ou script
--template <type> Tipo de modelo: packaged (por defeito) ou sparse
--logo-path <path> Caminho para o ficheiro de imagem do logótipo
--if-exists <Error\|Overwrite\|Skip> Comportamento se o ficheiro já existir (padrão: Erro)

Modelos:

Espaços reservados para manifestos

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

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

Como os placeholders são resolvidos:

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

Sugestão

Manter $targetnametoken$ no seu manifesto de check-in evita codificar nomes de executáveis e funciona tanto com winapp pack como com os builds 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 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:

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

Opções:

Option Descrição
--manifest <path> Caminho para o ficheiro AppxManifest.xml (por defeito: pesquisar no diretório atual)

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

# 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 pacotes.

winapp cert generate [options]

Opções:

Option Descrição
--manifest <appxmanifest.xml> Extrair informação do editor de appxmanifest.xml
--publisher <name> Nome da Editora do certificado
--output <path> Caminho do ficheiro de certificado de saída
--password <password> Palavra-passe do certificado (por defeito: "palavra-passe")
--valid-days <days> Número de dias em que o certificado é válido (padrão: 365)
--install Instale o certificado no repositório local do computador após a geração
--if-exists <Error\|Overwrite\|Skip> Comportamento se o ficheiro de certificado já existir (padrão: Erro)

Instalação do certificado

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

winapp cert install <cert-path>

Argumentos:

Argumento Descrição
cert-path Caminho para o ficheiro de certificado para instalação

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

símbolo

Assinar pacotes e executáveis MSIX com certificados.

winapp sign <file-path> [options]

Argumentos:

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

Opções:

Option Descrição
--cert <path> Caminho para assinar o certificado
--cert-password <password> Palavra-passe do certificado (por defeito: "palavra-passe")

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 úteis

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 do Windows SDK de 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 descarrega o CLI de Desenvolvimento da Microsoft Store se ainda não tiver sido descarregado. Saiba mais em Microsoft Store Developer CLI.

winapp store [args...]

Argumentos:

Argumento Descrição
args... Argumentos para passar diretamente para o 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

Obtenha caminhos para os componentes instalados do SDK do Windows.

winapp get-winapp-path [options]

Retorna os caminhos para a diretoria da área de trabalho .winapp, os diretórios de instalação de pacotes e as localizações de cabeçalhos gerados.

Node.js e comandos do Electron

Estes comandos estão disponíveis apenas no pacote NPM.

Node Create-Addon

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

npx winapp node create-addon [options]

Opções:

Option Descrição
--name <name> Nome do addon (por defeito: "nativeWindowsAddon")
--template Selecione o tipo de addon: cs ou cpp (por defeito: cpp)
--verbose Ativar saída detalhada

O que faz:

  • Cria diretório de addons com ficheiros modelo
  • Gera binding.gyp e ficheiros addon com exemplos do SDK do Windows
  • Instala dependências necessárias de npm
  • Adiciona um script de build à 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

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

Adicione identidade de aplicação ao processo de desenvolvimento do Electron usando embalagens esparsas. Requer um appxmanifest.xml (criar um com winapp init ou winapp manifest generate).

Importante

Há um problema conhecido com aplicações Electron com embalagens esparsas que faz com que a aplicação crashe ao iniciar ou não renderize conteúdo web. O problema foi resolvido no Windows, mas ainda não se propagou a todos os dispositivos. Podes desativar o sandboxing na tua app Electron com a --no-sandbox flag como solução alternativa. Este problema não afeta a embalagem completa do MSIX.

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

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

Opções:

Option Descrição
--manifest <path> Caminho para appxmanifest.xml personalizado (por defeito: appxmanifest.xml no diretório atual)
--no-install Não instale nem modifique dependências; configure apenas a identidade de depuração do Electron
--keep-identity Mantém a identidade do manifesto como está, sem acrescentar .debug
--verbose Ativar 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

nó clear-electron-debug-identity

Eliminar a identidade do pacote do processo de depuração do Electron restaurando o ficheiro electron.exe original a partir do backup.

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

Opções:

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

Exemplos:

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