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 de projeto selecionado, ou diretório atual caso não seja detetado projeto)
• --setup-sdks - Modo de instalação do SDK: 'estável' (predefinido), 'pré-visualização', 'experimental' ou 'nenhum' (saltar a instalação do SDK)
• --ignore-config, --no-config - Não use ficheiro de configuração para gestão de versões
• --no-gitignore - Não atualize o ficheiro .gitignore
• --use-defaults, --no-prompt - Não faça um pedido e use o padrão de todos os prompts
• --config-only - Apenas tratar de operações de ficheiros de configuração, saltar a instalação de pacotes
• --exe <path> - Caminho para o executável da aplicação. Requer --sparse. Gera um manifesto esparso apenas de identidade para o exe, em vez de uma configuração completa de pacote/SDK.
• --sparse - Gerar um manifesto de identidade esparso (appxmanifest.xml) para um ex-executante de ambiente de trabalho existente. Ignora a instalação do SDK/pacote. Utilizar com --exe.
• --name <name> - Sobrescrever o nome do pacote (apenas esparso; padrão: inferido a partir do exe)
• --publisher <CN> - Substituir o editor CN (apenas esparso; padrão: inferido a partir do nome da empresa do exe)
• --output-dir <path> - Diretório para escrever o manifesto esparso e Assets/ (apenas esparso; por defeito: uma sparse/ pasta no diretório atual)
• --force - Sobrescrever um existente appxmanifest.xml no diretório de destino (apenas esparso). Sem isso, o init falha em vez de substituir um manifesto/ativos existentes.
• --add-js-bindings (apenas npm) - Adicionar winapp.jsBindings à package.json e gerar ligações JS/TypeScript, sem necessidade de pedido (incompatível com --setup-sdks none)

O que faz:

• Cria winapp.yaml ficheiro de configuração (apenas quando os pacotes SDK são geridos; ignorado com --setup-sdks none)
• Descarrega pacotes do Windows SDK e do SDK de Aplicações Windows
• Gera cabeçalhos e binários em C++/WinRT
• Cria o Package.appxmanifest
• Configura ferramentas de compilação e ativa o modo de programador
• Atualiza o .gitignore para excluir ficheiros gerados
• Armazena ficheiros partilháveis no diretório global de cache
• Gera ligações JS para APIs do SDK de Aplicações Windows quando ativadas (apenas npm)

Deteção automática de projetos:

Quando init é executado sem um argumento de diretório, realiza uma pesquisa em larga escala na árvore de diretórios atual para encontrar projetos compatíveis (até 10). Tipos de projetos suportados:

• Tauri — tauri.conf.json encontrado um nível abaixo do diretório
• Electron — package.json com electron dependências in ou devDependencies
• Flutter — pubspec.yaml na raiz do projeto
• .NET — .csproj na raiz do projeto
• Ferrugem — Cargo.toml na raiz do projeto
• C++ — CMakeLists.txt na raiz do projeto

A pesquisa ignora diretórios normalmente ignorados (node_modules, bin, obj, .git, etc.). Quando um projeto compatível é encontrado, os subdiretórios abaixo dele não são pesquisados.

• Se for fornecido um argumento de diretório (por exemplo, winapp init . ou winapp init path/to/project), a pesquisa é ignorada e init verifica apenas esse diretório para um projeto compatível
• Se --use-defaults (ou --no-prompt) estiver definido sem um argumento de diretório, init ignora a pesquisa e inicializa o diretório atual de forma não interativa, avisando primeiro se não for detetado nenhum tipo de projeto conhecido (por exemplo, winapp init --use-defaults)
• Em ambientes não interativos (stdin canalizado, CI, entrada redirecionada), init usa --use-defaults automaticamente o comportamento e emite um aviso: Non-interactive environment detected. Using default values.
• Se o diretório atual for um projeto compatível, init avança imediatamente
• Se exatamente um projeto for encontrado noutro local, é solicitado a confirmar
• Se forem encontrados vários projetos, pode selecionar qual inicializar — o diretório atual está sempre disponível como opção de remédio
• Se não forem encontrados projetos, é avisado e perguntado se deve avançar na mesma
• Se a pesquisa atingir o limite de 10 projetos, um aviso sugere fornecer um argumento de diretório

Fluxo automático do projeto .NET:

Quando um ficheiro .csproj é encontrado no diretório de destino, init utiliza um fluxo simplificado .NET específico:

• Valida e atualiza o TargetFramework para um TFM compatível com Windows (por exemplo, net10.0-windows10.0.26100.0)
• Adiciona Microsoft.WindowsAppSDK e Microsoft.Windows.SDK.BuildTools como entradas NuGet PackageReference diretamente no .csproj
• Gera Package.appxmanifest, ativos e um certificado de desenvolvimento
• Não cria winapp.yaml nem descarrega projeções em C++ (usa dotnet restore para pacotes NuGet)

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

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

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

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

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

Exemplos:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

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

Dica: Instale SDKs após a configuração inicial

Se executaste init ( --setup-sdks none ou ignoraste a instalação do SDK) e mais tarde precisaste dos SDKs:

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

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

---

novo

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

winapp new [options]

Opções:

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

Modelos:

O pacote inclui dois estilos de aplicação WinUI. Os templates XAML definem a interface em marcação com um code-behind em C#. Os templates do reator são puro C# sem XAML, usando um padrão MVU (Model-View-Update). A lista de modelos é lida em direto a partir do pacote instalado, por isso reflete sempre a versão que tens — corre winapp new --list para ver o conjunto atual. Modelos comuns:

Nome abreviado	Descrição
winui	Aplicação XAML mínima em branco (embalagem MSIX)
winui-navview	Aplicação inicial do XAML NavigationView
winui-tabview	Aplicação inicial XAML TabView
winui-mvvm	Aplicação MVVM XAML (CommunityToolkit.Mvvm)
winui-lib	Biblioteca de classes WinUI 3
winui-unittest	Aplicação MSTest embalada; Os testes são realizados quando é lançado
reactor	Experimental. Aplicação Blank Reactor — C# puro, sem XAML
reactor-mvu	Experimental. Aplicação Reactor a demonstrar o padrão MVU
reactor-navview	Experimental. Navegação do Reator Ver aplicação inicial
reactor-tabview	Experimental. Aplicação inicial Reactor TabView

Os modelos dos reatores são experimentais. Referem-se aos pacotes de pré-lançamento Microsoft.UI.Reactor , cujas APIs podem ser alteradas ou removidas numa versão futura. winapp new marca-os (Experimental) no --list e no seletor interativo, define "Experimental": true--json, e imprime um aviso após andaimar um. Nunca são escolhidos como modelo padrão. O Reactor também requer o SDK .NET 10 ou mais recente; num SDK winapp new mais antigo, falha logo com a versão necessária em vez de estruturar um projeto que não consegue construir.

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

Versionamento de templates packs:

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

Uma primeira execução pode demorar mais: Instalar ou atualizar o pacote de templates, ou restaurar pacotes NuGet do SDK de Aplicações Windows em falta usados pelo template selecionado, pode exigir downloads adicionais. Isto também pode acontecer após a publicação de uma nova versão do SDK de Aplicações Windows. Se o andaime continuar a funcionar após 10 segundos, winapp new atualiza a sua mensagem de estado para indicar que os pacotes podem estar a descarregar ou restaurar.

O que faz:

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

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

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

Exemplos:

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

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

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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

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

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

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

---

repor

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

winapp restore [base-directory] [options]

Argumentos:

• base-directory - Diretório para restaurar (predefinido: diretório atual). Também seleciona de onde winapp.yaml e nuget.config são lidos, a menos que --config-dir seja sobreposto.

Opções:

• --config-dir <path> - Diretório contendo winapp.yaml (predefinido: base-directory)

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

Observação

Para projetos .NET não winapp.yaml existe — as versões SDK estão disponíveis como PackageReference entradas no .csproj — por isso winapp restore executa dotnet restore para si.

Exemplos:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Feeds NuGet personalizados e privados:

winapp init, restore, e update descarregue os pacotes Windows SDK e SDK de Aplicações Windows através do NuGet, respeitando a sua hierarquia padrãonuget.config. Feeds privados e espelhos, credenciais de feed (incluindo fornecedores de credenciais) e um personalizado globalPackagesFolder funcionam todos como para dotnet restore. Para restaurar exclusivamente a partir do seu próprio espelho, <clear /> as fontes herdadas e adicionar apenas as suas:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Observação

Para projetos nativos, o winapp resolve nuget.config a partir do diretório onde opera: orestoreinit/argumento do diretório, --config-dir quando dado, caso contrário o diretório atual. Para projetos .NET, as fontes vêm da hierarquia nuget.config própria do projeto, porque é isso que dotnet add package e dotnet restore usam, por isso coloca a configuração de um feed privado no diretório do projeto ou num antepassado. Uma hierarquia fora dessa hierarquia é reportada e ignorada em vez de selecionar silenciosamente versões que --config-dir o projeto não consegue restaurar. Execute estes comandos apenas contra diretórios em que confie, a mesma cautela que se aplica a dotnet restore. Quando várias fontes estiverem configuradas, use o Mapeamento de Fonte de Pacotes para fixar cada pacote num feed.

---

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 um projeto ou diretórios de aplicações preparados. Requer que um ficheiro manifesto (Package.appxmanifest preferencial, appxmanifest.xml também suportado) esteja presente no diretório de destino, no diretório atual, ou passado com a --manifest opção. (correr init ou manifest generate criar um manifesto)

Passe um único .csproj para construir o projeto e empacotar a sua saída numa só etapa (modo projeto, veja Empacotamento de um projeto diretamente abaixo). Passe várias pastas de entrada para criar uma .msixbundle distribuição multi-arquitetura (ver pacotes Multi-arquitetura abaixo).

winapp pack <input-folder> [input-folder...] [options]

Argumentos:

• input-folder - Um único .csproj para compilar e empacotar (modo projeto), ou um ou mais diretórios contendo os ficheiros de aplicação a empacotar. Passe várias pastas (por exemplo, ./publish/x64 ./publish/arm64) para criar um bundle MSIX. Para pacotes de identidade esparsos, passe diretamente um ficheiro esparso appxmanifest.xml em vez de uma pasta (ver pacotes de identidade esparsa abaixo).

Opções:

• --output <filename> - Nome do ficheiro de saída. Para pacotes individuais: <name>_<version>_<arch>.msix (voltando para <name>_<version>.msix, <name>_<arch>.msix, ou <name>.msix). Para fibrados: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --name <name> - Nome do pacote (por defeito: do manifesto)
• --manifest <path> - Caminho para o ficheiro de manifestos (Package.appxmanifest preferencial, appxmanifest.xml também suportado; padrão: auto-deteção)
• --cert <path> - Caminho para o certificado de assinatura (ativa a assinatura automática)
• --cert-password <password> - Palavra-passe do certificado (por defeito: "password")
• --generate-cert - Gerar um novo certificado de desenvolvimento
• --no-sign - Entregar o pacote sem assinatura, sobrepondo-se a qualquer configuração de assinatura de projeto (por exemplo, para submissão de Store ou um pipeline de assinatura externo). Não pode ser combinado com --cert ou --generate-cert.
• --install-cert - Certificado de instalação na máquina
• --publisher <name>- Publisher para geração de certificados. Aceita um nome distinto completo X.500 ou um nome simples (automaticamente embrulhado como CN=<name>)
• --self-contained- Agrupar o tempo de execução do SDK de Aplicações Windows
• --skip-pri - Saltar geração de ficheiros PRI
• --executable <path> - Caminho para o executável relativo à pasta de entrada (também --exe). Usado para resolver $targetnametoken$ marcadores de posição no manifesto.

