Documentação e uso da CLI

Conclusão do shell

Habilite a conclusão da guia para comandos, opções e valores. Consulte o guia de Conclusão do Shell para obter instruções de instalação.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

Iniciar

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

winapp init [base-directory] [options]

Argumentos:

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

Opções:

--config-dir <path> - Diretório para leitura/configuração do repositório (padrão: o diretório do projeto selecionado ou o diretório atual se nenhum projeto for detectado)
--setup-sdks - Modo de instalação do SDK: 'estável' (padrão), 'versão prévia', 'experimental' ou 'nenhum' (ignorar instalação do SDK)
--ignore-config, --no-config - Não use o arquivo de configuração para o gerenciamento de versão
--no-gitignore - Não atualize o arquivo .gitignore
--use-defaults, --no-prompt – Não solicitar e usar o padrão de todos os prompts
--config-only – Manipular somente as operações de arquivo de configuração, ignorar a instalação do pacote
--exe <path> - Caminho para o executável do aplicativo. Requer --sparse. Gera um manifesto esparso somente 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 exe de área de trabalho existente. Ignora a instalação do SDK/pacote. Usar com o --exe.
--name <name> - Substituir o nome do pacote (somente esparso; padrão: inferido do exe)
--publisher <CN> - Substituir o CN do editor (somente esparso; padrão: inferido do nome da empresa do exe)
--output-dir <path> - Diretório para gravar o manifesto esparso e (somente esparso Assets/ ; padrão: uma sparse/ pasta no diretório atual)
--force - Substituir um existente appxmanifest.xml no diretório de destino (somente esparso). Sem ele, a inicialização falha em vez de substituir um manifesto/ativo existente.
--add-js-bindings (somente npm) – Adicionar winapp.jsBindings a package.json e gerar associações JS/TypeScript, sem solicitar (incompatível com --setup-sdks none)

O que faz:

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

Detecção automática de projeto:

Quando init é executado sem um argumento de diretório, ele executa uma pesquisa da árvore de diretório atual para localizar projetos compatíveis (até 10). Tipos de projeto com suporte:

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

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

Se um argumento de diretório for fornecido (por exemplo, winapp init . ou winapp init path/to/project), a pesquisa será ignorada e init verificará apenas esse diretório para um projeto compatível
Se --use-defaults (ou --no-prompt) for definido sem um argumento de diretório, init ignorará a pesquisa e inicializará o diretório atual de forma não interativa, avisando primeiro se nenhum tipo de projeto conhecido for detectado lá (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 prossiga imediatamente
Se exatamente um projeto for encontrado em outro lugar, você será solicitado a confirmar
Se vários projetos forem encontrados, você poderá selecionar qual deles será inicializado – o diretório atual está sempre disponível como uma opção de fallback
Se nenhum projeto for encontrado, você será avisado e perguntado se deve continuar de qualquer maneira
Se a pesquisa atingir o limite de 10 projetos, um aviso sugere fornecer um argumento de diretório

Fluxo de projeto de .NET automático:

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

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

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

Gera um manifesto de pacote esparso somente identidade para um executável da área de trabalho existente – a primeira etapa do fluxo de trabalho de empacotamento esparso. Ao contrário do fluxo completo init , isso ignora toda a instalação do SDK/pacote (pacotes de identidade esparsos não têm dependências do SDK) e gera apenas um manifesto e ativos de espaço reservado.

Infere o nome do pacote, o editor, a descrição e a versão do exe via FileVersionInfo (substitua com --name, --publisherou interativamente)
Grava appxmanifest.xml (com o nome exe substituído Executable) mais uma Assets/ pasta para uma sparse/ pasta no diretório atual (ou --output-dir)
--use-defaults / --no-prompt Usa para ignorar os prompts de substituição interativos (amigável à CI)
--exe sem --sparse é um erro

Os ativos são externos. O esparso .msix é somente identidade: os gerados Assets/ são resolvidos do diretório de instalação do aplicativo (o local do conteúdo externo) em runtime, não agrupados no .msix. Implante-os junto com seu aplicativo.

Próximas etapas depois winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> para criar a identidade .msix, em seguida winapp embed-identity <exe>. Consulte o Guia de Empacotamento Esparso para obter o passo a passo 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: instalar SDKs após a instalação inicial

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

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

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

novo

Crie um novo aplicativo WinUI com base em um modelo de SDK do Aplicativo Windows dotnet new oficial. Interativo por padrão; usa automaticamente os padrões em ambientes não interativos.

winapp new [options]

Opções:

-t, --template <short-name> - Nome curto do modelo (por exemplo winui, , winui-navview, winui-mvvm, winui-lib, ou winui-unittestum modelo experimental do Reator, como reactor ou reactor-mvu). Validado no pacote instalado em tempo de execução; executar winapp new --list para ver tudo. Padrão: winui (aplicativo XAML em branco).
-n, --name <name> - Nome do novo aplicativo/projeto (padrão: derivado de --output, caso contrário WinUIApp)
-o, --output <path> - Diretório no qual o aplicativo será criado (padrão: ./<name>)
--use-defaults, --no-prompt – Não solicitar; use padrões (modelo em branco, nome e mantenha o pacote de --output/--namemodelos instalado em vez de atualizá-lo)
--force - Scaffold mesmo que o diretório de saída já contenha arquivos
--template-version <latest|installed|version> – Versão do pacote de modelos do WinUI: latest instala o pacote publicado mais recente, installed mantém o que já foi baixado (sem rede) ou fixa uma versão explícita, como 1.2.3. Padrão: instale o mais recente quando nenhum pacote estiver presente, caso contrário, solicite a atualização de um pacote obsoleto (mantido as-is em ).--use-defaults
--list - Liste os modelos winui disponíveis e saia (instala o pacote mais recente primeiro se nenhum estiver instalado)
--json - Formatar saída como JSON

Modelos:

O pacote fornece dois estilos de aplicativo WinUI. Os modelos XAML definem a interface do usuário na marcação com um code-behind em C#. Os modelos de reator são C# puros sem XAML, usando um padrão MVU (Model-View-Update). A lista de modelos é lida ao vivo do pacote instalado, portanto, ela sempre reflete a versão que você tem – execute winapp new --list para ver o conjunto atual. Modelos comuns:

Nome curto	Descrição
`winui`	Aplicativo XAML mínimo em branco (empacotamento MSIX)
`winui-navview`	Aplicativo inicial do XAML NavigationView
`winui-tabview`	Aplicativo inicial do XAML TabView
`winui-mvvm`	Aplicativo XAML MVVM (CommunityToolkit.Mvvm)
`winui-lib`	Biblioteca de classes do WinUI 3
`winui-unittest`	Aplicativo MSTest empacotado; os testes são executados quando são iniciados
`reactor`	Experimental. Aplicativo reator em branco — C#puro, sem XAML
`reactor-mvu`	Experimental. Aplicativo reator demonstrando o padrão de MVU
`reactor-navview`	Experimental. Aplicativo de inicialização Do NavigationView do Reator
`reactor-tabview`	Experimental. Aplicativo inicial do Reactor TabView

Modelos de reator são experimentais. Eles fazem referência aos pacotes de pré-lançamento, cujas APIs podem ser alteradas Microsoft.UI.Reactor ou removidas em uma versão futura. winapp new marca-os (Experimental) dentro --list e no seletor interativo, define "Experimental": true--jsone imprime um aviso após o scaffolding um. Eles nunca são escolhidos como o modelo padrão. O reator também requer o SDK do .NET 10 ou mais recente; em um SDK winapp new mais antigo falha antecipadamente com a versão necessária em vez de estruturar um projeto que você não pode criar.

O nome curto 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 é aceito. Quando executado dentro de um projeto WinUI existente, dotnet new também apresenta modelos de item (por exemplo, uma página em branco), que winapp new adiciona ao projeto atual em vez de criar um novo.

Controle de versão do pacote de modelos:

winapp new não fixa mais uma versão específica do pacote de modelos. Se nenhum pacote estiver instalado, ele instalará o mais recente. Se um pacote mais antigo já estiver instalado, ele verificará o feed e, quando houver um mais recente, solicitará a atualização, exceto em execuções não interativas--use-defaults , que mantêm o pacote instalado. Use --template-version latest sempre para usar o mais novo sem solicitar ou --template-version installed sempre usar o pacote baixado sem uma verificação de rede. Passar uma versão explícita (por exemplo --template-version 1.2.3) sempre instala exatamente essa versão — reinstalando mesmo quando um pacote mais recente já está presente — portanto, o scaffolding é reproduzível entre computadores.

Uma primeira execução pode levar mais tempo: Instalar ou atualizar o pacote de modelos ou restaurar pacotes NuGet SDK do Aplicativo Windows ausentes usados pelo modelo selecionado pode exigir downloads adicionais. Isso também pode acontecer depois que uma nova versão do SDK do Aplicativo Windows for publicada. Se o scaffolding ainda estiver em execução após 10 segundos, winapp new atualize sua mensagem de status para indicar que os pacotes podem estar baixando ou restaurando.

O que faz:

Verifica se o SDK do .NET está instalado (falha rapidamente com as diretrizes, se ausente – winapp não instala as cadeias de ferramentas)
Instala ou atualiza o pacote de modelos oficial do WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) sob demanda
Enumera os modelos disponíveis do pacote instalado e delega o scaffolding para dotnet new <short-name>

Os modelos de aplicativo WinUI já incluem Windows empacotamento e identidade (Package.appxmanifest), portanto, nenhuma etapa separada winapp init é necessária. Para modelos de aplicativo, use winapp run para criar e iniciar o aplicativo. O winui-lib modelo produz uma biblioteca de classes para fazer referência a partir de um projeto de aplicativo (ele não tem manifesto do aplicativo). O winui-unittest modelo é um aplicativo MSTest empacotado cujos testes são executados quando o aplicativo é iniciado (winapp run) — não via dotnet test. winapp newscaffolds em relação à estrutura de destino do SDK .NET instalada e imprime a próxima etapa apropriada para o modelo escolhido.

Passe o sinalizador global --verbose (-v) para ecoar cada invocação subjacente dotnet (consulta de pacote, verificação de atualização, instalação, dotnet new listscaffold) juntamente com sua saída completa , útil para diagnosticar problemas de pacote de modelo ou scaffolding.

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

restauração

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

winapp restore [base-directory] [options]

Argumentos:

base-directory - Diretório a ser restaurado (padrão: diretório atual). Também seleciona de onde winapp.yaml e nuget.config são lidos --config-dir , a menos que o substitua.

Opções:

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

O que faz:

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

Observação

Para .NET projetos, não winapp.yaml há nenhuma versão do SDK ativada como PackageReference entradas, .csproj portantowinapp restore, é executada dotnet restore para você.

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, restoree update baixe os pacotes Windows SDK e SDK do Aplicativo Windows por meio do NuGet, respeitando sua hierarquia padrãonuget.config. Feeds privados e espelhos, credenciais de feed (incluindo provedores de credenciais) e um trabalho personalizado globalPackagesFolder como eles fazem.dotnet restore Para restaurar exclusivamente do seu próprio espelho, <clear /> as fontes herdadas e adicione 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 do diretório em que opera: o argumento derestoreinit/diretório, --config-dir quando fornecido, caso contrário, o diretório atual. Para .NET projetos, as fontes vêm da própria nuget.config hierarquia do projeto, porque isso é o que dotnet add package e dotnet restore o uso, então coloque a configuração de um feed privado no diretório do projeto ou em um ancestral. Uma --config-dir hierarquia externa é relatada e ignorada em vez de selecionar silenciosamente as versões que o projeto não pode restaurar. Execute esses comandos somente em diretórios em que você confia, a mesma cautela que se aplica a dotnet restore. Quando várias fontes estiverem configuradas, use o Mapeamento de Origem do Pacote para fixar cada pacote em um feed.

atualização

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

winapp update [options]

Opções:

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

O que faz:

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

Exemplos:

# Update packages to latest versions
winapp update

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

pacote

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

Passe um único .csproj para criar o projeto e empacote sua saída em uma etapa (modo de projeto, consulte Empacotar um projeto diretamente abaixo). Passe várias pastas de entrada para criar uma .msixbundle distribuição de várias arquiteturas (confira os pacotes de várias arquiteturas abaixo).

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

Argumentos:

input-folder - Um único .csproj para compilar e empacotar (modo de projeto) ou um ou mais diretórios que contêm os arquivos de aplicativo a serem empacotadas. Passe várias pastas (por exemplo, ./publish/x64 ./publish/arm64) para criar um pacote MSIX. Para pacotes de identidade esparsos, passe um arquivo esparso appxmanifest.xml diretamente em vez de uma pasta (confira os pacotes de identidade esparsos abaixo).

Opções:

--output <filename> - Nome do arquivo de saída. Para pacotes únicos: <name>_<version>_<arch>.msix (caindo para <name>_<version>.msix, <name>_<arch>.msixou <name>.msix). Para pacotes: <name>_<version>_<arch1>_<arch2>.msixbundle.
--name <name> - Nome do pacote (padrão: do manifesto)
--manifest <path> - Caminho para o arquivo de manifesto (Package.appxmanifest preferencial, appxmanifest.xml também com suporte; padrão: detecção automática)
--cert <path> - Caminho para assinar o certificado (habilita a assinatura automática)
--cert-password <password> - Senha de certificado (padrão: "senha")
--generate-cert – Gerar um novo certificado de desenvolvimento
--no-sign – Entregar o pacote sem sinal, substituindo qualquer configuração de assinatura de projeto (por exemplo, para envio da Loja ou um pipeline de assinatura externo). Não é possível combinar com --cert ou --generate-cert.
--install-cert – Instalar o certificado no computador
--publisher <name>- Publisher para geração de certificados. Aceita um nome X.500 completo diferenciado ou um nome nu (encapsulado automaticamente como CN=<name>)
--self-contained – tempo de execução do pacote SDK do Aplicativo Windows
--skip-pri - Ignorar a geração de arquivos PRI
--executable <path> - Caminho para o executável em relação à pasta de entrada (também --exe). Usado para resolver $targetnametoken$ espaços reservados no manifesto.

Project opções de modo (exigir uma .csproj entrada; rejeitada para entradas de pasta/pacote/manifesto):

--configuration <name> (-c) – Configuração de build (padrão: Release)
--arch <arch> - Arquitetura de destino: x64, arm64ou x86 (padrão: a arquitetura do processo atual)
--framework <tfm> (-f) – Moniker de estrutura de destino para projetos de vários destinos
--no-build - Empacotar a saída de build existente sem recompilar
--no-restore – Ignorar a restauração do projeto antes da criação
--property <name=value> (-p) – propriedade MSBuild, encaminhada para compilação e avaliação (repetível)

Observação: Para um WinUI/ EnableMsixTooling.csproj (modo de projeto de ferramentas MSIX), o SDK do Aplicativo Windows possui o manifesto, o ponto de entrada e a geração PRI, portanto--manifest, --executablee --skip-pri são rejeitados — configuram<AppxManifest>, o ponto de entrada do projeto e seu build de recursos no próprio projeto. Essas três opções ainda se aplicam a entradas de pasta e ao modo de projeto genérico (não msix-tooling .csproj ).

O que faz:

Valida e processa arquivos Package.appxmanifest
Resolve tokens $placeholder$ no manifesto (consulte espaços reservados de manifesto abaixo)
Garante dependências de estrutura adequadas
Atualiza manifestos lado a lado com registros
Descobre e agrupa automaticamente todos os arquivos que não são de imagem referenciados no manifesto (por exemplo, AppExtension, arquivos de configuração manifest.json) do diretório de manifesto ou da pasta de entrada se eles estiverem ausentes do preparo
Descobre automaticamente componentes winRT de terceiros e registra suas classes ativas (consulte a descoberta de componentes do WinRT abaixo)
Manipula a implantação autocontida do WinAppSDK
Assinar pacote se o certificado for fornecido

Empacotando um projeto diretamente

Quando a entrada é única .csproj, winapp pack cria o projeto (usando as opções acima) e empacota a saída resultante , não é necessário compilar separadamente ou localizar a pasta de saída primeiro. Isso espelha o winapp runmodo 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 de destino vem de --arch, ou de um solitário -p RuntimeIdentifier=<rid> quando você não passa --arch (o RID exato é preservado e impulsiona a compilação). Passar ambos --arch e -p RuntimeIdentifier é um conflito e é rejeitado.

O projeto deve ser criado como um aplicativo empacotado (EnableMsixTooling=true com um Package.appxmanifest); um projeto criado como um aplicativo não empacotado (WindowsPackageType=None) não tem nenhum manifesto MSIX para empacotar e winapp pack relata um erro acionável. As entradas de pasta, pacote e manifesto esparso não são alteradas.

Project modo produz um único .msix ou somente .msixbundle arquitetura (consulte pacotes de várias arquiteturas). Ele não produz arquivos de upload da Loja ou pacotes de divisão de recursos (idioma/escala): um explícito -p UapAppxPackageBuildMode=StoreUpload ou -p AppxBundleAutoResourcePackageQualifiers=... é rejeitado com uma anotação para executar o comando de empacotamento do SDK nativo diretamente para esses fluxos.

Pacotes de identidade esparsos