Opções em modo Project (requerem uma .csproj entrada; rejeitadas para entradas de pasta/bundle/manifest):

• --configuration <name> (-c) - Configuração de compilação (por defeito: Release)
• --arch <arch> - Arquitetura alvo: x64, arm64, ou x86 (padrão: a arquitetura atual do processo)
• --framework <tfm> (-f) - Denominação de framework alvo para projetos multi-direcionados
• --no-build - Empacotar a saída da build existente sem reconstruir
• --no-restore - Ignorar a restauração do projeto antes da construção
• --property <name=value> (-p) - Propriedade MSBuild, encaminhada para construção e avaliação (repetível)

Nota: Para um modo de projeto WinUI / EnableMsixTooling.csproj (ferramenta MSIX), o SDK de Aplicações Windows detém o manifesto, o ponto de entrada e a geração PRI, por isso --manifest, --executable, e --skip-pri são rejeitados — configure <AppxManifest>, o ponto de entrada do projeto e a sua construção de recursos no próprio projeto. Essas três opções ainda se aplicam a entradas de pastas e ao modo de projeto genérico (não MSIX). .csproj

O que faz:

• Valida e processa ficheiros Package.appxmanifest
• Resolve $placeholder$ tokens no manifesto (ver marcadores de Manifesto abaixo)
• Garante que as dependências do framework estão corretamente definidas
• Atualiza manifestos lado a lado com registos
• Descobre e agrupa automaticamente quaisquer ficheiros que não sejam imagem referenciados no manifesto (por exemplo, AppExtension manifest.json, ficheiros de configuração) do diretório do manifesto ou da pasta de entrada se estiverem em falta no staging
• Descobre automaticamente componentes WinRT de terceiros e regista as suas classes ativables (ver descoberta de componentes WinRT abaixo)
• Trata da implementação autónoma do WinAppSDK
• Assina o pacote se o certificado for fornecido

Empacotamento direto de um projeto

Quando a entrada é uma única .csproj, winapp pack constrói o projeto (usando as opções acima) e empacota a saída resultante — não é necessário construir separadamente ou localizar primeiro a pasta de saída. Isto espelha winapp runo modo de projeto.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

A arquitetura alvo vem de --arch, ou de um lone -p RuntimeIdentifier=<rid> quando não passas --arch (o RID exato é preservado e gere a build). Passar em ambos --arch-p RuntimeIdentifier é um conflito e é rejeitado.

O projeto deve compilar como uma aplicação empacotada (EnableMsixTooling=true com um Package.appxmanifest); um projeto que se compila como uma aplicação não empacotada (WindowsPackageType=None) não tem manifesto MSIX para empacotar e winapp pack reporta um erro acionável. As entradas de pasta, bundle e spars-manifest mantêm-se inalteradas.

O modo Project produz um único .msix ou apenas .msixbundle um conjunto de arquitetura (ver pacotes Multi-arquitetura). Não produz arquivos Store-upload nem bundles de divisão de recursos (linguagem/escala): um explicit -p UapAppxPackageBuildMode=StoreUpload ou -p AppxBundleAutoResourcePackageQualifiers=... é rejeitado com uma nota para executar o comando nativo de empacotamento do SDK diretamente para esses fluxos.

Pacotes de identidade esparsos

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

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

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

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

Descoberta de componentes WinRT

Ao ser empacotado, winapp pack escaneia automaticamente os pacotes NuGet definidos no winapp.yaml ou *.csproj para componentes WinRT de terceiros (por exemplo, Win2D). Analisa .winmd ficheiros para extrair nomes de classes ativables e localiza as suas DLLs de implementação. As entradas descobertas são registadas da seguinte forma:

• Dependente do framework (por defeito): Classes ativables são adicionadas como <InProcessServer> entradas no Package.appxmanifest
• Auto-contido (--self-contained): Classes ativables estão incorporadas em manifestos lado a lado (SxS) dentro do executável

Resolução provisória durante a embalagem:

Se o manifesto contiver $targetnametoken$ no Executable atributo:

1. Se --executable for fornecido (caminho relativo à pasta de entrada), o marcador é substituído pelo valor especificado
2. Caso contrário, winapp pack analisa a raiz da pasta de entrada à procura .exe de ficheiros — se for encontrado exatamente um, é usado automaticamente
3. Se forem encontrados zero ou múltiplos .exe ficheiros, aparece um erro a pedir que especifique --executable

Exemplos:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Pacotes multi-arquitetura

Quando várias pastas de entrada são passadas, winapp pack cria-se uma .msixbundle contendo uma .msix por arquitetura:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

O comando deteta automaticamente a arquitetura de cada pasta a partir do cabeçalho PE do executável principal, valida a consistência entre fatias (Identidade, Capacidades, Dependências) e produz um <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Resolução manifesta para fibrados:

Cada fatia do feixe precisa de um manifesto. O comando resolve manifesta-se nesta ordem:

1. --manifest <path> — Se especificado, este manifesto único é usado para todas as fatias. É ProcessorArchitecture automaticamente atualizado por fatia para corresponder à arquitetura detetada.

2. Manifesto por pasta — Se cada pasta de entrada contiver um Package.appxmanifest (ou appxmanifest.xml), o manifesto dessa pasta é usado para a sua fatia.

3. Alternativa do diretório atual — Se uma pasta não tiver manifesto, o comando procura Package.appxmanifest no diretório de trabalho atual e usa-o (com a arquitetura carimbada automaticamente).

Em todos os casos, o manifesto é atualizado automaticamente: os marcadores são resolvidos, as dependências são injetadas e ProcessorArchitecture o manifesto é forçado para a arquitetura detetada. Após a resolução, uma validação cross-slice assegura que a Identidade (Nome, Versão, Publisher), Capacidades e Dependências são consistentes em todas as fatias — apenas ProcessorArchitecture podem diferir. A versão do pacote definida nas fatias é atribuída à versão do bundle MSIX, exceto se for 0.0.0.0, caso em que uma versão baseada em carimbo temporal é gerada automaticamente.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

---

criar-identidade-debug

Criar identidade de aplicação para depuração usando empacotamento sparse. O exe mantém-se na sua localização original — Windows associa a identidade a ele através de Add-AppxPackage -ExternalLocation.

Quando usar isto ou winapp runquando usar: Usar create-debug-identity quando o exe está separado do código da sua aplicação (por exemplo, aplicações Electron onde electron.exe está inserido node_modules), ou quando testar especificamente o comportamento dos pacotes esparsos. Para a maioria dos frameworks onde o exe está na pasta de saída da build, use winapp run em vez disso — ele regista um pacote completo de layout solto e inicia a aplicação. Consulte o Guia de Depuração para uma comparação completa.

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

Argumentos:

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

Opções:

• --manifest <path> - Caminho para o ficheiro de manifesto da aplicação, seja Package.appxmanifest ou ou appxmanifest.xml (por defeito: auto-deteção Package.appxmanifest ou appxmanifest.xml no diretório atual)
• --no-install - Não instalar o pacote após a criação
• --keep-identity - Manter a identidade do manifesto as-is, sem acrescentar .debug ao nome do pacote e ao ID da aplicação

O que faz:

• Modifica o manifesto lado a lado do executável
• Regista pacote disperso para identidade
• Permite depurar APIs que requerem identidade

Exemplos:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

---

Identidade embed-

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

winapp embed-identity <target> [options]

Argumentos:

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

Opções:

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

Exemplos:

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

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

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

---

manifesto

Gerar e gerir ficheiros Package.appxmanifest.

gerar manifesto

Gerar o Package.appxmanifest a partir de templates.

winapp manifest generate [directory] [options]

Argumentos:

• directory - Diretório para gerar manifestos em (por defeito: diretório atual)

Opções:

• --package-name <name> - Nome do pacote (por defeito: nome da pasta)
• --publisher-name <name>- Publisher nome distinto (por defeito: CN=<utilizador> atual). Aceita um DN X.500 com componentes de valor único, separados por vírgulas (RDNs multi-valor + e barras adicionais não são suportados); os nomes simples são automaticamente encapsulados como CN=<nome>.
• --version <version> - Versão (por defeito: "1.0.0.0")
• --description <text> - Descrição (por defeito: "A Minha Candidatura")
• --entrypoint <path> - Executável ou script de ponto de entrada
• --template <type> - Tipo de modelo: packaged (por defeito) ou sparse
• --logo-path <path> - Ficheiro de imagem do caminho para o logótipo
• --if-exists <Error|Overwrite|Skip> - Comportamento quando o ficheiro manifest já existe no caminho de destino (padrão: Error)

Modelos:

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

Espaços reservados para manifestos

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

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

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 ficheiro deve declarar o seu próprio tamanho, através de atributos a viewBox ou absoluto width e height e; uma largura percentual com não viewBox não define nenhum tamanho específico. Uma fonte que declara nenhum dos dois é rejeitada em vez SVG image has no usable dimensions de apresentar ativos em branco.

O comando escala as imagens proporcionalmente, mantendo a proporção de aspeto, centrando-as com fundos transparentes quando necessário. Os ativos são guardados no diretório Assets relativamente à localização do manifesto.

Exemplos:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

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

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

---

execução

Crie um pacote de layout solto a partir de uma pasta de saída de compilação, regista-o com Windows usando a API Windows.Management.Deployment.PackageManager e inicie a aplicação — simulando uma instalação completa do MSIX para depuração. Devolve o ID do processo para anexo do depurador.

winapp run Funciona num de três modos, escolhidos automaticamente a partir da entrada:

• Modo pasta — a entrada é uma pasta build-output (contém um Package.appxmanifest/AppxManifest.xml).
• Modo Project — a entrada é um .csproj, uma .sln/.slnx solução ou um diretório que contém um. winapp run constrói o projeto e lança-o, suportando tanto aplicações WinUI empacotadas como não empacotadas . Veja o modo Project abaixo.
• Modo de ficheiro único — a entrada é uma .csaplicação baseada em ficheiros .NET. winapp run constrói-o, gera um manifesto a partir das suas #:property diretivas e lança-o com identidade de pacote.

Sugestão