Quando a entrada é um arquivo esparso appxmanifest.xml (um declarando <uap10:AllowExternalContent>true</uap10:AllowExternalContent> em <Properties>) em vez de uma pasta, winapp pack cria um somente.msix identidade – ele empacota apenas o manifesto, sem binários ou ativos de aplicativo. Esta é a etapa 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 é <PackageName>.identity.msix padrão no diretório atual (substitua com --output).
A assinatura ocorre somente quando --cert (ou --generate-cert) é fornecido.
Se, em vez disso, você passar uma pasta cujo manifesto se declaraAllowExternalContent, o comportamento de empacotamento de pastas existente se aplicará, mas winapp pack avisará se ele encontrar ativos (.ico/.jpg/.png) ou binários (.exe.dll//.so) – para pacotes esparsos que pertencem ao local externo, não dentro do ..msix

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

Descoberta de componente do WinRT

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

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

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

Se o manifesto contiver $targetnametoken$ no Executable atributo:

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

Exemplos:

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

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

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

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

Pacotes de várias arquiteturas

Quando várias pastas de entrada são passadas, winapp pack cria uma contendo uma .msixbundle.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 detecta automaticamente a arquitetura de cada pasta do cabeçalho PE do executável primário, valida a consistência entre fatias (Identidade, Funcionalidades, Dependências) e produz um <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Resolução de manifesto para pacotes:

Cada fatia no pacote precisa de um manifesto. O comando resolve manifestos nesta ordem:

--manifest <path> — Se especificado, esse único manifesto é usado para todas as fatias. O ProcessorArchitecture valor é atualizado automaticamente por fatia para corresponder à arquitetura detectada.
Manifesto por pasta — se cada pasta de entrada contiver um Package.appxmanifest (ou appxmanifest.xml), o manifesto dessa pasta será usado para sua fatia.
Fallback do diretório atual – se uma pasta não tiver manifesto, o comando procurará Package.appxmanifest no diretório de trabalho atual e o usará (com a arquitetura carimbada automaticamente).

Em todos os casos, o manifesto é atualizado automaticamente: os espaços reservados são resolvidos, as dependências são injetadas e o ProcessorArchitecture conjunto de força para a arquitetura detectada. Após a resolução, uma validação entre fatias garante que a Identidade (Nome, Versão, Publisher), Funcionalidades e Dependências sejam consistentes em todas as fatias — só ProcessorArchitecture pode ser diferente. A versão do pacote definida nas fatias é atribuída à versão do pacote MSIX, exceto se for 0.0.0.0, nesse caso, uma versão baseada em carimbo de data/hora é 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

create-debug-identity

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

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

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

Argumentos:

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

Opções:

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

O que faz:

Modifica o manifesto de execução paralela do executável
Registra o pacote esparso para identidade
Habilita a depuração de APIs que exigem identidade

Exemplos:

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

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

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

Inserção de identidade

Conecte um aplicativo da área de trabalho ao seu pacote de identidade esparso inserindo o <msix> elemento no manifesto lado a lado (fusão) do aplicativo. Esta é a etapa 3 do fluxo de trabalho de empacotamento esparso , informa Windows a qual pacote de identidade o exe em execução pertence.

winapp embed-identity <target> [options]

Argumentos:

target - O arquivo a ser atualizado. Detectado automaticamente por extensão:
- .exe (Modo EXE) — insira o <msix> elemento diretamente no manifesto lado a lado do exe usando mt.exe.
- .xml / .manifest (Modo XML) — insere ou substitui o <msix> elemento em um arquivo de manifesto SxS externo (criado se ele não existir). Recompile seu aplicativo posteriormente para que o manifesto atualizado seja inserido no binário.

Opções:

--manifest <path> - Caminho para a identidade de leitura esparsa appxmanifest.xml (packageName, publisher, applicationId). Quando omitido, o comando pesquisa uma sparse/ pasta ao lado do destino primeiro, depois no diretório atual, depois no diretório do destino e no diretório atual.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

Esse comando é idempotente: executá-lo novamente substitui qualquer elemento existente <msix> em vez de duplicá-lo.

manifesto

Gere e gerencie arquivos Package.appxmanifest.

geração de manifesto

Gere Package.appxmanifest a partir de modelos.

winapp manifest generate [directory] [options]

Argumentos:

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

Opções:

--package-name <name> - Nome do pacote (padrão: nome da pasta)
--publisher-name <name>- Publisher nome diferenciado (padrão: CN=<usuário> atual). Aceita um DN X.500 com componentes separados por vírgulas de valor único (NÃO há suporte para RDNs e backslashes de vários valores + ); os nomes nus são encapsulados automaticamente como CN=<name>.
--version <version> – Versão (padrão: "1.0.0.0")
--description <text> - Descrição (padrão: "Meu Aplicativo")
--entrypoint <path> – Executável de ponto de entrada ou script
--template <type> - Tipo de modelo: packaged (padrão) ou sparse
--logo-path <path> - Caminho para o arquivo de imagem do logotipo
--if-exists <Error|Overwrite|Skip> – Comportamento quando o arquivo de manifesto já existe no caminho de destino (padrão: Error)

Modelos:

packaged - Manifesto do aplicativo empacotado padrão
sparse - Manifesto do aplicativo usando o empacotamento de localização esparso/externo

Marcadores de posição de manifesto

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

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

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

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

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

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

Exemplos:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

suplemento de manifesto

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

winapp manifest add-alias [options]

Opções:

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

O que faz:

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

Exemplos:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifest atualizar-recursos

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

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

Argumentos:

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

Opções:

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

Descrição:

Usa uma única imagem de origem e gera um conjunto abrangente de ativos de imagem MSIX com base nas referências de ativos do manifesto:

Para cada ativo referenciado no manifesto:

5 variantes de escala — base (sem sufixo), .scale-125, , .scale-150, .scale-200.scale-400

Para o ícone do aplicativo (Square44x44Logo /AppList, 44×44 base):

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

Additionally:

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

Com --light-image:

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

Suporte ao SVG: Os arquivos SVG têm suporte total como imagens de origem. Eles são renderizados como vetores diretamente em cada tamanho de destino, produzindo resultados perfeitos em todas as resoluções. O arquivo deve declarar seu próprio tamanho, por meio de um viewBox ou absoluto width e height atributos; uma largura percentual sem viewBox nenhuma descreve nenhum tamanho específico. Uma fonte que declara nenhum dos dois é rejeitada SVG image has no usable dimensions em vez de produzir ativos em branco.

O comando dimensiona as imagens proporcionalmente, mantendo a taxa de proporção, centralizando-as com planos de fundo transparentes quando necessário. Os ativos são salvos no diretório Assets relativo ao local do manifesto.

Exemplos:

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

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

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

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

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

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

execução

Crie um pacote de layout solto de uma pasta de saída de build, registre-o com Windows usando a API Windows.Management.Deployment.PackageManager e inicie o aplicativo, simulando uma instalação msix completa para depuração. Retorna a ID do processo para anexo do depurador.

winapp run opera em um dos três modos, escolhidos automaticamente da entrada:

Modo de pasta – a entrada é uma pasta de saída de build (contém um Package.appxmanifest/AppxManifest.xml).
Project modo — a entrada é um.csproj, uma .sln/.slnx solução ou um diretório que contém um. winapp run cria o projeto e o inicia, dando suporte a aplicativos WinUI empacotados e não empacotados . Veja Project modo abaixo.
Modo de arquivo único – a entrada é um .csaplicativo baseado em arquivo .NET. winapp run cria-o, gera um manifesto de suas #:property diretivas e inicia-o com a identidade do pacote.

Dica

A seleção de modo é silenciosa por padrão. Se um diretório foi tratado como uma pasta de saída de build quando você esperava que ele fosse criado como um projeto, execute novamente com --verbose — o modo de pasta relata por que ele foi escolhido (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Um diretório só é criado como um projeto quando um .csproj/.slnx/.slnaplicativo com runnable fica em seu nível superior; ele não é pesquisado recursivamente.

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

winapp run [<input>] [options]

Argumentos:

input- O aplicativo a ser executado: uma pasta de saída de build (modo de pasta), um .cs aplicativo baseado em arquivo .NET (modo de arquivo único), um .csproj projeto, uma .sln/.slnx solução ou um diretório que contém um daqueles em seu nível superior (modo de projeto; o diretório não é pesquisado recursivamente). Use . para compilar/executar o projeto no diretório atual. Opcional – usa como padrão o diretório atual quando omitido (corresponde dotnet run).

Opções:

--manifest <path> - Caminho para Package.appxmanifest (padrão: detectar automaticamente da pasta de entrada ou do diretório atual)
--output-appx-directory <path> - Diretório de saída para o layout solto (padrão: AppX dentro da pasta de entrada). O layout padrão remove os arquivos que não estão mais no build; um diretório personalizado mantém arquivos extras. Use um novo diretório personalizado quando precisar de um layout limpo.
--args <string> - Argumentos de linha de comando a serem passados para o aplicativo. Como alternativa, use -- seguido de argumentos para evitar escape (por exemplo, winapp run . -- --flag value).
--no-launch - Crie apenas a identidade de depuração e registre o pacote sem iniciar o aplicativo
--with-alias – Inicie o aplicativo usando seu alias de execução em vez de ativação do AUMID. O aplicativo é executado no terminal atual com stdin/stdout/stderr herdado. Raramente necessário: um aplicativo com OutputType=Exe já é iniciado dessa forma por padrão. o winapp adiciona o necessário uap5:ExecutionAlias ao manifesto que ele realiza no layout do AppX, portanto, nenhuma alteração no manifesto de check-in é necessária; um alias que o aplicativo se declara é usado as-is. Não é possível combinar com --no-launch, --detach, --without-aliasou --json.
--without-alias – Forçar a ativação do AUMID para um aplicativo que, de outra forma, seria iniciado por meio de um alias de execução. Em seguida, um aplicativo de console é executado sem um console e não imprime nada neste terminal. Não é possível combinar com --with-alias.
--debug-output – Capturar OutputDebugString mensagens e exceções de primeira chance do aplicativo iniciado. O ruído da estrutura (WinUI, COM, DirectX) é filtrado da saída do console; o arquivo de log completo captura tudo. Se o aplicativo falhar, capturará automaticamente um minidump e o analisará para mostrar o tipo de exceção, a mensagem e o rastreamento de pilha com números de arquivo de origem:linha (resolvidos de PDBs na pasta de saída de build). Falhas gerenciadas (.NET) são analisadas instantaneamente sem ferramentas externas. Falhas nativas (C++/WinRT) mostram os nomes e deslocamentos do módulo. Quando o aplicativo com falha é um aplicativo WinUI 3 (Microsoft.UI.Xaml.dll é carregado), um passe de triagem de exceção extra stowed é executado automaticamente para exibir o HRESULT de origem, sua cadeia ErrorContext e a pilha de expedição XAML nativa completa; os componentes do depurador necessários são baixados no primeiro uso (consulte Depuração, substituível por meio da variável de WINAPP_DBGTOOLS_DIR ambiente). Somente um depurador pode anexar a um processo de cada vez, portanto, outros depuradores (Visual Studio, VS Code) não podem ser usados simultaneamente. Em vez disso, use --no-launch se precisar anexar um depurador diferente. Não é possível combinar com --no-launch. Não é possível combinar com --json.
--symbols – Baixe símbolos PDB do servidor de símbolos Microsoft para uma análise de falha nativa mais avançada com nomes de função resolvidos. Usado somente com --debug-output. Se ocorrer omitido e ocorrer uma falha nativa, a saída sugerirá a adição desse sinalizador. Esse sinalizador também melhora a pilha de triagem de exceção do WinUI para aplicativos WinUI 3. A primeira execução baixa símbolos e os armazena em cache localmente; as execuções subsequentes usam o cache.
--unregister-on-exit - Cancele o registro do pacote de desenvolvimento após a saída do aplicativo. Remove apenas os pacotes registrados no modo de desenvolvimento. Não é possível combinar com --no-launch.
--detach – Inicie o aplicativo e retorne imediatamente sem esperar que ele saia. Útil para CI/automação em que você precisa interagir com o aplicativo após a inicialização. As execuções locais imprimem o PID; as execuções de destino imprimem o destino da interface do usuário com escopo. O JSON inclui o PID e o escopo de destino. Não é possível combinar com --no-launch, --debug-output, --with-aliasou --unregister-on-exit.
--clean - Remova os dados do aplicativo do pacote existente (LocalState, configurações etc.) antes de implantar novamente. Por padrão, os dados do aplicativo são preservados em relançamentos.
--json - Formatar a saída como JSON para consumo programático (por exemplo, CI/automação). Útil para --detach capturar o PID. Não é possível combinar com --with-alias ou --debug-output.
--on <target> - Compile no host e, em seguida, registre-se e execute no destino. Atualmente, há suporte sandboxpara , sem fallback para execução local. Use antes dos --detach comandos de interface do usuário de acompanhamento. A área restrita --debug-output requer um aplicativo empacotado. Consulte Windows execução de área restrita para instalação, suporte de runtime e tempo de vida de aplicativo desanexado.

Persistência de dados do aplicativo:

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

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

O que faz:

Localiza ou gera o Package.appxmanifest
Cria e registra uma identidade de depuração usando um pacote de layout flexível
Calcula a ID do modelo de usuário do aplicativo (AUMID)
Inicia o aplicativo usando a identidade registrada (a menos que --no-launch seja especificado)
ID do processo impresso (PID) para anexo do depurador

Exemplos:

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

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

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

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

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

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

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

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

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

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

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

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

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

modo Project (.NET projetos do SDK)

Quando a entrada é uma .csproj, uma .sln/.slnx solução ou um diretório que contém um (incluindo .), winapp runcria o projeto com dotnet build e, em seguida, inicia-o. Ele dá suporte a aplicativos WinUI empacotados e não empacotados e instala a arquitetura correspondente aplicativo do Windows Runtime de que o aplicativo precisa antes de ser iniciado.

Entrada da solução: aponte winapp run para um .sln.slnx/(ou um diretório que contém um – uma solução é preferencial em vez de arquivos soltos.csproj) e resolve o projeto de aplicativo executável e, em seguida, cria-o com $(SolutionDir) e as propriedades irmãos Solution* definidas, de modo que os projetos que dependem deles são compilados como fazem em Visual Studio. Regras de resolução:

Os projetos de teste são ignorados durante a seleção automática, portanto, uma solução que contém um aplicativo mais seus testes é resolvida para o aplicativo sem --project necessidade. (Um projeto de teste do WinUI é em si um aplicativo empacotado, portanto, o tipo de saída sozinho não pode distingui-lo.)
Se o único projeto executável for um projeto de teste, ele será executado.
Se houver mais de um projeto de aplicativo executável, winapp run não adivinhará um projeto de inicialização , ele errou ao listar os candidatos. Use --project <name> para escolher, o que é sempre honrado, inclusive para selecionar um projeto de teste.

Packaged vs. unpackaged é detectado automaticamente da propriedade msbuild efetiva WindowsPackageType do projeto (nunca da presença do manifesto):

Empacotado (WindowsPackageType=MSIX, o padrão empacotado por WinUI) — compila e registra a saída de build como um pacote de layout flexível e é iniciado por meio do AUMID (o mesmo pipeline que o modo de pasta).
Desempacotado (WindowsPackageType=None) – compila, garante que o aplicativo do Windows Runtime dependente da estrutura esteja instalado e inicie o compilado .exe diretamente. Force isso para um projeto empacotado com -p WindowsPackageType=None.

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

AOT nativo: adicione esse grupo de propriedades dentro do elemento do <Project> arquivo project e adicione--aot:

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

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

--aotdá suporte a projetos x64 e ARM64 e requer o SDK .NET 8.0.300 ou mais recente. Ele é executado dotnet publish com a configuração AOT do projeto e, em seguida, inicia essa saída; use -p PublishAot=true para uma substituição única. Ele não executa a certificação de runtime separada e não pode ser combinado com --no-build ou --manifest.

Para aplicativos que usam a identidade do pacote sem um layout MSIX gerado, inclua Package.appxmanifest ou appxmanifest.xml na saída de publicação do projeto. O Winapp prepara os arquivos publicados com esse manifesto. Se ambos os nomes estiverem presentes, o winapp será interrompido em vez de escolher um; remova o manifesto obsoleto e configure o projeto para publicar somente o manifesto pretendido.

opções de modo Project (ignoradas no modo de pasta, a menos que indicado):

-c, --configuration <name> – Configuração de build. Padrão: Debug. (Também respeitado no modo de arquivo único.)
--arch <x64|arm64|x86> – Arquitetura de destino. Padrão: a arquitetura do processo atual. Determina o build RID e aplicativo do Windows arquitetura de runtime e seleciona um perfil de publicação dependente da plataforma correspondente quando exigido pelo build efetivo. (Também respeitado no modo de arquivo único.)
-r, --runtime <rid>- Identificador de runtime de .NET de destino (por exemplowin-x64). Project modo usa apenas a arquitetura do RID, sempre cria o canônico win-<arch>e rejeita RIDs não Windows (por exemplolinux-x64). Sua arquitetura substitui --arch e pode selecionar o perfil de publicação necessário. (Também respeitado no modo de arquivo único, em que ele substitui um #:property RuntimeIdentifier declarado pelo arquivo.)
-f, --framework <tfm> - Moniker de estrutura de destino para projetos de vários destinos (por exemplo net10.0-windows10.0.26100.0). (Rejeitado no modo de arquivo único — use #:property TargetFramework=....)
--project <name-or-path> - Quando a entrada é uma solução (.sln/.slnx) ou um diretório com vários projetos de aplicativo executáveis, seleciona qual projeto será iniciado (por nome ou caminho do projeto). (Rejeitado no modo de arquivo único — um .cs aplicativo baseado em arquivo é o próprio projeto.)
--no-build - Ignore a compilação e execute a saída de build existente (ainda avalia as propriedades de saída). (Também respeitado no modo de arquivo único.)
--no-restore – Ignore a restauração antes da criação ou da publicação do AOT nativo. (Também respeitado no modo de arquivo único.)
--aot– Execute o projeto configurado .NET publicação AOT nativa. Requer eficácia PublishAot=true. Rejeitado em modos de pasta e arquivo único.
-p, --property <Name=Value> - Propriedade MSBuild, encaminhada para a compilação e a avaliação da propriedade. Repita -p para várias propriedades; use %3B ou %2C para um ponto-e-vírgula literal ou vírgula em um valor. (Também respeitado no modo de arquivo único, em que é a única maneira de definir TargetFramework.)

Saída de build & verbosidade: uma execução de projeto comum usa dotnet builde, em seguida, avalia a saída compilada. Restaurar e criar fluxo de saída ao vivo, com credenciais de URLs de feed autenticadas redigidas. Com --aot, o winapp usa dotnet publish; --verbose mostra o comando de publicação e os caminhos resolvidos. Use as opções de verbosidade abaixo para controlar o que é mostrado:

Flag	verbosidade dotnet	Adiciona
(padrão)	`minimal`	—
`--verbose`	`minimal`	Rastreamentos de decisão de build do winapp
`--quiet`	`quiet`	—

O AOT nativo publica fluxos de saída à medida que chega. Em --json, invocações de restauração/build e saída filho vão para stderr para que stdout permaneça puro JSON. Em , --quietas invocações são suprimidas e a saída silenciosa de restauração/build do dotnet é roteada para stderr para que stdout permaneça limpo. A saída de publicação AOT nativa também vai para stderr em qualquer opção.

Aplicabilidade de opção: as opções de identidade/layout flexível (--manifest, , --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, , --clean) --executablese aplicam somente a aplicativos empacotados. Eles são rejeitados com um erro claro para aplicativos não empacotados (que não têm nenhum pacote MSIX). As opções de inicialização/depuração (--args/--, , --detach, --debug-output--symbols, ) --jsonfuncionam em ambas.

exemplos do 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 arquivo único (.NET aplicativos baseados em arquivo)

.NET 10 permite que você execute um único .cs arquivo sem nenhum arquivo de projeto, configurando-o com #: diretivas na parte superior. Aponte winapp run para esse arquivo e ele cria o aplicativo, gera um appxmanifest para ele e inicia-o com a identidade do pacote . Portanto Windows.ApplicationModel.Package.Current , funciona, o aplicativo obtém um AUMID real e uma entrada de menu Iniciar, e as APIs que simplesmente exigem identidade (notificações de aplicativo, ApplicationDataIA no dispositivo) funcionam.

Integrações de shell, como manipuladores de protocolo, associações de arquivos, destinos de compartilhamento e tarefas de inicialização, precisam de uma entrada declarada <Extensions> , que o manifesto gerado não contém. Para adicionar um, crie seu próprio manifesto – confira Traga seu próprio manifesto abaixo.

winapp run counter.cs

Ou execute-o sem formatação dotnet run – consulte Executar com dotnet run abaixo.

Você não cria um manifesto. Em vez disso, descreva o pacote com #:property diretivas:

#: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 do manifesto. Todos são opcionais; cada um volta para um padrão sensato:

Propriedade	Conjuntos	Padrão
`WinAppPackageName`	`Identity/@Name` (a identidade do pacote)	o nome do arquivo, sanitizado para `[-.A-Za-z0-9]`, além de um hash curto do caminho do arquivo (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	O nome mostrado em Iniciar e Configurações	o nome do arquivo sem sua extensão
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Um nome nu é encapsulado como `CN=<name>`.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, normalizado (veja abaixo)
`WinAppDescription`	A descrição mostrada durante a instalação e em Configurações	o nome de exibição
`WinAppCapabilities`	Recursos a serem declarados, separados por `;` ou `,`	nenhum

Version. Uma versão do pacote deve ser exatamente quatro números, cada um de 0 a 65535. WinAppVersion (ou, se você não defini-la, a propriedade padrão Version ) será normalizada para se ajustar a: qualquer um -preview/-rc o sufixo é descartado e os componentes ausentes são preenchidos com zeros, portanto #:property Version=1.2.3-preview.4 , torna-se 1.2.3.0 e define a versão do assembly e a versão do pacote juntas. Um valor que não pode ser feito para ajustar - um componente acima de 65535 ou mais de quatro componentes - é rejeitado com um erro em vez de silenciosamente alterado.

Capabilities

Seu aplicativo executa a confiança total com a identidade, o que satisfaz AS APIs que exigem apenas um aplicativo empacotado. Mas algumas APIs são fechadas em uma funcionalidade declarada independentemente – as APIs de IA Windows são o caso comum. (As integrações do Shell, como manipuladores de protocolo e associações de arquivos, são um terceiro caso: essas precisam de entradas criadas <Extensions> , não de uma funcionalidade, portanto, use seu próprio manifesto para elas.)

#:property WinAppCapabilities=systemAIModels

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

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

O winapp grava cada um deles no elemento e no namespace XML que ele realmente requer, declara esse namespace e aumenta MaxVersionTested quando a funcionalidade precisa de um mais recente. Isso importa mais do que parece: as funcionalidades são distribuídas entre vários elementos diferentes e a mesma lista acima se torna três formas diferentes —

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

Nomes que winapp sabe que são escritos para você. Para qualquer outra coisa — o conjunto restrito cresce ao longo do tempo — qualifique-o por conta própria com o prefixo do namespace:

prefixo	Emite
`rescap:`	`<rescap:Capability>` — recursos restritos
`uap:`, `uap6:`, , `uap7:uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` no namespace padrão

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Um nome nu não reconhecido é rejeitado com um erro nomeando esses prefixos, em vez de adivinhado , uma funcionalidade emitida no namespace errado produz um manifesto Windows se recusa a registrar ou aceita enquanto silenciosamente não o concede.

Traga seu próprio manifesto

Se você precisar de algo que as propriedades não abrangem — um manipulador de protocolo, uma associação de arquivos, um alias de execução — crie um manifesto e winapp run o usará verbatim em vez de gerar um. Ele é obtido de, em ordem:

--manifest <path> na linha de comando.
#:property WinAppManifestPath=<path> no .cs arquivo.
Um manifesto sentado ao lado do .cs arquivo, nomeado <filename>.appxmanifest (por exemplo counter.appxmanifest , ao lado counter.cs).

Somente esse nome por arquivo é coletado automaticamente. Uma Package.appxmanifest ou appxmanifest.xml na mesma pasta é deliberadamente ignorada– vários .cs arquivos podem compartilhar uma pasta e adotar um nome compartilhado executaria silenciosamente um aplicativo sob a identidade de outro. Para usar um manifesto para vários arquivos, nomeie-o explicitamente com --manifest ou WinAppManifestPath.

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

Options. Cada opção de modo de pasta funciona: --no-launch, , --with-alias, --without-alias, --detach, --clean, --debug-output, --symbols, --unregister-on-exit,----args/ , --json, , --executable, --manifest, , --output-appx-directory, mais -c/--configuration, --no-build, --no-restoree .-p/--property

Dica

Um aplicativo de console é impresso no terminal por padrão. Um aplicativo empacotado iniciado por meio da AUMID não tem console, portanto, um aplicativo somente console seria executado corretamente e não imprimiria nada. Winapp evita isso: um aplicativo com OutputType=Exe é iniciado por meio de um alias de execução, que herda o stdin/stdout/stderr deste terminal. Você ainda obtém a identidade do pacote e não precisa perguntar:

winapp run counter.cs

Passe --without-alias para forçar a ativação do AUMID, em vez disso, o aplicativo é executado sem um console e não imprime nada aqui. Um aplicativo com janelas (WinExe) mostra uma janela, portanto, ele mantém a ativação do AUMID; passe --with-alias se você quiser um neste terminal de qualquer maneira. Para corrigir a opção no arquivo em vez de em cada linha de comando, defina a mesma propriedade .csproj usada:

#:property WinAppRunUseExecutionAlias=false

O alias winapp declares é nomeado em homenagem ao nome da família de pacotes, com um winapp- prefixo , portanto com.contoso.counter , publicado por CN=You gets winapp-com.contoso.counter_gspb8g6x97k2t.exe. Essa parte à direita é o hash do editor Windows deriva, portanto, dois aplicativos que compartilham um nome em diferentes editores ainda recebem aliases diferentes. O prefixo mantém o nome livre de comandos reais: um aplicativo em python.cs obtém um winapp-… alias, nunca python.exe. Se você criar seu próprio manifesto, o alias que você declara que há é usado as-is e o winapp não adiciona nada.

Isso se aplica somente ao alias. O registro em si é inserido no nome do pacote, portanto, a execução de um segundo aplicativo que declara o mesmo WinAppPackageName em um editor diferente substitui o primeiro registro em vez de sentar ao lado dele. Dê a cada aplicativo seu próprio nome se você quiser que ambos se registrem ao mesmo tempo.

winapp run Imprime o alias que ele registrou, para que você não precise calcular o hash para encontrá-lo.

O alias é um comando em seu PATH que dura desde que o pacote permaneça registrado. Se algum outro pacote já possui o nome, o winapp diz isso. Quando infere o alias para você, ele é iniciado por meio do AUMID, em vez de iniciar o aplicativo errado; quando você pediu um explicitamente – com --with-alias ou #:property WinAppRunUseExecutionAlias=true – ele falha em vez de fazer algo mais silenciosamente.

Duas opções de modo de projeto não se aplicam, porque um aplicativo baseado em arquivo se configura. Eles são rejeitados com uma mensagem nomeando a diretiva a ser usada em vez disso:

Opção	Em vez disso, use
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	nothing — o `.cs` arquivo é o projeto

--arch e -r/--runtime funcionam como fazem no modo de projeto. Quando você não passa nenhum dos dois, o winapp cria para a arquitetura do computador , que é o que um aplicativo SDK do Aplicativo Windows autocontido precisa, pois sem ele o SDK AnyCPU cria e falha com WindowsAppSDKSelfContained requires a supported Windows architecture. Um #:property RuntimeIdentifier=win-arm64 no arquivo é respeitado; um explícito --arch/--runtime o substitui.

Os dois trabalhos empacotados e desempacotados, detectados do efetivo WindowsPackageType exatamente como no modo de projeto: o padrão registra um layout flexível e o inicia com a identidade, enquanto #:property WindowsPackageType=None cria o aplicativo, instala o aplicativo do Windows Runtime correspondente e inicia diretamente.exe. (Um aplicativo empacotado é iniciado por meio de seu alias de execução ou por meio da ativação do AUMID – consulte a observação do console acima; essa opção é separada de se ele está empacotado.) As opções de identidade (--no-launch, , --with-alias, --without-alias, --clean, --unregister-on-exit--manifest, ) --output-appx-directoryse aplicam somente a aplicativos empacotados.

Executando com `dotnet run`

Você não precisa digitar winapp . Fazer referência ao Microsoft.Windows.SDK.BuildTools.WinApp pacote do arquivo e do modo simples dotnet run oferece a mesma inicialização empacotada:

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

O MSBuild do pacote destina-se a redirecionar a execução para o winapp, que empacota, registra e inicia o aplicativo que dotnet run acabou de ser criado– ele não é recriado. O tratamento de manifesto não é alterado: o winapp resolve exatamente como ele faz para winapp run, portanto #:property WinAppManifestPath=… , e um <filename>.appxmanifest lado dos .cs dois são honrados (consulte Traga seu próprio manifesto), um diretório em todo Package.appxmanifest o diretório ainda é ignorado e, caso contrário, um é gerado a partir de suas #:property diretivas e atualizado a cada execução.

Duas condições precisam ser retenção para que o redirecionamento aconteça:

Diretiva	Por que
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	os destinos que fazem a remessa de redirecionamento neste pacote
`#:property TargetFramework=net10.0-windows…`	um arquivo simples `net10.0` é deixado sozinho, portanto, ele é executado desempacotado

Adicionar #:property WindowsPackageType=None também deixa o arquivo sozinho: dotnet run em seguida, executa diretamente .exe , sem identidade. Use winapp run o caminho não empacotado se desejar que o aplicativo do Windows Runtime correspondente seja instalado primeiro.

Defina #:property EnableWinAppRunSupport=false para recusar totalmente o redirecionamento e as WinAppRun* propriedades descritas em Configuração para moldar a inicialização, por exemplo:

#:property WinAppRunUnregisterOnExit=true

Se dotnet run executar o aplicativo desempacotado quando você esperava a identidade, pergunte ao MSBuild por quê. Use dotnet build, não dotnet msbuild — sintetiza apenas dotnet build o projeto virtual pelo qual um aplicativo baseado em arquivo é compilado por meio de:

dotnet build counter.cs -t:WinAppRunSupportInfo

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

O registro sobrevive à execução. winapp run counter.cs deixa o pacote registrado após a saída do aplicativo, exatamente como pasta e modo de projeto, portanto LocalState , sobrevive e executar novamente o mesmo arquivo reutiliza a mesma identidade em vez de acumular registros. o winapp diz isso na primeira vez em que registra um aplicativo e winapp unregister usa o .cs próprio:

# 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 nenhum caminho de manifesto: ele avalia os valores do arquivo da #:property mesma maneira run e remove apenas um pacote registrado da saída de build desse arquivo. Um aplicativo com o mesmo nome registrado de uma pasta diferente é recusado, a menos que você passe --force. Se a execução usou uma opção que forma 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

-psubstitui as próprias diretivas do arquivo e uma ao lado da .cs chave pode WinAppPackageName ser desativada $(Configuration) ou $(RuntimeIdentifier) , portanto, cada uma Directory.Build.props delas pode alterar qual pacote é registrado.

Depois que a saída temporária do SDK tiver sido limpa, winapp unregister counter.cs não será mais possível confirmar se o registro veio desse arquivo e o ignorará – use winapp unregister --prune para limpar registros cujos arquivos foram removidos ou --force para remover um específico de qualquer maneira. Se a execução for usada --output-appx-directory, passe o mesmo diretório para unregister que ele possa reconhecer o layout.

O mesmo se aplica a um caminho de saída personalizado: a propriedade é confirmada do layout padrão <root>\bin\<configuration> do SDK, portanto, uma execução criada com -p OutputPath=<somewhere-else> não pode ser correspondida ao arquivo de origem. unregister ignora-o em vez de adivinhar em um diretório mais amplo – nomeie o layout com --output-appx-directoryou use --force.

Exemplos de arquivo único:

# 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 hash curto do caminho do arquivo — counter.cs torna-se algo parecido counter-a1b2c3d4 — portanto, dois counter.cs arquivos em pastas diferentes são aplicativos diferentes e mantêm suas próprias configurações e LocalState. O hash é derivado do caminho, portanto, ele sobrevive a edições e execuções novamente e só é alterado se você mover o arquivo. Defina #:property WinAppPackageName=<name> para escolher uma identidade estável por conta própria; ela é normalizada para o que Identity/@Name permite – caracteres externos [-.A-Za-z0-9] são descartados, nomes com menos de 3 caracteres são adicionados 1e o resultado é limitado a 50 caracteres, portanto My App , registra como MyApp. De qualquer forma, o menu Iniciar e as Configurações mostram o WinAppDisplayName (padrão: o nome do arquivo), não a identidade. A identidade sempre tem o escopo de sua conta de usuário, portanto, ela nunca colide com outro usuário no mesmo computador.

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 gravado depois dotnet run é passado para seu aplicativo, exatamente como seria sem o pacote. Configure o inicializador 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 seu .csproj comportamento de controle:

Propriedade	Padrão	Descrição
`EnableWinAppRunSupport`	`true`	Habilitar/desabilitar a funcionalidade de suporte de execução
`WinAppLaunchArgs`	(vazio)	Argumentos a serem passados para o aplicativo na inicialização
`WinAppRunUseExecutionAlias`	inferido do aplicativo	Inicie por meio de alias de execução em vez de ativação do AUMID. Não definido à esquerda, o winapp o infere: um aplicativo de console usa um alias para que sua saída chegue ao terminal, um aplicativo com janelas use a AUMID. Defina `true` ou `false` decida você mesmo.
`WinAppRunNoLaunch`	`false`	Registrar apenas a identidade sem iniciar
`WinAppRunDebugOutput`	`false`	Capturar `OutputDebugString` mensagens e exceções de primeira chance. Somente um depurador pode anexar por vez (impede VS/VS Code). Em vez disso, use `WinAppRunNoLaunch` para anexar um depurador diferente.
`WinAppRunDetach`	`false`	Retorne imediatamente após a inicialização, em vez de aguardar a saída do aplicativo. Imprime o PID.
`WinAppRunUnregisterOnExit`	`false`	Cancelar o registro do pacote de desenvolvimento após a saída do aplicativo
`WinAppRunClean`	`false`	Remover os dados do aplicativo do pacote existente (LocalState, configurações) antes de implantar novamente
`WinAppRunSymbols`	`false`	Baixe símbolos do servidor de símbolos do Microsoft para uma análise de falha nativa mais avançada. Só tem um efeito com `WinAppRunDebugOutput`.
`WinAppRunExecutable`	(vazio)	Caminho executável relativo à pasta build-output. Use quando o manifesto contiver $targetnametoken$ e a pasta de saída tiver mais de um `.exe`.
`WinAppRunArgs`	(vazio)	Argumentos brutos acrescentados à `winapp run` linha de comando, para opções sem propriedade dedicada (por exemplo `--verbose`). Acrescentado após cada propriedade acima.

Configurações mutuamente exclusivas. WinAppRunNoLaunch e WinAppRunDetach cada um descreve um comportamento de inicialização diferente, para que eles entrem em conflito com as outras propriedades de inicialização e entre si. A configuração de um par conflitante falha na execução com --X and --Y cannot be used together:

Propriedade	Não é possível combinar com
`WinAppRunNoLaunch`	`WinAppRunDetach`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias não está deliberadamente nessa lista, em qualquer direção. false solicita a ativação do AUMID, que já é usada sem inicialização e desanexação; true simplesmente não é aplicado quando um dos dois está definido, porque um alias de execução precisa de um processo controlado e em execução. Portanto, um projeto que faz check-in <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> ainda é executado de forma dotnet run -p:WinAppRunDetach=truelimpa, iniciando via AUMID em vez de falhar.

WinAppRunUseExecutionAlias, WinAppRunDebugOutpute WinAppRunUnregisterOnExit pode ser combinado um com o outro. WinAppRunClean, WinAppRunSymbolse WinAppRunExecutableWinAppLaunchArgs não tem restrições. WinAppRunArgs não adiciona nenhuma restrição própria, mas uma opção passada por ela é verificada como qualquer outra, portanto WinAppRunArgs="--detach" , ainda entra em conflito com WinAppRunNoLaunch.

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

Unregister

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

winapp unregister [input] [options]

Argumentos:

input- Caminho para um aplicativo baseado em arquivo .NET (um único.cs) cujo pacote deve ser não registrado. Sua identidade é resolvida da mesma forma winapp run que a resolve – de um manifesto criado se o aplicativo tiver um, caso contrário, de seus #:property valores – para que nenhum caminho de manifesto seja necessário. Omita para usar --manifest ou detectar automaticamente um manifesto no diretório atual. Não é possível combinar com --manifest, que nomeia o pacote de uma maneira diferente e pode ser resolvido para outro.

Opções:

--manifest <path> - Caminho para Package.appxmanifest (padrão: detecção automática do diretório atual)
--force - Somente para cancelar o registro local, ignore a verificação do diretório de local de instalação e cancele o registro, mesmo que o pacote tenha sido registrado em uma árvore de projeto diferente. Ele é rejeitado com --on; as verificações de propriedade de destino não podem ser ignoradas.
--on <target> – Remova o registro de desenvolvimento correspondente de propriedade do sandboxwinapp, não deste computador. Requer um manifesto e não dá suporte --force. Consulte a limpeza do aplicativo área restrita.
--prune – Remova todos os registros de modo de desenvolvimento cujos arquivos foram removidos. Não pode ser combinado com uma entrada, --manifest, --property, , --configuration, --arch, --runtimeou --output-appx-directory.
-p, --property <Name=Value> - Propriedade MSBuild usada ao resolver a identidade de um .cs aplicativo baseado em arquivo. 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 comando substitui as próprias #:property diretivas do arquivo. Aplica-se apenas a uma .cs entrada.
-c, --configuration <name> – Configuração de build usada ao resolver a identidade de um .cs aplicativo baseado em arquivo. Padrão: Debug. Passe a mesma configuração que a execução usada: uma Directory.Build.props ao lado da .cs pode ser definida WinAppPackageName ou WinAppManifestPath condicionalmente ativada $(Configuration). Aplica-se apenas a uma .cs entrada.
--arch <x64|arm64|x86> – Arquitetura de destino usada ao resolver a identidade de um .cs aplicativo baseado em arquivo. Padrão: a arquitetura do processo atual. Passe a mesma arquitetura que a execução usada, já que a identidade também pode ser desativada $(RuntimeIdentifier). Aplica-se apenas a uma .cs entrada.
-r, --runtime <rid>- Identificador de runtime de .NET de destino (por exemplowin-x64) usado ao resolver a identidade de um .cs aplicativo baseado em arquivo. Somente sua arquitetura é usada e substitui --arch. Aplica-se apenas a uma .cs entrada.
--output-appx-directory <path> - O diretório de layout do AppX do qual o pacote foi registrado. Necessário apenas quando a execução foi usada --output-appx-directory, já que nada nos registros de pacote que executam a opção produziu seu layout.
--json - Formatar saída como JSON

O que faz:

Determina o nome do pacote – da .cs identidade resolvida do arquivo ou lendo o manifesto
Pesquisa pacotes e pacotes {name} (a variante de depuração é criada por {name}.debug)create-debug-identity
Verifica se cada pacote foi registrado no modo de desenvolvimento (IsDevelopmentMode == true)
Verifica se o pacote pertence ao aplicativo que você nomeou (a menos --forceque ) – seu local de instalação deve estar em um diretório que você identificou: a .cs saída de build do próprio arquivo, o diretório do manifesto, o diretório atual ou um explícito --output-appx-directory. Um pacote cujo local de instalação não pode ser resolvido (seus arquivos foram excluídos) é ignorado, pois a identidade por si só não é prova de propriedade: dois aplicativos que ambos definem #:property WinAppPackageName=counter registram a mesma identidade de pastas diferentes. Use --prune para limpar registros cujos arquivos foram removidos.
Cancelar o registro de pacotes correspondentes

Limpeza de registros mortos (--prune):

Um registro sobrevive aos arquivos. Excluir uma saída de build, árvore de projeto ou (para um aplicativo baseado em arquivo) permite que Windows limpo %LOCALAPPDATA%\Tempe o pacote permaneça registrado: Windows mantém a identidade e sua entrada de menu Iniciar, mas a ativação silenciosamente não faz nada. Eles se acumulam de forma 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

Somente registros de modo de desenvolvimento são considerados e cada um é removido pelo nome do pacote completo, portanto, um pacote com o mesmo nome ainda instalado de um local dinâmico não é intocado. O prompt existe porque um local de instalação ausente geralmente é uma pasta excluída, mas também descreve um pacote registrado de um compartilhamento de rede desconectado ou unidade removível – examine 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

Gere, inspecione e instale certificados de desenvolvimento.

Gerar certificado

Gerar certificados de desenvolvimento para assinatura de pacote.

winapp cert generate [options]

Opções:

--manifest <Package.appxmanifest>- Extraia o certificado publisher do manifestoIdentity/@Publisher. Somente o publicador é necessário, portanto, um manifesto parcialmente completo ainda funciona. Se o manifesto não tiver nenhum publicador utilizável, o comando falhará em vez de substituir um padrão, de modo que o certificado nunca poderá incompatível silenciosamente com o manifesto.
--publisher <name>- Publisher para o certificado. Ao gerar um certificado, essa opção tem precedência --manifest; um valor explicitamente vazio falha em vez de usar o publicador de manifesto. Aceita um nome X.500 diferenciado completo (por exemplo, CN=Contoso, O=Contoso Ltd, C=US) ou um nome nu que é automaticamente encapsulado como CN=<name>. Os componentes devem ser de valor único e separados por vírgulas; Não há suporte para RDNs de vários valores (CN=Foo+OU=Bar) e barras invertidas porque o editor de manifesto MSIX não pode representá-los. Um nome diferenciado malformado (por exemplo CN= , ou CN=A,,O=B) é rejeitado com uma saída diferente de zero e um erro nomeando o problema, em vez de produzir um certificado que nunca pode corresponder ao editor de manifesto.
--output <path> - Caminho do arquivo de certificado de saída (dá suporte a caminhos absolutos e relativos)
--password <password> – Senha de certificado (padrão: password, que é conhecido publicamente — consulte a saída JSON e a segurança)
--valid-days <valid-days> - Número de dias em que o certificado é válido (padrão: 365)
--install – Instalar o certificado no repositório de máquinas local após a geração
--if-exists <Error|Overwrite|Skip> - Definir o comportamento se o arquivo de certificado já existir (padrão: Erro)
--export-cer - Exportar um .cer arquivo (somente chave pública) ao lado do .pfx. Útil para distribuir o certificado público separadamente para a instalação de confiança.
--json - Formatar a saída como JSON para consumo programático. Os erros também são retornados como JSON ({"error": "..."}).

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 diferenciado completo ao qual o certificado foi emitido. defaultPasswordIsPublic está sempre presente. Quando estiver true, a .pfx senha é protegida por qualquer pessoa pode adivinhar, portanto, o certificado só deve assinar builds que permanecem em seus próprios computadores – verifique-o antes que um script entregue o certificado para qualquer outra coisa. warnings carrega a mesma divulgação que o texto e é omitida quando não há nada a relatar. publicCertificatePath aparece apenas com --export-cer.

Informações de certificado

Exiba os detalhes do certificado de um arquivo PFX ou CER. Útil para verificar se um certificado corresponde ao manifesto antes de assinar.

winapp cert info <cert-path> [options]

Argumentos:

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

Opções:

--password <password> - Senha do arquivo PFX, ignorada para um CER público (padrão: "senha")
--json - Formatar saída como JSON

Instalação do certificado

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

winapp cert install <cert-path> [options]

Argumentos:

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

Exemplos:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

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

assinar

Assinar pacotes MSIX e executáveis com certificados.

winapp sign <file-path> <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> - Senha de certificado (padrão: "senha")
--timestamp <url> - URL do servidor de carimbo de data/hora 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

Assinar um arquivo (exe, MSIX ou pacote MSIX) usando Assinatura Confiável do Azure — uma identidade de assinatura gerenciada pela nuvem, portanto, nenhuma chave privada (PFX) nunca reside no computador local.

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

Argumentos:

file-path - Caminho para o arquivo a ser assinado (exe, msix ou msixbundle)

Opções:

--subscription, -s - Azure ID da assinatura a ser usada. Se não for fornecido e várias assinaturas existirem, você será solicitado
--resource-group, -r – Grupo de recursos para restringir contas de assinatura
--account - Nome da conta de assinatura. 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 diretamente. Uma credencial de Azure não interativa já deve estar disponível; a CLI pode voltar para um prompt de locatário interativo ouaz login, mas a API programática do npm é sempre não interativa e falha em vez de solicitar

Autenticação:

az-signusa a cadeia de credenciais padrão do Azure (DefaultAzureCredential). Para CI/CD, defina AZURE_TENANT_IDe AZURE_CLIENT_IDAZURE_CLIENT_SECRET (ou use GitHub Actions OIDC/identidade gerenciada). Uma sessão de CLI do Azure existente (az loginincluindo a azure/login Ação GitHub) também é respeitada em qualquer ambiente. Somente quando nenhuma credenciais for encontrada e a sessão for interativa será az-sign iniciada az login para você.

Pré-requisitos:

Uma conta de Assinatura de Código Azure e um perfil de certificado (criado no portal Azure após a validação de identidade), além da função de Signatário de Perfil de Certificado de Assinatura de Código atribuída à sua identidade. Para obter mais diretrizes, visite Azure documentos de início rápido da Assinatura de Artefatos.
Um runtime x64 de todo o computador .NET 8 (ou posterior) instalado. A biblioteca de clientes de assinatura Azure é um assembly gerenciado que signtool.exe é carregado em um processo separado; o runtime autocontido do winapp não o satisfaz. Instale-o https://dotnet.microsoft.com/download se a assinatura falhar com um erro de carregamento de runtime.
O Microsoft Visual C++ Redistribuível (x64). A biblioteca de clientes de assinatura Azure depende do runtime vc++ e, como o winapp baixa o pacote NuGet bruto em vez do instalador oficial de ferramentas do cliente, essa dependência não é instalada automaticamente. Um computador limpo pode falhar mesmo com .NET e SignTool presentes. Instale o redistribuível x64 mais recente de https://aka.ms/vs/17/release/vc_redist.x64.exe se a assinatura falhar com um 0xc000007berro "O aplicativo não pôde iniciar corretamente" ou um erro de DLL ausente do dlib.

CI de privilégio mínimo: A descoberta automática (listando assinaturas, grupos de recursos, contas e perfis) precisa de acesso de leitura em um escopo pai. Para evitar cada chamada de listagem de coleção, passe todos os quatro de --subscription, --resource-group--accounte --profile: az-sign em seguida, valida a conta e o perfil com leituras de recursos diretos (um GET em cada recurso nomeado) em vez de enumerar a coleção pai, portanto, uma entidade de segurança com escopo apenas para essa conta e perfil é suficiente. Omitir qualquer uma delas introduz novamente uma chamada de listagem – por exemplo, deixar de fora --subscription faz az-sign a lista das assinaturas que sua identidade pode acessar – o que uma entidade de segurança com escopo estreito pode não ter permissão para fazer. Uma entidade de segurança com escopo apenas para um único perfil de certificado pode ignorar totalmente a validação passando um pré-gerado --metadata-file (que especifica diretamente o ponto de extremidade e o perfil da conta).

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

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

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

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

Argumentos:

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

Opções:

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

O que faz:

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

Exemplos:

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

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

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

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

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

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

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

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

Quando usar:

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

winapp manifest generate --template sparse — Criar um manifesto esparso com AllowExternalContent
winapp create-external-catalog ./bin — Gerar o catálogo de integridade de código para os executáveis do aplicativo
winapp pack — Empacotar o manifesto, os ativos e o catálogo em um MSIX

ferramenta

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

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

Ferramentas disponíveis:

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

Exemplos:

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

Verificação de assinatura

As ferramentas de build são baixadas do NuGet e executadas, portanto, o winapp verifica cada uma delas para obter uma assinatura válida Microsoft Authenticode imediatamente antes de executá-la. O certificado deve nomear Microsoft Corporation como a organização de assinatura. Isso se aplica a todos os comandos que desembolsam para uma ferramenta do SDK, incluindo tool, packagee sign. Uma ferramenta que falha na 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 arquivo no disco não é o que Microsoft publicado — geralmente um download corrompido ou parcial. Exclua o pacote do cache NuGet e execute o comando novamente para que o winapp o baixe novamente.

Em seguida, o winapp mantém a ferramenta aberta enquanto ela for executada, portanto, o arquivo verificado é o arquivo Windows carrega. Se não puder manter a ferramenta no lugar, ela também não será executada:

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

Feche o que estiver usando o arquivo – uma verificação antivírus ou um editor aberto é a causa usual – e execute o comando novamente. Se a ferramenta não estiver em uso, exclua o pacote do cache NuGet para que o winapp o baixe novamente.

armazenar

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

winapp store [args...]

Argumentos:

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

O que faz:

Garante que a CLI do Desenvolvedor do Microsoft Store (msstore) esteja baixada e disponível em seu sistema.
Encaminha todos os argumentos para a msstore CLI.
Executa o comando mostrando a saída diretamente no terminal.

Exemplos:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Obter caminhos para componentes do SDK do Windows instalados.

winapp get-winapp-path [options]

O que ele retorna:

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

destino

Execute comandos, copie arquivos, inspecione o estado ou capture toda a área de trabalho convidada.

Cada verbo usa sandbox como seu primeiro argumento. Com exceção snapshot, esses comandos podem preparar ou iniciar a Área Restrita. Consulte Windows execução de área restrita para pré-requisitos, permissões, ciclo de vida e recuperação.

exec de destino

Execute um comando como o usuário convidado.

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

Argumentos após -- manter 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 de winapp no stderr sem alterar o stdout do comando filho. Use o estruturado error.code para distinguir uma falha de destino do status de saída de um aplicativo.

Um explícito WINAPP_UI_WORKFLOW_ID também agrupa chamadas de interface do usuário convidadas feitas pelo comando; consulte a coordenação da interface do usuário da área restrita.

push de destino e pull de destino

Copie um arquivo 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 de destino são relativos à área de trabalho gerenciada do destino; os caminhos de destino absoluto, raiz e UNC são rejeitados. Um destino de arquivo inclui seu nome de arquivo. Consulte Executar comandos e copiar arquivos para layout de diretório, manipulação de link e execução de um script copiado.

instantâneo de destino

Relatar preparação, implantações e janelas de convidado sem iniciar uma área restrita.

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

Ele não reconecta um cliente nem repara um agente. Nenhuma área restrita em execução é um resultado bem-sucedido, não um erro. Consulte Inspecionar a Área Restrita para interpretar IDs de preparação e processo.

captura de tela de destino

Capture a área de trabalho convidada em seu tamanho de pixel nativo como um PNG de host, sem um seletor de aplicativo ou bordas da janela do host. --json relata a origem da coordenada de convidado.

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

Em vez disso, use ui screenshot --on sandbox -a <app> para uma janela do aplicativo. Confira capturas de tela e gravações para requisitos de cliente, limitações de foco e manipulação de saída.

registro de destino

Registre a área de trabalho convidada no H.264 MP4. Arquivos de vídeo e quadro do host chegam após a conclusão da gravação; JSON e o manifesto do quadro descrevem qualquer dimensionamento ou preenchimento.

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

Usa as opções de duração, quadro, substituição e resultado, mas captura a área de ui recordtrabalho em vez de um aplicativo. Prefira um positivo --duration-sec para uso da CLI autônoma; o auxiliar npm requer durationSec. Consulte a captura de área restrita para obter evidências parciais e falhas de preparação para captura.

find-ui

Agente primeiro. find-ui é criado principalmente para agentes de codificação de IA – permite que um agente efetue pull real, compilando a marcação WinUI das galerias de envio em vez de inventá-la e --json torna todos os resultados (e todas as falhas) legíveis pelo computador. Ele funciona tão bem digitado à mão.

Pesquise controles e exemplos do WinUI para obter um exemplo de código de trabalho. Somente WinUI: o corpus é a Galeria WinUI 3 e o Kit de Ferramentas da Comunidade Windows (além de alguns padrões principais coletados) — ele não abrange WPF, WinForms ou outras estruturas de interface do usuário. Uma terceira origem, a ReactorGallery microsoft-ui-reactor, é aceita: ela é excluída de uma pesquisa normal e pesquisada somente quando você passa --source reactor (suas amostras declarativas somente C#não colam em um aplicativo XAML padrão, portanto, alcance-a somente ao criar um projeto de Reator/MVU).

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

A Galeria, o Kit de Ferramentas e o Reator são enviados corporativos dentro da CLI, portanto find-ui , funciona sem acesso à rede, inclusive em uma primeira execução em uma área restrita do agente ou atrás de um proxy corporativo que bloqueia raw.githubusercontent.com. Quando GitHub é acessível, a CLI é atualizada e armazena em cache o resultado por usuário<global .winapp>/cache/find-ui; o corpus interno é apenas um piso, nunca um teto. Os dados armazenados em cache são atualizados no máximo a cada 24 horas ou sob demanda com --refresh.

O corpus interno é rebuscado de GitHub sempre que uma versão estável é criada e uma atualização que falha interrompe a compilação de lançamento em vez de enviar dados mais antigos silenciosamente – o padeiro busca pelo mesmo caminho --refresh de código usado, portanto, uma falha significa que a atualização ao vivo também é interrompida e vale a pena investigar antes do envio. Uma liberação ainda pode ser cortada contra o corpus confirmado anteriormente, mas apenas como uma substituição explícita. Quando os resultados são atendidos a partir da cópia interna da corporação galeria/kit de ferramentas/reator, find-ui diz isso em stderr e --json saída carrega "corpus": "embedded" (outros valores: "network" para uma busca nova, "cache" para o cache local). Uma solicitação somente de núcleo – --source coreou um --id conjunto que é todos os padrões principais – relata "embedded" também, porque os padrões de núcleo coletados são compilados na CLI e nunca buscados; ele não imprime nenhum aviso de desatualização, pois --refresh não pode alterá-los. O corpus campo é relatado sempre que os resultados foram atendidos; ele está ausente somente quando nenhum corpus pode ser carregado.

Opções:

--id <id> - Buscar o código (XAML de retorno da Galeria/Toolkit e/ou C#; Reator é somente C#) mais notas de pré-requisito para uma ou mais IDs de cenário de uma pesquisa anterior (por exemplo gallery-tabview-1). Repetível. As IDs não diferenciam maiúsculas de minúsculas — GALLERY-TABVIEW-1 resolve o mesmo que gallery-tabview-1.
--list - Listar cada ID de exemplo/controle detectável em vez de pesquisar (Galeria + Kit de Ferramentas + núcleo; a origem do Reator opt-in é excluída).
--source <gallery|toolkit|reactor|core> – Restringir os resultados da pesquisa a uma única origem. (Somente pesquisa — não é válido com --list/--id.) O reator é opt-in – ele é excluído de uma pesquisa normal, portanto --source reactor , é a única maneira de pesquisá-lo.
--max <N> - Número máximo de controles correspondentes a serem retornados (padrão: 3). Aplica-se somente à pesquisa; ignorado com --list/--id.
--refresh- Ignorar o cache local e buscar novamente o corpus winui de GitHub.
--json - Emite JSON estruturado (amigável ao agente). Para pesquisa, cada correspondência carrega source, control, score, descriptione uma scenarios matriz cujas entradas contêm o 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 simples {"error": "..."} no stdout com um código de saída diferente de zero, portanto, a saída permanece legível pelo computador.

Fluxo de trabalho: pesquise compactamente para encontrar o controle certo e suas IDs de cenário e, em seguida, busque o código completo para obter 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; use find-api para pesquisar na superfície da API (tipos, membros, enumes) referências de projeto e winapp ui search pesquisar a árvore de interface do usuário de um aplicativo em execução .

find-api

Agente primeiro. find-api é criado principalmente para agentes de codificação de IA – ele fundamenta o código gerado na superfície da API que um projeto realmente faz referência em vez da lembrança do modelo e, --json além de códigos de saída não zero em símbolos ausentes, permitem que um codegen de porta do agente na resposta. Ele funciona tão bem digitado à mão.

Pesquise e inspecione a superfície da API Windows/WinRT (tipos, membros, enumes, namespaces) disponíveis para um projeto, resolvida a partir de seus metadados referenciados.winmd/.dll. O formulário nu pesquisa; subvérbos detalham um tipo específico, namespace ou o próprio índice.

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

O índice é compilado a partir dos pacotes NuGet/SDK restaurados do projeto (via project.assets.json) no primeiro uso e atualizado automaticamente quando o projeto é restaurado. Ele reside no cache global .winapp (cache/find-api/) e é compartilhado entre projetos. Restaure o projeto primeiro (winapp restore ou dotnet restore).

Cada correspondência é listada em seu namespace com o pacote que o envia e um resumo de uma linha do que ele faz, portanto, um resultado é utilizável sem 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 para imprimir o arquivo de cache no disco que faz backup de cada namespace, o que é útil ao diagnosticar um índice obsoleto ou inesperado.

Executar winapp find-api sem nenhuma consulta imprime um breve resumo de uso e sai 0 – é um pedido de ajuda, não uma pesquisa que não encontrou nada.

Escopos. Cada resposta vem exatamente de um escopo, relatado como scope dentro --json e como uma observação na saída de texto:

project – o projeto no diretório atual (ou --project / --project-dir). Abrange o SDK Windows, o SDK do Aplicativo Windows e os próprios pacotes NuGet do projeto. O SDK do Aplicativo Windows metadados é a versão que o projeto faz referência: se o computador tiver um runtime aplicativo do Windows mais recente instalado, find-api avisará e o deixará de fora em vez de confirmar tipos nos quais o projeto não pode compilar.
sdk– o SDK do Windows de todo o computador + metadados SDK do Aplicativo Windows, usados automaticamente quando o diretório atual não contém nenhum projeto e nenhuma solução. Isso torna find-api utilizável para explorar APIs antes que qualquer projeto exista e não precise de acesso à rede. Ele deliberadamente não inclui pacotes NuGet de terceiros, portanto, um tipo do (digamos) Kit de Ferramentas da Comunidade não será encontrado nesse escopo.

Uma consulta de um diretório sem projeto e nenhuma solução é sempre respondida pelo sdk escopo - nunca por qualquer projeto que seja indexado no cache compartilhado - portanto, os resultados nunca dependem do estado global não relacionado. Passe --project sdk para selecionar o escopo do SDK explicitamente de dentro de um projeto e winapp find-api refresh --project sdk recompilá-lo depois de instalar um novo SDK Windows.

Diretórios de solução. Em um diretório que contém um .sln/.slnx arquivo sem projeto ao lado dele, os projetos que a solução cria respondem em vez do sdk escopo – eles são indexados sob demanda, para que seus pacotes NuGet sejam incluídos. Quando a solução cria mais de um projeto indexado, a consulta os lista e solicita --project <name> em vez de escolher um.

Comandos:

(bare)find-api "<query>" ["<query>"...] - Tipo de pesquisa e nomes de membro, voltando aos resumos documentados, agrupados por namespace
members <type> [<type>...] [--filter <text>] - Listar propriedades, eventos e métodos de um tipo (membros declarados com assinaturas, membros herdados resumidos declarando o tipo)
check-property <type> <property> [<property>...] - As propriedades de validação existem em um tipo (sai diferente de zero se alguma estiver ausente). Uma propriedade somente leitura é relatada com ️ e "somente leitura, não pode ser atribuída" em vez de uma simples✅, portanto, uma propriedade como ActualWidth não é confundida com ⚠algo que você pode definir. Os nomes de propriedade são correspondentes caso a caso, porque C# e XAML são: check-property Button background sai de fora de zero e oferece Background como uma correspondência próxima em vez de relatar um nome que você não pode realmente gravar.
enums <type> [<type>...] [--filter <text>] - Listar os valores de um enum (sai diferente de zero quando o tipo não é um enumeração)
packages - Listar os pacotes de metadados indexados, com contagens de tipo/membro por pacote
stats - Mostrar estatísticas de índice agregado (pacotes, namespaces, tipos, membros, .winmd arquivos)
refresh [--scan] - Recompilar o índice de um projeto (--scan indexa cada projeto no diretório). Com --project <name>, um nome que corresponde a nenhum projeto indexado único falha em vez de indexar o diretório atual.

Batching.search, members, enumse check-property aceite vários assuntos em uma invocação. Para um agente de IA, essa é a maior alavanca de custo: o custo marginal de uma pesquisa é dominado pela viagem de ida e volta (cada chamada envia novamente toda a conversa), não pelo tamanho da carga, portanto, uma chamada que responde a dez perguntas é muito mais barata do que dez chamadas.

Um único assunto retorna exatamente a forma de conteúdo que sempre tem, tanto no texto --jsonquanto em .
Dois ou mais sujeitos retornam um envelope – { "count": N, "results": [ ... ] } em --json, com cada elemento sendo o conteúdo normal de assunto único; check-property adiciona missingCount. A saída de texto renderiza cada assunto em sequência em um cabeçalho de escopo.
check-property lotes propriedades em um tipo: o primeiro argumento é o tipo, cada argumento depois que ele é uma propriedade. No modo de lote, uma propriedade que existe imprime uma única ✅ linha; os detalhes de quase-erro completos são impressos apenas para os que não o fazem.
Um lote é encerrado 0 somente se cada assunto foi resolvido e encontrado, portanto, um lote ainda é seguro para o codegen em portão.

Classificação de pesquisa. Uma consulta que corresponde exatamente a um nome de tipo é classificada à frente de correspondências parciais e, quando um nome curto é compartilhado por vários namespaces, apenas as colisões de nome exato são listadas como ambíguas , uma consulta como NavigationView relata o punhado de namespaces que definem esse tipo exato em vez de cada namespace que contém um símbolo de nome semelhante. A lista de ambiguidade obedece --maxe os resultados normais ainda são impressos abaixo dela.

Digite names.members, check-propertye enums aceite um nome curto (NavigationView) ou um totalmente qualificado (Microsoft.UI.Xaml.Controls.NavigationView). Quando um nome curto é compartilhado por um tipo moderno Microsoft.* e seu gêmeo UWP herdadoWindows.*, o Microsoft.* tipo responde – que é a projeção que um aplicativo SDK do Aplicativo Windows usa – e o nome totalmente qualificado resolvido sempre é mostrado. Qualquer outra colisão sai fora de zero e lista os candidatos em vez de adivinhar.

Assinaturas de método. Uma assinatura é impressa da maneira como você escreveria a chamada: um método que você chama no tipo em vez de em uma instância é mostrado com static, e um parâmetro por referência é mostrado com a palavra-chave de que ele realmente precisa — outou inref. Assim TryGetValue , lê Boolean TryGetValue(String key, out String value), que é compilado como escrito.

Opções:

--max <n> - Número máximo de resultados de pesquisa agrupados em namespace (padrão 5; somente pesquisa). Também limita a lista de ambiguidades, portanto, uma consulta curta que colide entre muitos namespaces permanece legível.
--filter <text> - Restringir uma listagem members e enums: uma subcadeia de caracteres que não diferencia maiúsculas de minúsculas no nome do membro/valor. Melhor usado em tipos com centenas de membros. A maioria das enumerações é pequena o suficiente para despejar inteiro (mesmo Symbol, o maior em WinUI em valores de 197), portanto, filtrar-los geralmente custa mais do que economiza quando você leva em conta um segundo palpite. Nunca execute novamente o mesmo comando com texto de filtro diferente – despejo uma vez e leia-o.
--all - On members, liste a superfície completa: assinaturas completas para membros herdados, mais estáticas de identificador de propriedade de dependência e descrições por membro, todas as quais uma listagem não filtrada omite (consulte o tamanho da listagem abaixo). --verbose implica isso; use --all quando você também quiser --json, que não pode ser combinado com --verbose.
--scan - Descubra e indexe cada projeto de forma recursiva no diretório (refresh somente)
--project <name>- Project consultar (corresponde ao .csproj/.vcxproj nome) ou sdk consultar o escopo do SDK de todo o computador Windows
--project-dir <path>- Project diretório a ser consultado (padrão para o diretório atual). Um caminho que não existe é um erro– ele nunca é respondido silenciosamente do sdk escopo.
--json - Emita um conteúdo legível por computador no stdout (com suporte de cada verbo). As cargas de consulta identificam o índice que respondeu por meio scope de (project ou sdk), projectNamee projectDir (ausente para o escopo do SDK) – os nomes de projeto não são exclusivos entre diretórios, assim projectDir como a identidade confiável. Em --jsoncada falha , incluindo erros de argumento/analisador, como um não inteiro --max , é emitido como um objeto simples {"error": "..."} no stdout com um código de saída diferente de zero, portanto, a saída permanece legível pelo computador.

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 ainda relata o total não filtrado (totalValuesoutotalEvents//totalPropertiestotalMethods em --json), portanto, uma exibição estreita nunca é confundida com uma API pequena. Um filtro que corresponde a nada ainda sai 0 e diz de forma tão explícita que "nada corresponde ao filtro", não "nenhum tipo desse tipo".

Tamanho da listagem. Uma listagem não filtrada members é a única forma cara – members Button abrange 288 membros, dos quais 280 são herdados de seis tipos base. Uma chamada não filtrada é uma consulta de orientação ("o que é esse tipo, aproximadamente o que ela pode fazer?"), portanto, ela responde a isso e omite as partes das quais nada é escrito:

Assinaturas de membro herdadas – os membros herdados são agrupados declarando o tipo e listados apenas pelo nome, portanto, a forma da superfície herdada ainda está visível sem 280 assinaturas completas.
Estática do identificador de propriedade de dependência (BackgroundProperty) – 28% das propriedades de um controle WinUI típico. Eles existem para serem passados, GetValue/SetValuenão atribuídos.
Descrições por membro – a prosa XML-doc, cerca de 16% do conteúdo.
Campos implícitos por seus arredores em --json: kind (implícito pela matriz que//methodseventsproperties contém), returnType (o token principal de signature) e inherited quando falso (implícito por ).declaringType

O que foi omitido sempre é relatado (hiddenDependencyPropertiesdescriptionsOmittede uma hint linha "--jsonOmitida:" no texto) e os totais ainda descrevem todo o tipo. Ambos --filter e --all veja a superfície completa com assinaturas e descrições completas, portanto members Button --filter BackgroundProperty , ainda encontra o identificador e members Button --filter Click ainda retorna Clicka assinatura herdada. Medida em samples/winui-app, isso leva members Button --json de 91.954 a 10.567 caracteres (-88,5%) ao sair --filter e --all bytes idênticos.

Como uma consulta é correspondida. winapp find-api "language model" classifica acima correspondências LanguageModel cujas palavras estão espalhadas entre namespaces e membros, incluindo fora de um projeto quando o tipo é indexado. A pesquisa é lexical, não semântica: corresponde a palavras de identificador inteiro em vez de qualquer execução de letras, então llm localiza IImageLLMAdapterSession , mas não ScrollMode. Quando uma consulta não corresponde a nenhum nome, ela é tentada em relação aos resumos documentados de tipos e membros "random-access stream" , que é o que permite localizar IRandomAccessStream. As descrições estão abaixo de cada correspondência 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 nenhum texto de descrição.

Projetos sem um arquivo de projeto do MSBuild. Um aplicativo Electron (ou qualquer outro aplicativo não .NET controlado porwinapp.yaml) não tem nenhum .csproj e, portanto, nenhum project.assets.json. find-api o indexa do .winapp/winmds.lock.json que winapp restore grava, que registra a mesma coisa: cada pacote resolvido, sua versão e os .winmd arquivos que ele contribui. Esse projeto tem o nome de seu diretório e seu índice fica obsoleto quando o arquivo de bloqueio é reescrito. Um diretório que contém um .csproj e um winapp.yaml é indexado do .csproj, que é a descrição mais precisa do que o projeto compila.

As respostas negativas são qualificadas quando o índice está incompleto. Se os metadados de um pacote não puderam ser lidos, "nenhum tipo desse tipo" e "esse pacote nunca foi indexado" parecem idênticos e agindo no primeiro quando é realmente o segundo gera código em uma API que você foi informado que não existe. Portanto, cada resposta negativa, incluindo uma search que retorna resultados zero, carrega uma observação de que o índice é parcial e aponta para winapp find-api refresh. Respostas positivas não são afetadas.

Nomes de tipo genéricos. Os metadados armazenam tipos genéricos com um sufixo arity (IAsyncOperation`1), que não é como alguém os grava. members, enumse check-property aceite todos os formulários: IAsyncOperation, IAsyncOperation<StorageFile>e IAsyncOperation`1 todos resolvam para o mesmo tipo. Um nome nu corresponde a qualquer aridade; um arity declarado (em qualquer notação) deve corresponder, portanto Holder<A, B> , não será resolvido para um único parâmetro Holder<T>.

--json cargas omitem diagnósticos. Os caminhos de arquivo de cache aparecem somente em --verbose (saída de texto correspondente, em que já eram somente detalhados) e matrizes de sugestão vazias são omitidas em vez de serializadas como [].

Códigos de saída:search sem ocorrências, check-property em uma propriedade ausente e enums em um tipo não enumerado, todos saem fora de zero – a geração de código de portão e a CI as verificam. Uma invocação em lote sairá fora de zero se algum assunto falhar. Uma propriedade somente leitura não é uma falha – ela existe, portanto check-property , sai 0 e sinaliza-a na saída (writable: false em --json). Uma init propriedade relata writable: false pelo mesmo motivo: ela pode ser definida em um inicializador de objeto, e sua assinatura diz { get; init; }, mas atribuí-la posteriormente não é compilada.

Relacionado:find-api responde "essa API existe e quais são seus membros?"; use find-ui para encontrar um exemplo de WinUI funcionando para um controle.

node generate-bindings

(Disponível somente no pacote NPM) Gere associações JS para APIs de SDK do Aplicativo Windows. As associações são declaradas por um "winapp": { "jsBindings": {...} } namespace e gravadas package.jsonem .winapp/bindings/ .

npx winapp node generate-bindings [options]

Opções:

--verbose, -v – Habilitar a saída detalhada de codegen por arquivo
--quiet, -q – Suprimir o progresso e a saída informativa

O que faz:

Lê o winapp.jsBindings bloco de package.json e o winmds.lock.json escrito pelo último winapp restore, em seguida, emite associações digitada .js + .d.ts em .winapp/bindings/
Não modificapackage.json – é um regenerador passivo. Adicionar o winapp.jsBindings bloco e a dependência de @microsoft/dynwinrt runtime acontece durante winapp init quando as associações JS estão habilitadas; esse comando falha rapidamente se o bloco estiver ausente
Avisa (mas não grava) se @microsoft/dynwinrt estiver ausente de suas dependências — execute npm install depois init de adição

Observação

As associações são somente npm – elas exigem invocação por meio npx winapp (do @microsoft/winappcli pacote npm); a CLI do winget autônomo não as apresenta. Execute winapp init interativamente e opte por entrar ou usar winapp init . --use-defaults --add-js-bindingsantes de usar esse comando para regenerar associações. Se você editarwinapp.yaml, execute npx winapp restore para atualizar Windows dependências 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 associaçõ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 somente no pacote NPM) Gerar modelos de complemento C++ ou C# nativos com Windows SDK e integração SDK do Aplicativo Windows.

npx winapp node create-addon [options]

Opções:

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

O que faz:

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

Exemplos:

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

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

node add-electron-debug-identity

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

Importante

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

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

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

Opções:

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

O que faz:

Registra a identidade de depuração para electron.exe processo
Habilita o teste de APIs que exigem identidade no desenvolvimento do Electron
Usa Package.appxmanifest existente para configuração de identidade

Exemplos:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node clear-electron-debug-identity

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

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

Opções:

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

O que faz:

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

Exemplos:

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

Opções globais

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

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

Diretório de Cache Global

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

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

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

No cmd:

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

No PowerShell e pwsh:

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

O Winapp criará esse diretório automaticamente quando você executar comandos como init ou restore.

Atualizar verificações

A CLI do winapp verifica periodicamente novas versões e exibe um aviso de uma linha quando uma atualização está disponível. Essa verificação é executada em segundo plano e não adiciona latência aos comandos.

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

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

No cmd:

set WINAPP_CLI_UPDATE_CHECK=0

No PowerShell e pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Para tornar isso permanente:

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

Identidade do fluxo de trabalho da interface do usuário

winapp ui os comandos que conduzem a área de trabalho física sempre têm turnos cooperativos, portanto, dois fluxos de trabalho em execução ao mesmo tempo não podem roubar o foco um do outro ou ignorar os menus uns dos outros. Essa arbitragem não precisa de nenhuma configuração e não pode ser desativada.

O que é opcional é a continuidade. Por padrão, cada comando é um tiro único autocontido que libera a área de trabalho assim que ela é concluída. Para manter a área de trabalho em vários comandos, forneça a eles todas as mesmas IDs de fluxo de trabalho:

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

Use o mesmo valor para processos de cooperação (por exemplo, uma gravação e os cliques que ele deve capturar) e valores diferentes para fluxos de trabalho independentes. Cada comando sem uma ID é seu próprio fluxo de trabalho de um tiro, mesmo quando vários são iniciados de um shell, portanto, os hosts que iniciam um novo shell por comando devem injetar o mesmo valor explícito em cada um deles. O valor é opaco, nunca é tratado como uma credencial e só é persistente como um hash SHA-256. Consulte Automação da Interface do Usuário → Coordenando fluxos de trabalho de interface do usuário simultâneos.

ui

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

winapp ui [command] [options]

Comandos:

status – Conectar-se ao aplicativo e mostrar informações
inspect - Exibir árvore de elementos
search - Localizar elementos por seletor
get-property – Ler propriedades do elemento
get-text / get-value - Ler valor/texto do elemento (TextPattern, ValuePattern ou Name)
screenshot - Capturar janela/elemento como PNG (várias janelas formam um PNG composto rotulado; consulte o escopo da captura)
record- Gravar uma região de janela/elemento em um vídeo do H.264 MP4 (Windows Graphics Capture + Media Foundation)
invoke - Ativar elemento (clique, alterne, expanda)
click - Clique no elemento por meio da simulação do mouse (para controles que não dão suporte à invocação)
hover - Mover o mouse para o elemento para disparar dicas de ferramenta, submenus e estados de foco (habitação padrão: 800ms)
drag - Arraste o mouse de um ponto para outro, por seletor de elemento ou coordenadas de tela x,y (reordenar, redimensionar, controles deslizantes, arrastar e soltar)
touch- Injetar gestos de toque sintético (toque, toque duplo, pressionar longamente, deslizar o dedo, pinçar, alongar) em um centro de elementos ou coordenadas de tela x,y
pen – Injetar entrada de caneta/caneta sintética — toques e traços de tinta com pressão configurável, inclinação e modo de borracha
send-keys - Enviar entrada de teclado sintético (teclas nomeadas, combinações, vk=0xNN bruto ou texto literal) para uma janela
set-value - Definir valor no elemento editável (texto, número); volta para LegacyIAccessible put_accValue para controles de edição avançada somente TextPattern
focus – Mover o foco do teclado
scroll-into-view - Elemento scroll visível
wait-for - Aguarde o estado do elemento
list-windows - Listar todas as janelas de um aplicativo
get-focused - Relatar o elemento focado no momento
yield – Liberar a volta da interface do usuário do fluxo de trabalho atual; requer WINAPP_UI_WORKFLOW_ID

Opções:

-a, --app <app> - Aplicativo de destino (nome, título ou PID)
-w, --window <hwnd> - Janela de destino por HWND (estável)
--on <target> - Execute qualquer ui verbo em sandbox; nomes, PIDs e identificadores de janela referem-se ao convidado. As saídas são entregues ao host. Consulte a automação da interface do usuário da área restrita para obter configuração, coordenação de fluxo de trabalho e requisitos de cliente.

registro de interface do usuário

Registre uma janela ou região de elemento em um H.264 MP4.

# 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 registro:

--duration-sec <n> - Comprimento da gravação em segundos. 0 registros até Ctrl+C (padrão 0).
--fps <n> - Quadros por segundo a serem capturados (padrão 15).
--max-edge <px> - Escala de downscale para que a borda mais longa seja, no máximo, tantos pixels (0 = nenhuma escala de downscale).
--capture-screen - Captura da tela para que as sobreposições/pop-ups sejam incluídas (podem capturar janelas ocluding).
-o, --output <path> - Caminho de saída .mp4 (padrão para recording-<timestamp>-<guid>.mp4).
--overwrite - Substitua as saídas de gravação existentes após a conclusão da nova tomada; as saídas existentes são rejeitadas por padrão. Os pacotes de quadros anteriores são mantidos. Consulte a recuperação de saída de gravação.
--frames - Gravar JPEGs com carimbo de frames.ndjsondata/hora e manifest.json para <output-name>.frames. Dá suporte a 1-30 fps e --max-edge 64-4096 (padrão 1280), com um limite de dados de quadro de 1 GiB.

Com --json, o resultado final inclui o caminho de saída, dimensões, codec, modo de captura, cadência, motivo de parada, opcional frameArtifactse avisos.

Limitação conhecida: gravar um elemento específico dentro de um pop-up que renderiza em sua própria janela de nível superior (submenu WinUI/XAML, dica de ensino, dica de ferramenta) pode capturar a janela principal subjacente. Registre a janela inteira ou siga o fluxo de trabalho de sobreposição de captura de tela para imagens pop-up. Rastreado no nº 646.

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

Comentários

Esta página foi útil?

Last updated on 2026-10-03

Documentação e uso da CLI

Conclusão do shell

Iniciar

novo

restauração

atualização

pacote

Empacotando um projeto diretamente

Pacotes de identidade esparsos

Descoberta de componente do WinRT

Pacotes de várias arquiteturas

create-debug-identity

Inserção de identidade

manifesto

geração de manifesto

Marcadores de posição de manifesto

suplemento de manifesto

manifest atualizar-recursos

execução

modo Project (.NET projetos do SDK)

Modo de arquivo único (.NET aplicativos baseados em arquivo)

Capabilities

Traga seu próprio manifesto

Executando com dotnet run

Unregister

cert

Gerar certificado

Informações de certificado

Instalação do certificado

assinar

az-sign

create-external-catalog

ferramenta

armazenar

get-winapp-path

destino

exec de destino

push de destino e pull de destino

instantâneo de destino

captura de tela de destino

registro de destino

find-ui

find-api

node generate-bindings

node create-addon

node add-electron-debug-identity

node clear-electron-debug-identity

Opções globais

Diretório de Cache Global

Atualizar verificações

Identidade do fluxo de trabalho da interface do usuário

ui

registro de interface do usuário

Comentários

Recursos adicionais

Executando com `dotnet run`