A seleção de modos é silenciosa por defeito. Se um diretório foi tratado como uma pasta build-output quando esperava que fosse construído como um projeto, re-execute com --verbose — o modo pasta indica porque foi escolhido (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Um diretório só é construído como um projeto quando um .csproj/.slnx/.slncom uma aplicação executável está ao seu nível superior; não é pesquisado recursivamente.

Este é o comando preferido para depuração com identidade de pacote para a maioria dos frameworks (.NET, C++, Rust, Flutter, Tauri). Ao contrário create-debug-identity de que regista um pacote esparso para um único exe, winapp run regista toda a pasta como um pacote de layout solto, tal como numa instalação real do MSIX. Consulte o Guia de Depuração para fluxos de trabalho comuns de depuração.

winapp run [<input>] [options]

Argumentos:

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

Opções:

• --manifest <path> - Caminho para Package.appxmanifest (padrão: auto-deteção a partir da pasta de entrada ou diretório atual)
• --output-appx-directory <path> - Diretório de saída para o layout solto (por defeito: AppX dentro da pasta de entrada). O layout padrão remove ficheiros que já não estão na build; um diretório personalizado mantém ficheiros extra. Usa um diretório personalizado novo quando precisares de um layout limpo.
• --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. Raramente necessário: uma aplicação que OutputType=Exe já abre assim por defeito. o winapp adiciona o necessário uap5:ExecutionAlias ao manifesto que está a criar no layout do AppX, pelo que não é necessária qualquer alteração ao seu manifesto check-in; um alias que a app declara é usado as-is. Não pode ser combinado com --no-launch, --detach, --without-alias, ou --json.
• --without-alias - Forçar a ativação de AUMID para uma aplicação que, de outra forma, seria lançada através de um alias de execução. Uma aplicação de consola corre então sem consola e não imprime nada neste terminal. Não pode ser combinado com --with-alias.
• --debug-output - Capturar OutputDebugString mensagens e exceções de primeira oportunidade da aplicação lançada. O ruído do framework (WinUI, COM, DirectX) é filtrado da saída da consola; O ficheiro de registo completo regista tudo. Se a aplicação crashar, captura automaticamente um minidump e analisa-o para mostrar o tipo de exceção, a mensagem e o traço da pilha com o ficheiro de origem:números de linha (resolvido a partir dos PDBs na pasta de saída da compilação). As falhas geridas (.NET) são analisadas instantaneamente sem ferramentas externas. Crashes nativos (C++/WinRT) mostram nomes e deslocamentos de módulos. Quando a aplicação com falha é uma aplicação WinUI 3 (Microsoft.UI.Xaml.dll está carregada), uma passagem extra de triagem de exceções armazenadas é executada automaticamente para repor o HRESULT de origem, a sua cadeia ErrorContext e a pilha nativa completa de despacho XAML; os componentes de depuração necessários são descarregados na primeira utilização (ver Debugging, overridable via a WINAPP_DBGTOOLS_DIR variável de ambiente). Apenas um depurador pode ser ligado a um processo de cada vez, pelo que outros depuradores (Visual Studio, VS Code) não podem ser usados simultaneamente. Usa --no-launch em vez disso se precisares de anexar um depurador diferente. Não pode ser combinado com --no-launch. Não pode ser combinado com --json.
• --symbols - Descarregue símbolos PDB do Microsoft Symbol Server para uma análise nativa de falhas mais rica com nomes de funções resolvidos. Utilizado apenas com --debug-output. Se for omitido e ocorrer um crash nativo, a saída sugerirá adicionar esta bandeira. Este flag também melhora a pilha de triagem de exceções armazenadas do WinUI para aplicações WinUI 3. A primeira corrida descarrega símbolos e armazena-os em cache localmente; As execuções subsequentes utilizam a cache.
• --unregister-on-exit - Desregistar o pacote de desenvolvimento após o encerramento da aplicação. Apenas remove pacotes registados em modo de desenvolvimento. Não pode ser combinado com --no-launch.
• --detach - Iniciar a aplicação e regressar imediatamente, sem esperar que saia. Útil para CI/automação, onde precisas de interagir com a aplicação após o lançamento. As execuções locais imprimem o PID; as execuções do alvo imprimem o alvo da interface com escopo. O JSON inclui o PID e o telescópio do alvo. 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.
• --on <target> - Construir sobre o host, depois registar e executar no alvo. Atualmente suporta sandbox, sem recorrer à execução local. Use --detach antes dos comandos de UI seguintes. O Sandbox --debug-output requer uma aplicação incluída. Consulte a execução do Sandbox no Windows para configuração, suporte em tempo de execução e vida útil da aplicação separada.

Persistência dos dados da aplicação:

Por defeito, winapp run preserva os dados da sua aplicação (LocalState, RoamingState, Settings, etc.) ao reimplantar. Se a sua aplicação gravar dados no ApplicationData.Current.LocalFolder contexto do pacote ou Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dentro dele, esses dados sobreviverão através das winapp run invocações.

Use --clean quando precisar de um novo começo (por exemplo, para reiniciar o estado corrompido ou testar o comportamento da primeira execução).

O que faz:

• Localiza ou gera o Package.appxmanifest
• Cria e regista uma identidade de depuração usando um pacote de layout frouxo
• Calcula o ID do Modelo de Utilizador da Aplicação (AUMID)
• Lança a aplicação usando a identidade registada (a menos que --no-launch seja especificado)
• Imprime o ID do processo (PID) para anexo do depurador

Exemplos:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Modo Project (projetos .NET SDK)

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

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

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

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

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

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

AOT nativo: adicione este grupo de propriedades dentro do elemento do <Project> ficheiro do project, depois adicione--aot:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aotsuporta projetos x64 e ARM64 e requer o SDK .NET 8.0.300 ou mais recente. Corre dotnet publish com a configuração AOT do projeto, depois lança essa saída; usada -p PublishAot=true como substituição única. Não realiza certificação em tempo de execução separada e não pode ser combinada com --no-build ou --manifest.

Para aplicações que usam identidade de pacote sem um layout MSIX gerado, inclua Package.appxmanifest ou appxmanifest.xml na saída de publicação do projeto. A Winapp organiza os ficheiros publicados com esse manifesto. Se ambos os nomes estiverem presentes, o winapp para em vez de escolher um; remover o manifesto obsoleto e configurar o projeto para publicar apenas o manifesto pretendido.

Opções do modo Project (ignoradas no modo de pasta, salvo indicação):

• -c, --configuration <name> - Configuração de construção. Padrão: Debug. (Também homenageado em modo em fila indiana.)
• --arch <x64|arm64|x86> - Arquitetura alvo. Padrão: a arquitetura atual do processo. Determina a arquitetura build RID e Aplicação do Windows Runtime, e seleciona um perfil de publicação dependente da plataforma correspondente quando necessário pela build efetiva. (Também homenageado em modo em fila indiana.)
• -r, --runtime <rid>- Identificador de runtime .NET do alvo (por exemplo, win-x64). O modo Project utiliza apenas a arquitetura do RID, constrói sempre o canónico win-<arch>, e rejeita RIDs que não sejam do Windows (por exemplo, linux-x64). A sua arquitetura sobrepõe-se --arch e pode selecionar o perfil de publicação necessário. (Também é respeitado em modo de fila única, onde sobrepõe um #:property RuntimeIdentifier declarado pelo ficheiro.)
• -f, --framework <tfm> - Nome de framework alvo para projetos multi-direcionados (por exemplo, net10.0-windows10.0.26100.0). (Rejeitado em modo de fila única — usar #:property TargetFramework=....)
• --project <name-or-path> - Quando a entrada é uma solução (.sln/.slnx) ou um diretório com múltiplos projetos de aplicação executáveis, seleciona-se qual projeto lançar (por nome ou caminho). (Rejeitado em modo de ficheiro único — uma .cs aplicação baseada em ficheiros é ela própria o projeto.)
• --no-build - Saltar a construção e executar a saída da build existente (ainda avaliando as propriedades da saída). (Também homenageado em modo em fila indiana.)
• --no-restore - Evite restaurar antes de construir ou publicar em AOT nativo. (Também homenageado em modo em fila indiana.)
• --aot- Executar a publicação nativa do AOT em .NET configurada pelo projeto. Requer .PublishAot=true Rejeitado em modos de pasta e ficheiro único.
• -p, --property <Name=Value> - Propriedade MSBuild, encaminhada tanto para a construção como para a avaliação da propriedade. Repita -p para múltiplas propriedades; use %3B ou %2C para um ponto e vírgula literal ou vírgula num valor. (Também é homenageado no modo em fila única, onde é a única forma de definir TargetFramework.)

Saída de build & verbosidade: uma execução de projeto comum usa dotnet build, depois avalia a saída construída. Restaurar e construir o fluxo de saída em direto, com as credenciais dos URLs autenticados dos feeds ocultos. Com , o --aotwinapp usa dotnet publish; --verbose mostra o comando publish e os caminhos resolvidos. Use as opções de verbosidade abaixo para controlar o que é mostrado:

Flag	Verborrosidade dotnet	Acrescenta
(padrão)	minimal	—
--verbose	minimal	Traços da decisão de construção da Winapp
--quiet	quiet	—

O AOT nativo publica os fluxos de saída à medida que chegam. Em --json, restore/build invocações e output filho vão para stderr, por isso stdout mantém-se puro JSON. Em --quiet, as invocações são suprimidas e a saída silenciosa de restauro/build do dotnet é encaminhada para stderr, para que o stdout se mantenha limpo. A saída nativa de publicação AOT também vai para stderr em qualquer uma das opções.

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

Exemplos em modo Project:

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

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

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

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

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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

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

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

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

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

Modo de ficheiro único (aplicações baseadas em ficheiros .NET)

O .NET 10 permite-te executar um único .cs ficheiro sem ficheiro de projeto, configurando-o com #: diretivas no topo. Basta apontar winapp run para esse ficheiro e ele constrói a aplicação, gera um appxmanifest para ela e lança-o com a identidade do pacote — assim Windows.ApplicationModel.Package.Current funciona, a aplicação recebe um AUMID real e uma entrada no menu Iniciar, e as APIs que simplesmente requerem identidade (notificações da app, ApplicationData, IA no dispositivo) funcionam.

Integrações de shell, como manipuladores de protocolo, associações de ficheiros, alvos de partilha e tarefas de arranque, necessitam de uma entrada declarada <Extensions> , que o manifesto gerado não contém. Para adicionar uma, crie o seu próprio manifesto — veja Traga o seu próprio manifesto abaixo.

winapp run counter.cs

Ou execute-o com o simples dotnet run — veja Correr com dotnet run abaixo.

Não se escreve um manifesto. Descreva o pacote com #:property diretivas em vez disso:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Propriedades manifestas. Todos são opcionais; cada um volta a um padrão sensato:

Property	Conjuntos	Predefinição
WinAppPackageName	Identity/@Name (a identidade da embalagem)	o nome do ficheiro, sanitizado para [-.A-Za-z0-9], mais um pequeno hash do caminho do ficheiro (counter.cs → counter-a1b2c3d4)
WinAppDisplayName	O nome mostrado em Início e Definições	o nome do ficheiro sem a sua extensão
WinAppPublisher	Identity/@Publisher	CN=<your Windows user name>. Um nome simples é enrolado como CN=<name>.
WinAppVersion	Identity/@Version	$(Version), normalizado (ver abaixo)
WinAppDescription	A descrição mostrada durante a instalação e nas Definições	O nome de exibição
WinAppCapabilities	Capacidades para declarar, separadas por ; ou ,	none

Version. Uma versão em pacote deve ter exatamente quatro números, cada um de 0 a 65535. WinAppVersion(ou, se não definir, a propriedade padrãoVersion) é normalizado para ajustar: qualquer -preview-rc/sufixo é eliminado e os componentes em falta são preenchidos com zeros, tornando-se #:property Version=1.2.3-preview.41.2.3.0 e junta a sua versão assembly e a versão do pacote. Um valor que não pode ser ajustado — um componente acima de 65535, ou mais de quatro componentes — é rejeitado com um erro em vez de ser alterado silenciosamente.

Capabilities

A sua aplicação corre em modo total de confiança com identidade, o que satisfaz APIs que só requerem uma aplicação empacotada. Mas algumas APIs estão bloqueadas por uma capacidade declarada — as APIs de IA do Windows são o caso comum. (Integrações shell, como handlers de protocolo e associações de ficheiros, são um terceiro caso: essas precisam de entradas autoradas <Extensions> , não de uma capacidade, por isso use o seu próprio manifesto para elas.)

#:property WinAppCapabilities=systemAIModels

Isto é tudo o que a Phi Silica e as outras APIs do modelo no dispositivo precisam do manifesto. Declare vários separando-os:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

O winapp grava cada um no espaço de nomes elemento e XML que realmente necessita, declara esse espaço de nomes e aumenta MaxVersionTested quando a capacidade precisa de um mais recente. Isto importa mais do que parece: as capacidades estão distribuídas por vários elementos diferentes, e a mesma lista acima transforma-se em três formas diferentes —

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Nomes que a winapp sabe que são escritos para si. Para qualquer outra coisa — o conjunto restrito cresce com o tempo — qualifica-o tu próprio com o prefixo namespace:

Prefixo	Emite
rescap:	<rescap:Capability> — capacidades restritas
uap:, uap6:, uap7:, uap11:	<uap*:Capability>
systemai:	<systemai:Capability>
device:	<DeviceCapability>
app:	<Capability> no espaço de nomes padrão

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Um nome não reconhecido é rejeitado com um erro que nomeia esses prefixos, em vez de ser adivinhado — uma capacidade emitida no namespace errado produz um manifesto que o Windows ou se recusa a registar ou aceita enquanto silenciosamente não o concede.

Traga o seu próprio manifesto

Se precisar de algo que as propriedades não cobrem — um gestor de protocolo, uma associação de ficheiros, um alias de execução — crie um manifesto e winapp run usá-lo-á literalmente em vez de gerar um. É recolhido de, por ordem:

1. --manifest <path> na linha de comandos.
2. #:property WinAppManifestPath=<path> no .cs ficheiro.
3. Um manifesto ao lado do .cs ficheiro, nomeado <filename>.appxmanifest (por exemplo counter.appxmanifest , ao lado counter.csde ).

Só esse nome por ficheiro é apanhado automaticamente. A ou appxmanifest.xml na mesma pasta é deliberadamente ignorado — vários .cs ficheiros podem partilhar uma pasta, e adotar um nome partilhado faria Package.appxmanifest uma aplicação correr silenciosamente sob a identidade de outra. Para usar um manifesto para vários ficheiros, nomeie-o explicitamente com --manifest ou WinAppManifestPath.

Caso contrário, a Package.appxmanifest é gerado na saída da compilação, juntamente com os ativos de imagem padrão, e atualizado em cada execução.

Options. Todas as opções de modo de pasta funcionam: --no-launch, --with-alias, --detach--without-alias, --clean, --debug-output, --symbols, --args--json/--executable--output-appx-directory--unregister-on-exit----manifestmais -c/--configuration, --no-build, , --no-restore, e .-p/--property

Sugestão

Uma aplicação de consola imprime no teu terminal por defeito. Uma aplicação empacotada lançada via AUMID não tem consola, por isso uma app só para consola correria corretamente e não imprimia nada. O WinApp evita isso: uma aplicação com OutputType=Exe é lançada através de um alias de execução, que herda o stdin/stdout/stderr deste terminal. Continua a receber a identidade do pacote, e não precisa de a pedir:

winapp run counter.cs

Passe --without-alias para forçar a ativação do AUMID em vez disso — a aplicação depois corre sem consola e não imprime nada aqui. Uma aplicação em janela (WinExe) mostra uma janela, por isso mantém a ativação do AUMID; passa --with-alias se quiseres uma neste terminal de qualquer forma. Para corrigir a escolha no ficheiro em vez de em cada linha de comandos, defina a mesma propriedade que o .csproj utiliza:

#:property WinAppRunUseExecutionAlias=false

O alias declarado pelo winapp é nomeado a partir do nome da família do pacote, com um winapp- prefixo — portanto com.contoso.counter , publicado por CN=You obtém winapp-com.contoso.counter_gspb8g6x97k2t.exe. Essa parte final é o hash do publisher que o Windows deriva, por isso duas aplicações que partilham o mesmo nome sob publishers diferentes continuam a receber alias diferentes. O prefixo mantém o nome livre de comandos reais: uma aplicação em python.cs recebe um winapp-… pseudónimo, nunca python.exe. Se criares o teu próprio manifesto, o alias que declaras lá é usado as-is e o winapp não acrescenta nada.

Isso aplica-se apenas ao pseudónimo. O registo em si é baseado no nome do pacote, por isso, executar uma segunda aplicação que declara o mesmo WinAppPackageName sob um editor diferente substitui o primeiro registo em vez de ficar ao lado dele. Dê a cada aplicação o seu próprio nome se quiser que ambas sejam registadas ao mesmo tempo.

winapp run imprime o alias que registou, por isso não precisas de calcular o hash para o encontrar.

O alias é um comando no seu PATH que dura enquanto o pacote permanecer registado. Se algum outro pacote já possui o nome, a Winapp diz que sim. Quando inferiu o pseudónimo para si, inicia via AUMID, em vez de iniciar a aplicação errada; quando pediu um explicitamente — com --with-alias ou #:property WinAppRunUseExecutionAlias=true — falha em vez de fazer outra coisa silenciosamente.

Duas opções de modo projeto não se aplicam, porque uma aplicação baseada em ficheiros configura-se sozinha. São rejeitados com uma mensagem que indica a diretiva a usar em vez disso:

Option	Use em vez disso
-f/--framework	#:property TargetFramework=net10.0-windows10.0.22621.0
--project	Nada — o .cs ficheiro é o projeto

--arch E -r/--runtime trabalham como fazem em modo projeto. Quando não passa nenhum dos dois, o winapp compila para a arquitetura da sua máquina — que é o que uma aplicação SDK de Aplicações Windows autónoma precisa, pois sem ela o SDK constrói AnyCPU e falha com WindowsAppSDKSelfContained requires a supported Windows architecture. A #:property RuntimeIdentifier=win-arm64 no ficheiro é respeitado; um explicit --arch/--runtime sobrepõe-o.

Empacotado e desempacotado funcionam, detetados a partir do efetivo WindowsPackageType exatamente como no modo projeto: o padrão regista um layout solto e lança-o com identidade, enquanto #:property WindowsPackageType=None constrói a aplicação, instala o Aplicação do Windows Runtime correspondente e lança o .exe direto. (Uma aplicação empacotada é lançada através do seu alias de execução ou através da ativação AUMID — veja a nota da consola acima; essa escolha é separada de ser empacotada.) As opções de identidade (--no-launch, --with-alias, --without-alias, --clean, --unregister-on-exit, --manifest, ) --output-appx-directoryaplicam-se apenas a aplicações empacotadas.

A correr com dotnet run

Não precisas de escrever winapp de todo. Faça referência ao Microsoft.Windows.SDK.BuildTools.WinApp pacote a partir do ficheiro e o Plain dotnet run apresenta o mesmo pacote de lançamento:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Os alvos do MSBuild do pacote redirecionam a execução para o winapp, que empacota e regista e lança a aplicação que dotnet run acabou de ser construída — não é reconstruída. O tratamento dos manifestos mantém-se inalterado: o winapp resolve exatamente como para winapp run, por isso #:property WinAppManifestPath=… e ao <filename>.appxmanifest lado de ambos .cs são honrados (ver Traga o seu próprio manifesto), um diretório em todo Package.appxmanifest o diretório continua ignorado, e de resto um é gerado a partir das suas #:property diretivas e atualizado a cada execução.

Duas condições têm de se cumprir para que o redirecionamento aconteça:

Directive	Porquê
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*	os alvos que fazem o redirecionamento neste pacote
#:property TargetFramework=net10.0-windows…	um ficheiro simples net10.0 é deixado intacto, por isso corre sem empacotar

Adicionar #:property WindowsPackageType=None também deixa o ficheiro intacto: dotnet run depois executa o .exe diretamente, sem identidade. Usa winapp run para o caminho não empacotado se quiseres instalar primeiro o Aplicação do Windows Runtime correspondente.

Definido #:property EnableWinAppRunSupport=false para optar por não receber o redirecionamento completamente, e as WinAppRun* propriedades descritas em Configuração para moldar o lançamento — por exemplo:

#:property WinAppRunUnregisterOnExit=true

Se dotnet run a aplicação correr sem empacotar quando esperava identidade, pergunte ao MSBuild porquê. Use dotnet build, not dotnet msbuild — sintetiza apenas dotnet build o projeto virtual através do qual uma aplicação baseada em ficheiros é compilada:

dotnet build counter.cs -t:WinAppRunSupportInfo

O modo de ficheiro único requer o SDK .NET 10.0.300 ou mais recente.

O registo dura mais do que a corrida. winapp run counter.cs deixa o pacote registado depois de a aplicação sair, exatamente como o modo pasta e projeto — por isso LocalState sobrevive, e reexecutar o mesmo ficheiro reutiliza a mesma identidade em vez de acumular registos. O WinApp diz isso logo na primeira vez que regista uma aplicação, e winapp unregister assume o .cs seu próprio processo:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs não precisa de caminho de manifesto: avalia os valores do #:property ficheiro da mesma forma run que o faz e remove apenas um pacote registado da saída de build desse ficheiro. Uma aplicação com o mesmo nome registada numa pasta diferente é recusada a menos que passe --force. Se a sequência usou uma opção que molda a identidade ou o layout, passe a mesma para unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p sobrepõe as próprias diretivas do ficheiro, e ao Directory.Build.props lado da .cs tecla WinAppPackageName can desliga $(Configuration) ou $(RuntimeIdentifier) — para que cada uma destas possa alterar qual o pacote que é registado.

Depois de a saída temporária do SDK ser limpa, winapp unregister counter.cs já não é possível confirmar que o registo veio desse ficheiro e vai saltá-lo — usar winapp unregister --prune para apagar registos cujos ficheiros desapareceram, ou --force para remover um específico na mesma. Se a execução usou --output-appx-directory, passa o mesmo diretório para unregister que possa reconhecer o layout.

O mesmo se aplica a um caminho de saída personalizado: a propriedade é confirmada a partir do layout padrão <root>\bin\<configuration> do SDK, pelo que uma execução construída com -p OutputPath=<somewhere-else> não pode ser correspondida ao seu ficheiro fonte. unregister ignora-o em vez de adivinhar um diretório mais amplo — nomeie o layout com --output-appx-directory, ou use --force.

Exemplos em fila única:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Observação

A identidade padrão inclui um pequeno hash do caminho do ficheiro — counter.cs que se torna algo como counter-a1b2c3d4 — por isso dois counter.cs ficheiros em pastas diferentes são aplicações diferentes e mantêm as suas próprias definições e LocalState. O hash é derivado do caminho, por isso sobrevive a edições e repetições e só muda se mover o ficheiro. Definir #:property WinAppPackageName=<name> para escolher uma identidade estável por si próprio; é normalizado para o que Identity/@Name permite — caracteres fora [-.A-Za-z0-9] são eliminados, nomes com menos de 3 caracteres são preenchidos com 1, e o resultado é limitado a 50 caracteres, registando-se My App como MyApp. De qualquer forma, o menu Iniciar e as Definições mostram o seu WinAppDisplayName (por defeito: o nome do ficheiro), não a identidade. A identidade está sempre ligada à tua conta de utilizador, por isso nunca colide com outro utilizador na mesma máquina.

Propriedades do MSBuild (pacote NuGet):

Ao usar o pacote NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run invoca automaticamente winapp run.

Tudo o que foi escrito a seguir dotnet run é entregue para a sua candidatura, exatamente como seria sem o pacote. Configure o lançador com as propriedades do MSBuild abaixo:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

As seguintes propriedades do MSBuild podem ser definidas em your .csproj to control behavior:

Property	Predefinição	Descrição
EnableWinAppRunSupport	true	Ativar/desativar a funcionalidade de suporte à execução
WinAppLaunchArgs	(vazio)	Argumentos para passar à aplicação no lançamento
WinAppRunUseExecutionAlias	Inferido a partir da aplicação	Lança via alias de execução em vez de ativação AUMID. Se não estiver definido, o winapp infere isso: uma aplicação de consola usa um alias para que a sua saída chegue ao terminal, uma aplicação em janela usa AUMID. Define true ou false decide tu próprio.
WinAppRunNoLaunch	false	Regista apenas a identidade sem iniciar
WinAppRunDebugOutput	false	Capturar OutputDebugString mensagens e exceções de primeira oportunidade. Apenas um depurador pode ser ligado de cada vez (previne o VS/VS Code). Use WinAppRunNoLaunch antes para anexar um depurador diferente.
WinAppRunDetach	false	Volte imediatamente após o lançamento em vez de esperar que a aplicação saia. Imprime o PID.
WinAppRunUnregisterOnExit	false	Desregista o pacote de desenvolvimento depois de a aplicação sair
WinAppRunClean	false	Remova os dados da aplicação do pacote existente (LocalState, definições) antes de voltar a implementar
WinAppRunSymbols	false	Descarregue símbolos do Microsoft Symbol Server para uma análise nativa de falhas mais rica. Só tem efeito com WinAppRunDebugOutput.
WinAppRunExecutable	(vazio)	Caminho executável relativo à pasta build-output. Use quando o manifesto contém $targetnametoken$ e a pasta de saída tem mais do que um .exe.
WinAppRunArgs	(vazio)	Argumentos brutos anexados à winapp run linha de comandos, para opções sem propriedade dedicada (por exemplo --verbose, ). Anexado após todas as propriedades acima.

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

Property	Não pode ser combinado com
WinAppRunNoLaunch	WinAppRunDetach, WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach	WinAppRunNoLaunch, WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias está deliberadamente fora dessa lista, em qualquer das direções. false pede ativação de AUMID, que o no-launch e o desacoplamento já utilizam; true simplesmente não é aplicado quando qualquer um deles está definido, porque um alias de execução necessita de um processo rastreado e em execução. Assim, um projeto que faz check-in <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> continua a correr limpamente sob dotnet run -p:WinAppRunDetach=true, lançando via AUMID em vez de falhar.

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

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

---

desregisto

Desregistar um pacote de desenvolvimento sideloaded. Apenas remove pacotes que foram registados em modo de desenvolvimento (por exemplo, via winapp run ou create-debug-identity). Os pacotes instalados na loja ou instalados no MSIX nunca são removidos.

winapp unregister [input] [options]

Argumentos:

• input- Caminho para uma aplicação baseada em ficheiros .NET (uma única .cs) cujo pacote deve estar não registado. A sua identidade é resolvida da mesma forma winapp run que a resolve — a partir de um manifesto autorado se a aplicação tiver um, caso contrário a partir dos seus #:property valores — pelo que não é necessário um caminho de manifesto. Omitir usar --manifest ou detetar automaticamente um manifesto no diretório atual. Não pode ser combinado com --manifest, que nomeia o pacote de uma forma diferente e pode resolver para outro.

Opções:

• --manifest <path> - Caminho para Package.appxmanifest (padrão: deteção automática a partir do diretório atual)
• --force - Para desregisto local, basta ignorar a verificação do diretório de localização de instalação e desregistar-se mesmo que o pacote tenha sido registado de uma árvore de projeto diferente. É rejeitado com --on; as verificações de propriedade alvo não podem ser contornadas.
• --on <target> - Remover o registo de desenvolvimento correspondente pertencente ao winapp de sandbox, não desta máquina. Requer um manifesto e não suporta --force. Veja limpeza da aplicação Sandbox.
• --prune - Remover todos os registos em modo de desenvolvimento cujos ficheiros desapareceram. Não pode ser combinado com uma entrada, --manifest, --property, --configuration--arch, , --runtime, ou --output-appx-directory.
• -p, --property <Name=Value> - Propriedade MSBuild usada ao resolver a identidade de uma .cs aplicação baseada em ficheiros. Repetível. Passe as mesmas propriedades que afetam a identidade que a execução usou (por exemplo, -p WinAppPackageName=...), uma vez que uma propriedade de linha de comandos sobrepõe as próprias #:property diretivas do ficheiro. Aplica-se apenas a uma .cs entrada.
• -c, --configuration <name> - Configuração de construção usada ao resolver a identidade de uma .cs aplicação baseada em ficheiros. Padrão: Debug. Passe a mesma configuração que a execução usada: a Directory.Build.props ao lado do .cs conjunto WinAppPackageName pode ou WinAppManifestPath condicionalmente em $(Configuration). Aplica-se apenas a uma .cs entrada.
• --arch <x64|arm64|x86> - Arquitetura de destino usada na resolução da identidade de uma .cs aplicação baseada em ficheiros. Padrão: a arquitetura atual do processo. Passe a mesma arquitetura que a execução usou, já que a identidade também pode ser indexada $(RuntimeIdentifier)em chaves . Aplica-se apenas a uma .cs entrada.
• -r, --runtime <rid>- Identificador de runtime .NET de destino (por exemplowin-x64) usado ao resolver a identidade de uma .cs aplicação baseada em ficheiros. Apenas a sua arquitetura é utilizada, e sobrepõe-se --archa . Aplica-se apenas a uma .cs entrada.
• --output-appx-directory <path> - O diretório de layout do AppX de onde o pacote foi registado. Só era necessário quando a execução usava --output-appx-directory, pois nada no pacote registava a opção de execução produzia o seu layout.
• --json - Saída de formato como JSON

O que faz:

• Determina o nome do pacote — a partir da .cs identidade resolvida do ficheiro, ou lendo o 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 o pacote pertence à aplicação que mencionaste (a menos que --force) — a sua localização de instalação deve estar sob um diretório que identificaste: a .cs saída da build do ficheiro, o diretório do manifesto, o diretório atual ou um arquivo explícito --output-appx-directory. Um pacote cujo local de instalação não pode ser resolvido (os seus ficheiros foram eliminados) é ignorado, porque a identidade por si só não é prova de propriedade: duas aplicações que ambas definem #:property WinAppPackageName=counter registam a mesma identidade em pastas diferentes. Use --prune para limpar registos cujos ficheiros desapareceram.
• Desregistar pacotes correspondentes

A limpar registos mortos (--prune):

Um registo sobrevive aos seus ficheiros. Apague um output de compilação, árvore de projetos, ou (para uma aplicação baseada em ficheiros) deixe o Windows limpar %LOCALAPPDATA%\Temp, e o pacote mantém-se registado: o Windows mantém a identidade e a entrada do menu Iniciar, mas a ativação silenciosa não faz nada. Estas acumulam-se invisivelmente.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Apenas os registos em modo de desenvolvimento são considerados, e cada um é removido pelo nome completo do pacote, pelo que um pacote com o mesmo nome ainda instalado a partir de uma localização ativa permanece intacto. O prompt existe porque uma localização de instalação em falta é normalmente uma pasta eliminada, mas também descreve um pacote registado a partir de uma partilha de rede desconectada ou disco removível — reveja a lista antes de confirmar.

Exemplos:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# Remove every dev registration whose files are gone
winapp unregister --prune

# 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 o publisher do certificado do manifesto Identity/@Publisher. Só é necessário o editor, por isso um manifesto parcialmente completo ainda funciona. Se o manifesto não tiver um publisher utilizável, o comando falha em vez de substituir por um padrão, pelo que o certificado nunca pode coincidir silenciosamente com o manifesto.
• --publisher <name>- Publisher para o certificado. Ao gerar um certificado, esta opção tem precedência sobre --manifest; um valor explicitamente vazio falha em vez de usar o publicador do manifesto. Aceita um nome distinto completo X.500 (por exemplo, CN=Contoso, O=Contoso Ltd, C=US) ou um nome simples que é automaticamente enrolado como CN=<name>. Os componentes devem ser de valor único e separados por vírgulas; RDNs multivalorados (CN=Foo+OU=Bar) e barras inversas não são suportados porque o editor de manifestos MSIX não os pode representar. Um nome distinto mal formado (por exemplo, CN= ou CN=A,,O=B) é rejeitado com uma saída não nula e um erro que nomeia o problema, em vez de produzir um certificado que nunca pode corresponder ao editor do manifesto.
• --output <path> - Caminho de ficheiro de certificado de saída (suporta caminhos absolutos e relativos)
• --password <password> - Password de certificado (por defeito: password, que é publicamente conhecida — ver saída JSON e Segurança)
• --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": "..."}).

Saída JSON:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher é o nome de exibição e subjectName o nome distinto completo a que o certificado foi emitido. defaultPasswordIsPublic está sempre presente. Quando é true, o .pfx está protegido por uma palavra-passe que qualquer pessoa pode adivinhar, por isso o certificado só deve assinar compilações que permanecem nas suas próprias máquinas — verifique antes que um script passe o certificado a qualquer outra coisa. warnings contém a mesma divulgação que o texto e é omitida quando não há nada a reportar. publicCertificatePath aparece apenas com --export-cer.

Informação da certificação

Mostrar detalhes do certificado a partir de um ficheiro PFX ou CER. Ú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 ou CER)

Opções:

• --password <password> - Palavra-passe para o ficheiro PFX, ignorada para uma CER pública (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> <cert-path> [options]

Argumentos:

• file-path - Caminho para o pacote MSIX ou executável para assinar
• cert-path - Caminho para o certificado de assinatura (.pfx)

Opções:

• --password <password> - Palavra-passe do certificado (por defeito: "password")
• --timestamp <url> - URL do servidor de carimbo temporal do RFC 3161

Exemplos:

# Sign MSIX package
winapp sign MyApp.msix ./mycert.pfx

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

---

az-sign

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

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

Argumentos:

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

Opções:

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

Authentication: (Autenticação)

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

Pré-requisitos:

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

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

Exemplos:

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

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

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

---

create-external-catalog

Gerar um CodeIntegrityExternal.cat ficheiro de catálogo contendo hashes de ficheiros executáveis a partir de diretórios especificados. Este catálogo é usado com a flag TrustedLaunch nos manifestos de pacotes esparsos do MSIX (AllowExternalContent) para permitir a execução de ficheiros externos não incluídos no próprio pacote.

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

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

Argumentos:

• input-folder - Um ou mais diretórios contendo ficheiros executáveis a processar. Separe vários diretórios com ponto e vírgula (por exemplo, "dir1;dir2")

Opções:

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

O que faz:

• Analisa diretórios especificados para ficheiros executáveis (binários PE com secções de código)
• Gera um Ficheiro de Definição de Catálogo (CDF) com hashes de todos os executáveis encontrados
• Utiliza APIs Windows CryptoCAT para produzir o ficheiro de catálogo .cat
• Ficheiros não executáveis (por exemplo, .txt, .dll sem secções de código) são automaticamente ignorados

Exemplos:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Quando usar:

Use este comando ao construir um pacote MSIX esparso que utilize o TrustedLaunch para verificar executáveis externos. O fluxo de trabalho típico é:

1. winapp manifest generate --template sparse — Criar um manifesto esparso com AllowExternalContent
2. winapp create-external-catalog ./bin — Gerar o catálogo de integridade do código para os executáveis da sua aplicação
3. winapp pack — Empacotar o manifesto, os ativos e o catálogo num MSIX

---

ferramenta

Acess diretamente às ferramentas do SDK do Windows. Utiliza ferramentas disponíveis em Microsoft.Windows. SDK. BuildTools

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

Ferramentas disponíveis:

• makeappx - Criar e manipular pacotes de aplicações
• signtool - Assinar ficheiros e verificar assinaturas
• mt - Ferramenta de manifestação para conjuntos lado a lado
• E outras ferramentas Windows SDK do Microsoft.Windows. SDK. BuildTools

Exemplos:

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

Verificação de assinatura

As ferramentas de compilação são descarregadas do NuGet e depois executadas, por isso o winapp verifica cada uma delas para uma assinatura válida do Microsoft Authenticode imediatamente antes de a executar. O certificado deve indicar a Microsoft Corporation como a organização signatária. Isto aplica-se a todos os comandos que fornecem para uma ferramenta SDK, incluindo tool, package, e sign. Uma ferramenta que falha a verificação não é executada:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Uma falha aqui significa que o ficheiro no disco não é o que a Microsoft publicou — na maioria das vezes um download corrompido ou parcial. Apaga o pacote da cache NuGet e executa o comando novamente para que o winapp o volte a descarregar.

O WinApp mantém a ferramenta aberta enquanto estiver a correr, por isso o ficheiro que verificou é o ficheiro que o Windows carrega. Se não conseguir segurar a ferramenta no lugar, também não é executada:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Fecha o que quer que esteja a usar o ficheiro — uma análise antivírus ou um editor aberto é a causa habitual — e executa o comando novamente. Se a ferramenta desaparecer em vez de estar em uso, apague o pacote da cache NuGet para que o Winapp o volte a descarregar.

---

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

---

destino

Executa comandos, copia ficheiros, inspeciona o estado ou captura todo o ambiente de trabalho convidado.

Cada verbo tem sandbox como primeiro argumento. Exceto , snapshotestes comandos podem preparar ou iniciar o Sandbox. Consulte execução no Windows Sandbox para pré-requisitos, permissões, ciclo de vida e recuperação.

Executivo Target

Executa um comando como utilizador convidado.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

As discussões depois -- mantêm os seus limites. Os fluxos padrão e o código de saída do processo convidado são encaminhados; este não é um terminal completo. --json Formata falhas do WinApp no STDERR sem alterar o STDOUT do comando filho. Use a estrutura error.code para distinguir uma falha alvo do estado de saída da própria aplicação.

Um explicit WINAPP_UI_WORKFLOW_ID também agrupa chamadas de UI de convidados feitas pelo comando; ver coordenação de UI Sandbox.

Empurrão do alvo e puxão do alvo

Copie um ficheiro ou diretório na direção nomeada pelo verbo.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Os caminhos dos alvos são relativos à área de trabalho gerida do alvo; os caminhos absolutos, enraizados e UNC são rejeitados. Um destino de ficheiro inclui o seu nome de ficheiro. Veja Executar comandos e copiar ficheiros para layout de diretórios, gestão de links e execução de um script copiado.

Fotografia do alvo

Reporte prontidão, implementações e janelas de convidados sem iniciar um Sandbox.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

Não reconecta um cliente nem repara um agente. Nenhum Sandbox a correr é um resultado bem-sucedido, não um erro. Consulte Inspecionar o Sandbox para interpretar IDs de prontidão e processos.

Captura de ecrã do alvo

Capture o ambiente de trabalho convidado no seu tamanho nativo de píxeis como um PNG anfitrião, sem seletor de aplicações ou bordas de janelas anfitriãs. --json Reporta a origem da coordenada de convidados.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Usa ui screenshot --on sandbox -a <app> antes uma janela de aplicação. Consulte Capturas de ecrã e gravações para requisitos do cliente, limitações de foco e gestão de resultados.

Registo de alvos

Grava o ambiente de trabalho convidado para H.264 MP4. Os ficheiros de vídeo e frame host chegam após a gravação terminar; JSON e o manifesto de frames descrevem qualquer escalonamento ou preenchimento (midding).

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Utiliza as opções de duração, frame, sobrescrição e resultado de ui record, mas captura o ambiente de trabalho em vez de uma única aplicação. Prefiro um positivo --duration-sec para uso de CLI sem supervisão; o auxiliar npm requer durationSec. Consulte captura Sandbox para falhas de evidência parcial e prontidão para captura.

---

Find-ui

Agente em primeiro lugar. find-ui é criado principalmente para agentes de codificação de IA — permite que um agente extraia marcação real, compilando o WinUI das galerias de envio em vez de o inventar, e --json torna cada resultado (e cada falha) legível por máquina. Funciona tão bem digitado à mão.

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

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

A Galeria, o Toolkit e os corpora do reator são incluídos dentro da CLI, por isso find-ui funciona sem acesso à rede — incluindo numa primeira execução num sandbox de agentes ou atrás de um proxy corporativo que bloqueia raw.githubusercontent.com. Quando o GitHub está acessível, a CLI atualiza-se a partir dele e armazena em cache o resultado por utilizador em ; <global .winapp>/cache/find-uio corpus incorporado é apenas um piso, nunca um teto. Os dados em cache são atualizados no máximo a cada 24 horas, ou a pedido com --refresh.

O corpus incorporado é recuperado do GitHub sempre que uma versão estável é construída, e uma atualização que falha impede a versão da versão em vez de enviar silenciosamente dados antigos — o Baker obtém pelo mesmo caminho --refresh de código usado, por isso uma falha aí significa que a atualização ao vivo também está quebrada e vale a pena investigar antes do envio. Uma liberação pode ainda ser feita contra o corpus previamente comprometido, mas apenas como uma sobreposição explícita. Quando os resultados são servidos a partir da cópia incorporada dos corpora Gallery/Toolkit/Reactor, find-ui diz isso em stderr e --json output carry "corpus": "embedded" (outros valores: "network" para um fetch novo, "cache" para a cache local). Um pedido apenas core — --source core, ou um --id conjunto que seja composto por todos os padrões core — também reporta "embedded" , porque os padrões core curados são compilados na CLI e nunca são obtidos; não imprime qualquer aviso de estagnação, pois --refresh não os pode alterar. O corpus campo é reportado sempre que os resultados são apresentados; está ausente apenas quando nenhum corpus pode ser carregado.

Opções:

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

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

Exemplos:

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

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

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

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

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

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

Relacionado:find-ui pesquisa exemplos de WinUI; usa find-api para pesquisar a superfície da API (tipos, membros, enums) que um projeto referencia, e winapp ui search para pesquisar a árvore de interface de uma aplicação em execução .

---

Find-API

Agente em primeiro lugar. find-api é concebido principalmente para agentes de codificação de IA — fundamenta o código gerado na superfície da API que um projeto realmente referencia, em vez da recordação do modelo sobre ele, e --json , além de códigos de saída não nulos em símbolos em falta permitem que um código de porta de agente fique na resposta. Funciona tão bem digitado à mão.

Pesquise e inspecione a superfície da API do Windows/WinRT (tipos, membros, enums, namespaces) disponível para um projeto, resolvido a partir dos seus metadados referenciados.winmd/.dll. A forma nua procura; os subverbos penetram num tipo específico, espaço de nomes ou no próprio índice.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

O índice é construído a partir dos pacotes NuGet/SDK restaurados do projeto (via project.assets.json) na primeira utilização e atualiza-se automaticamente quando o projeto é restaurado. Está sob a cache global .winapp (cache/find-api/) e é partilhada entre projetos. Restaure primeiro o projeto (winapp restore ou dotnet restore).

Cada correspondência está listada no seu namespace com o pacote que a envia e um resumo de uma linha do que faz, pelo que o resultado é utilizável sem necessidade de uma segunda members chamada:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Adicione --verbose também a impressão do ficheiro de cache no disco que apoia cada namespace, o que é útil ao diagnosticar um índice obsoleto ou inesperado.

Correr winapp find-api sem qualquer consulta imprime um breve resumo de utilização e sai 0 — é um pedido de ajuda, não uma pesquisa que não encontrou nada.

Oscilos. Cada resposta vem de exatamente um espírito, reportado como scope em --json e como nota na saída do texto:

• project - o projeto no diretório atual (ou --project / --project-dir). Abrange o Windows SDK, o SDK de Aplicações Windows e os próprios pacotes NuGet do projeto. Os metadados do SDK de Aplicações Windows são a versão referenciada pelo projeto: se a máquina tiver um Aplicação do Windows Runtime mais recente, o Runtime avisa find-api e omite-o em vez de confirmar os tipos contra os quais o projeto não pode compilar.
• sdk- os metadados do Windows SDK + SDK de Aplicações Windows em toda a máquina, usados automaticamente quando o diretório atual não contém projeto nem solução. Isto torna-se find-api utilizável para explorar APIs antes de qualquer projeto existir, e não requer acesso à rede. Deliberadamente , não inclui pacotes NuGet de terceiros, pelo que um tipo do Community Toolkit não será encontrado neste âmbito.

Uma consulta de um diretório sem projeto e sem solução é sempre respondida pelo sdk âmbito – nunca pelo projeto que está indexado na cache partilhada – por isso os resultados nunca dependem de um estado global não relacionado. Passe --project sdk para selecionar explicitamente o âmbito do SDK dentro de um projeto e winapp find-api refresh --project sdk reconstruí-lo após instalar um novo SDK do Windows.

Diretórios de soluções. A partir de um diretório que contém um .sln/.slnx sem ficheiro de projeto ao lado, os projetos que a solução constrói respondem em vez do sdk âmbito – são indexados a pedido, por isso os seus pacotes NuGet estão incluídos. Quando a solução constrói mais do que um projeto indexado, a consulta lista-os e pede-os --project <name> em vez de escolher um.

Comandos:

• (nu)find-api "<query>" ["<query>"...] - Tipo de pesquisa e nomes dos membros, recorrendo aos seus resumos documentados, agrupados por namespace
• members <type> [<type>...] [--filter <text>] - Listar as propriedades, eventos e métodos de um tipo (membros declarados com assinaturas, membros herdados resumidos declarando o tipo)
• check-property <type> <property> [<property>...] - Existem propriedades de validação num tipo (saídas diferentes de zero se alguma estiver em falta). Uma propriedade de apenas leitura é reportada com ⚠️ e "somente leitura, não pode ser atribuída" em vez de uma propriedade simples ✅, por isso uma propriedade como ActualWidth não é confundida com algo que pode ser definido. Os nomes das propriedades são correspondidos de forma sensível a maiúsculas e minúsculas, porque C# e XAML são: check-property Button background saídas diferentes de zero e ofertas Background como quase correspondência, em vez de reportarem um nome que não consegue realmente escrever.
• enums <type> [<type>...] [--filter <text>] - Listar os valores de um enum (saídas não nulas quando o tipo não é um enum)
• packages - Listar os pacotes de metadados indexados, com cada tipo de pacote/número de membros
• stats - Mostrar estatísticas agregadas de índice (pacotes, namespaces, tipos, membros, .winmd ficheiros)
• refresh [--scan] - Reconstruir o índice de um projeto (--scan indexa todos os projetos sob o diretório). Com , um nome que não corresponde a --project <name>nenhum projeto indexado falha em vez de indexar o diretório atual.

Agrupamento,searchmembers , enums, e check-property aceitar múltiplos sujeitos numa única invocação. Para um agente de IA, esta é a maior alavanca de custo: o custo marginal de uma consulta é dominado pela ida e volta (cada chamada reenvia toda a conversa), e não pelo tamanho da carga útil, por isso uma chamada que responde a dez perguntas é muito mais barata do que dez chamadas.

• Um único sujeito devolve exatamente a forma da carga útil que sempre teve, tanto no texto como --jsonem .
• Dois ou mais sujeitos retornam um envelope — { "count": N, "results": [ ... ] } em --json, sendo cada elemento a carga útil normal de um único sujeito; check-property adiciona missingCount. A saída de texto apresenta cada assunto em sequência sob um cabeçalho de escopo.
• check-property lote propriedades num tipo: o primeiro argumento é o tipo, cada argumento depois dele é uma propriedade. No modo batch, uma propriedade existente imprime uma única ✅ linha; o detalhe completo de quase acidente é impresso apenas para as que não o fazem.
• Um lote 0 sai apenas se todos os sujeitos foram resolvidos e encontrados — por isso, um lote ainda é seguro para gerar código.

Classificação na pesquisa. Uma consulta que corresponde exatamente a um nome de tipo está classificada à frente de correspondências parciais, e quando um nome curto é partilhado por vários namespaces, apenas as colisões exatas do nome são listadas como ambíguas — uma consulta como NavigationView reporta o punhado de namespaces que definem esse tipo exato, em vez de todos os namespaces contendo um símbolo com nome semelhante. A lista de ambiguidade obedece --max, e os resultados normais continuam impressos por baixo.

Nomes de tipo.members, check-property, e enums aceitam um nome curto (NavigationView) ou um nome totalmente qualificado (Microsoft.UI.Xaml.Controls.NavigationView). Quando um nome curto é partilhado por um tipo moderno Microsoft.* e o seu gémeo UWP legadoWindows.*, o Microsoft.* tipo responde — que é a projeção que uma aplicação do SDK de Aplicações Windows usa — e o nome totalmente qualificado resolvido é sempre mostrado. Qualquer outra colisão sai diferente de zero e lista os candidatos em vez de adivinhar.

Assinaturas de métodos. Uma assinatura é impressa da mesma forma que escreveria a chamada: um método que chama no tipo em vez de numa instância é mostrado com static, e um parâmetro de referência é mostrado com a palavra-chave de que realmente precisa — out, in, ou ref. Assim TryGetValue lê-se Boolean TryGetValue(String key, out String value), que compila como está escrito.

Opções:

• --max <n> - Número máximo de resultados de pesquisa agrupados por espaço de nomes (por defeito 5; apenas pesquisa). Também limita a lista de ambiguidades, por isso uma consulta curta que colide entre muitos namespaces mantém-se legível.
• --filter <text> - Restringir uma listagem em members e enums: uma correspondência de substrings insensível a maiúsculas minúsculas no nome membro/valor. É melhor usado em tipos com centenas de membros. A maioria dos enums é pequena o suficiente para despejar inteira (até Symbol, a maior no WinUI com 197 valores), por isso filtrá-los normalmente custa mais do que poupa quando se considera um segundo palpite. Nunca voltes a executar o mesmo comando com texto de filtro diferente — faz um dump e lê-o.
• --all - Em members, liste a superfície completa: assinaturas completas para membros herdados, mais estáticas do identificador de propriedade de dependência e descrições por membro, todas as quais uma listagem não filtrada omite (ver Tamanho da listagem abaixo). --verbose implica isso; use --all quando também se quer --json, que não pode ser combinado com --verbose.
• --scan - Descobrir e indexar recursivamente todos os projetos sob o diretório (refresh apenas)
• --project <name>- Project para consultar (corresponde ao .csproj/.vcxproj nome), ou sdk para consultar o âmbito do Windows SDK em toda a máquina
• --project-dir <path>- Project diretório para consultar (por defeito para o diretório atual). Um caminho que não existe é um erro — nunca é silenciosamente respondido a partir do sdk âmbito.
• --json - Emitir uma carga útil legível por máquina no stdout (suportado por todos os verbos). As cargas úteis de consulta identificam o índice que respondeu através scope de (project ou sdk), projectName, e projectDir (ausente para o âmbito do SDK) — os nomes dos projetos não são únicos entre diretórios, assim como projectDir a identidade fiável. Em --jsoncada falha — incluindo erros de argumento/analisador como um não inteiro --max — é emitido como um objeto plano {"error": "..."} em stdout com um código de saída diferente de zero, pelo que a saída permanece legível pela máquina.

Exemplos:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Quando --filter aplicada, a saída continua a reportar o total não filtrado (totalValues, outotalEvents//totalPropertiestotalMethods em --json), pelo que uma visão restrita nunca é confundida com uma API pequena. Um filtro que não corresponde a nada sai 0 e diz explicitamente — que é "nada corresponde ao teu filtro", não "não há tal tipo".

Tamanho do anúncio. Uma listagem members sem filtros é a forma cara — members Button cobre 288 membros, dos quais 280 são herdados de 6 tipos de base. Uma chamada não filtrada é uma consulta de orientação ("o que é este tipo, mais ou menos o que pode fazer?"), por isso responde a isso e omite as partes de onde nada é escrito:

• Assinaturas de membros herdadas — os membros herdados são agrupados por tipo declarado e listados apenas pelo nome, pelo que a forma da superfície herdada ainda é visível sem 280 assinaturas completas.
• Estática do identificador de propriedade de dependência (BackgroundProperty) — 28% das propriedades típicas de um controlo WinUI. Existem para serem passadas a GetValue/SetValue, não para serem atribuídas.
• Descrições por membro — a prosa XML-doc, cerca de 16% da carga útil.
• Campos implícitos pelo seu entorno em --json: kind (implícito pelo array que contém/events/propertiesmethods), returnType (o token principal de signature), e inherited quando falso (implícito por ).declaringType

O que foi omitido é sempre reportado (hiddenDependencyProperties, descriptionsOmitted, e a hint em --json; uma linha "Omitido:" no texto), e os totais continuam a descrever o tipo completo. Ambos --filter e --all vê a superfície completa com assinaturas e descrições completas, por isso members Button --filter BackgroundProperty ainda encontra o identificador e members Button --filter Click ainda devolve Clicka assinatura herdada de . Medido em samples/winui-app, isto demora members Button --json de 91.954 a 10.567 caracteres (−88,5%) e sai --filter--all idêntico a byte.

Como uma consulta é emparelhada. winapp find-api "language model" classificações LanguageModel acima correspondem cujas palavras estão espalhadas por namespaces e membros, incluindo fora de um projeto quando o tipo é indexado. A pesquisa é léxica, não semântica: corresponde a palavras identificadoras inteiras em vez de qualquer sequência de letras, por isso llm encontra IImageLLMAdapterSession mas não ScrollMode. Quando uma consulta não corresponde a nenhum nome, é testada contra os resumos documentados de tipos e membros, o que permite "random-access stream" encontrar IRandomAccessStream. As descrições ficam abaixo de todas as correspondências de nome, e apenas os resumos que os pacotes realmente enviam são pesquisáveis — um pacote sem documentação XML não contribui com texto de descrição.

Projetos sem ficheiro de projeto MSBuild. Uma aplicação Electron (ou qualquer outra aplicação que não seja .NET gerida por winapp.yaml) não .csproj tem e, portanto, não project.assets.jsontem . find-api indexa-o a partir do .winapp/winmds.lock.json que winapp restore escreve, que regista a mesma coisa: cada pacote resolvido, a sua versão e os .winmd ficheiros que contribue. Tal projeto recebe o nome do seu diretório, e o seu índice fica obsoleto quando o ficheiro de bloqueio é reescrito. Um diretório que contém tanto a .csproj como a winapp.yaml é indexado a partir do .csproj, que é a descrição mais precisa do que o projeto compila.

Respostas negativas são qualificadas quando o índice está incompleto. Se os metadados de um pacote não puderam ser lidos, "não existe esse tipo" e "esse pacote nunca foi indexado" parecem idênticos — e agir com base no primeiro, quando na verdade é o segundo, gera código contra uma API que lhe disseram que não existe. Assim, toda resposta negativa, incluindo a search que devolve zero resultados, traz uma nota de que o índice é parcial e aponta para winapp find-api refresh. As respostas positivas não são afetadas.

Nomes genéricos de tipo. Os metadados armazenam tipos genéricos com um sufixo de aridade (IAsyncOperation`1), que não é como ninguém os escreve. members, enums, e check-property aceitam todas as formas: IAsyncOperation, IAsyncOperation<StorageFile>, e IAsyncOperation`1 todas resolvem para o mesmo tipo. Um nome simples corresponde a qualquer aridade; uma aridade declarada (em qualquer uma das notações) deve corresponder, pelo que Holder<A, B> não se resolve para um único parâmetro Holder<T>.

--json As cargas úteis omitem diagnósticos. Os caminhos dos ficheiros de cache aparecem apenas em --verbose (correspondente à saída de texto, onde já eram apenas verbosos), e os arrays de sugestões vazios são omitidos em vez de serializados como [].

Códigos de saída:search Sem correspondências, check-property numa propriedade em falta e enums num tipo não-enum, todas as saídas não nulas — geração de códigos de portas e verificações de CI sobre eles. Uma invocação em lote sai diferente de zero se algum sujeito falhar. Uma propriedade de só leitura não é uma falha — existe, por isso check-property sai 0 e sinaliza-a na saída (writable: false em --json). Uma init propriedade reporta writable: false pelo mesmo motivo: pode ser definida num inicializador de objetos, e a sua assinatura diz { get; init; }, mas atribui-la depois não compila.

Relacionado:find-api respostas "esta API existe e quais são os seus membros?"; usar find-ui para encontrar um exemplo funcional do WinUI para um controlo.

---

Ligações de geração de nós

(Disponível apenas no pacote NPM) Gerar ligações JS para APIs do SDK de Aplicações Windows. As ligações são declaradas por um "winapp": { "jsBindings": {...} } namespace em package.json e escritas em .winapp/bindings/.

npx winapp node generate-bindings [options]

Opções:

• --verbose, -v - Ativar a saída de codegen verbosa por ficheiro
• --quiet, -q - Suprimir o progresso e a produção informativa

O que faz:

• Lê o bloco de e o winapp.jsBindings escrito pelo último package.json, depois emite ligações digitadas winmds.lock.jsonwinapp restore.js em + .d.ts.winapp/bindings/
• Não se modifica package.json — é um regenerador passivo. Adicionar o bloco winapp.jsBindings e a @microsoft/dynwinrt dependência de tempo de execução ocorre durante winapp init o período em que as ligações JS estão ativadas; este comando falha rapidamente se o bloco estiver ausente
• Avisa (mas não escreve) se @microsoft/dynwinrt estiver em falta nas suas dependências — run npm install after init o adicionou

Observação

As ligações são apenas npm — requerem invocação via npx winapp (o @microsoft/winappcli pacote npm); a CLI winget autónoma não as apresenta. Execute winapp init interativamente e opte, ou use winapp init . --use-defaults --add-js-bindings, antes de usar este comando para regenerar bindings. Se editareswinapp.yaml, corre npx winapp restore para atualizar as dependências do Windows antes de regenerar.

Exemplos:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Consulte o guia de ligações JS para o fluxo de trabalho de ponta a ponta e as winapp.jsBindings opções de configuração.

---

Node Create-Addon

(disponível apenas no pacote NPM) Gerar templates de addons nativos em C++ ou C# com Windows SDK e integração SDK de Aplicações Windows.

npx winapp node create-addon [options]

Opções:

• --name <name> - Nome do addon (por defeito: "nativeWindowsAddon")
• --template - Selecionar o tipo de addon. As opções são cs ou cpp (por defeito: cpp)
• --verbose - Ativar a saída verbosa

O que faz:

• Cria diretório de addons com ficheiros modelo
• Gera binding.gyp e addon.cc com exemplos de SDK Windows
• As instalações exigiam dependências npm (nan, node-addon-api, node-gyp)
• Adiciona um script de build à package.json

Exemplos:

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

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

---

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

(Disponível apenas no pacote NPM) Adicione identidade de aplicação ao processo de desenvolvimento do Electron usando embalagens esparsas. Requer um Package.appxmanifest (cria um com winapp init ou winapp manifest generate se não tiveres).

Importante

Existe um problema conhecido com aplicações Electron com embalagens esparsas que faz com que a aplicação crashe ao iniciar ou não renderize o conteúdo web. O problema foi resolvido no Windows, mas ainda não se propagou para dispositivos Windows externos. Se estiver a ver este problema depois de ligar add-electron-debug-identity, pode desativar o sandboxing na sua aplicação Electron para efeitos de depuração com o --no-sandbox flag. 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 o Package.appxmanifest personalizado (padrão: Package.appxmanifest no diretório atual)
--no-install	Não instale nem modifique dependências; configure apenas a identidade de depuração do Electron
--keep-identity	Mantenha a identidade do manifesto como está, sem adicionar .debug ao nome do pacote e ao identificador da aplicação.
--verbose	Ativar saída detalhada

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:

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

O que faz:

• Restaura electron.exe a partir do backup criado por add-electron-debug-identity
• Remove os ficheiros de backup após a restauração
• Devolve o Electrão ao seu estado original sem identidade de pacote

Exemplos:

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

---

Opções Globais

Todos os comandos suportam estas opções globais:

• --verbose, -v - Ativar saída verbosa para registos detalhados
• --quiet, -q - Suprimir mensagens de progresso
• --help, -h - Mostrar ajuda com comandos

---

Diretório Global de Cache

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

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

Para usar uma localização diferente, define a WINAPP_CLI_CACHE_DIRECTORY variável de ambiente.

Em cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

No PowerShell e pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

O Winapp criará este diretório automaticamente quando executares comandos como init ou restore.

Verificações de Atualização

A linha de comando winapp verifica periodicamente novas versões e apresenta um aviso de uma linha quando uma atualização está disponível. Esta verificação corre em segundo plano e não adiciona latência aos comandos.

As verificações de atualização são automaticamente desativadas em ambientes CI (GitHub Actions, Azure Pipelines, etc.).

Para desativar manualmente as verificações de atualização, defina a WINAPP_CLI_UPDATE_CHECK variável ambiente para 0.

Em cmd:

set WINAPP_CLI_UPDATE_CHECK=0

No PowerShell e pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Para tornar isto permanente:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

Identidade do fluxo de trabalho UI

winapp ui Os comandos que controlam o ambiente de trabalho físico têm sempre turnos cooperativos, por isso dois fluxos de trabalho a correr ao mesmo tempo não podem roubar a atenção um do outro nem ignorar os menus um do outro. Essa arbitragem não precisa de ser configurada e não pode ser desligada.

O que é opcional é a continuidade. Por defeito, cada comando é um one-shot autónomo que liberta o ambiente de trabalho assim que termina. Para manter o ambiente de trabalho em vários comandos, dê-lhes a todos o mesmo id de workflow:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

Use o mesmo valor para processos cooperantes (por exemplo, uma gravação e os cliques que ela deve capturar) e valores diferentes para fluxos de trabalho independentes. Cada comando sem id é o seu próprio fluxo de trabalho de one-shot, mesmo quando vários são lançados a partir de um mesmo shell, por isso os hosts que iniciam um novo shell por comando têm de injetar o mesmo valor explícito em cada um. O valor é opaco, nunca é tratado como credencial e só é mantido como um hash SHA-256. Veja Automatização da Interface de Utilizador → Coordenação de fluxos de trabalho de UI concorrentes.

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 (múltiplas janelas formam uma PNG composta rotulada; ver escopo de captura)
• record- Gravar uma região de janela/elemento num vídeo MP4 H.264 (Windows Graphics Capture + Media Foundation)
• invoke - Ativar elemento (clicar, alternar, expandir)
• click - Clique no elemento via simulação de rato (para controlos que não suportam invocação)
• hover - Mover o rato para o elemento para ativar dicas de ferramenta, flyouts e estados de hover (dwell padrão: 800ms)
• drag - Arrastar o rato de um ponto para outro, por seletor de elementos ou coordenadas do ecrã x,y (reordenar, redimensionar, deslizar, arrastar e largar)
• touch- Injetar gestos táteis sintéticos (toque, duplo toque, pressão longa, deslizar, beliscar, esticar) no centro de um elemento ou coordenadas do ecrã x,y
• pen - Injetar entrada sintética de caneta/caneta — toques e traços de tinta com modo de pressão, inclinação e borracha configuráveis
• send-keys - Enviar entrada sintética do teclado (teclas nomeadas, combos, raw vk=0xNN, ou texto literal) para uma janela
• set-value - Definir valor no elemento editável (texto, número); recorre ao LegacyIAccessible put_accValue para controlos de edição rica apenas com TextPattern
• focus - Mover o foco do teclado
• scroll-into-view - Elemento de pergaminho visível
• wait-for - Esperar pelo estado do elemento
• list-windows - Listar todas as janelas de uma aplicação
• get-focused - Reportar o elemento atualmente focado
• yield - Libertar a atualização da interface do fluxo de trabalho atual; requer WINAPP_UI_WORKFLOW_ID

Opções:

• -a, --app <app> - Aplicação alvo (nome, título ou PID)
• -w, --window <hwnd> - Janela-alvo por HWND (estável)
• --on <target> - Executar qualquer ui verbo em sandbox; nomes, PIDs e maçanetas de janela referem-se ao convidado. As saídas são entregues ao anfitrião. Consulte automação da interface Sandbox para configuração, coordenação de fluxos de trabalho e requisitos do cliente.

Registo UI

Grave uma janela ou região de elemento num MP4 H.264.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

Opções de gravação:

• --duration-sec <n> - Duração da gravação em segundos. 0 regista até Ctrl+C (padrão 0).
• --fps <n> - Frames por segundo para capturar (por defeito 15).
• --max-edge <px> - Redução de escala para que a aresta mais longa tenha no máximo este número de píxeis (0 = sem redução de escala).
• --capture-screen - Capturar a partir do ecrã para incluir sobreposições/pop-ups (pode capturar janelas a ocluir).
• -o, --output <path> - Caminho de saída .mp4 (por defeito para recording-<timestamp>-<guid>.mp4).
• --overwrite - Substituir as saídas de gravação existentes após o término da nova tomada; as saídas existentes são rejeitadas por defeito. Os feixes de frames anteriores são mantidos. Ver Recuperação de saída de gravação.
• --frames - Escrever JPEGs com carimbo temporal, frames.ndjson, e manifest.json para <output-name>.frames. Suporta 1-30 fps e --max-edge 64-4096 (padrão 1280), com limite de 1 GiB de dados de frames.

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

Limitação conhecida: gravar um elemento específico dentro de um pop-up que é renderizado na sua própria janela de topo (WinUI/XAML, dica de ensino, dica de ferramenta) pode capturar a janela principal subjacente em vez disso. Grava toda a janela ou segue o fluxo de trabalho de sobreposição de capturas de ecrã para imagens pop-up. Rastreado no #646.

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