Documentazione e utilizzo dell'interfaccia della riga di comando

Completamento shell

Abilitare il completamento tramite tabulazione per comandi, opzioni e valori. Per istruzioni sull'installazione, vedere la guida al completamento della shell .

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

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

Init

Inizializzare una directory con Windows SDK, SDK per app di Windows e asset necessari per lo sviluppo di Windows moderno.

winapp init [base-directory] [options]

Argomenti:

• base-directory - Directory di base/radice per l'app/area di lavoro (impostazione predefinita: directory corrente)

Opzioni:

• --config-dir <path> - Directory per la configurazione di lettura/archiviazione (impostazione predefinita: directory corrente)
• --setup-sdks - Modalità di installazione dell'SDK: 'stable' (impostazione predefinita), 'preview', 'experimental' o 'none' (ignorare l'installazione dell'SDK)
• --ignore-config, --no-config - Non usare il file di configurazione per la gestione delle versioni
• --no-gitignore - Non aggiornare il file con estensione gitignore
• --use-defaults, - --no-prompt Non richiedere e usare il valore predefinito di tutte le richieste
• --config-only - Gestire solo le operazioni dei file di configurazione, ignorare l'installazione del pacchetto
• --exe <path> - Percorso dell'eseguibile dell'applicazione. Richiede --sparse. Genera un manifesto sparse solo identità per l'exe invece di un pacchetto completo/installazione dell'SDK.
• --sparse - Generare un manifesto dell'identità sparse (appxmanifest.xml) per un exe desktop esistente. Ignora l'installazione di SDK/pacchetto. Usare con --exe.
• --name <name> - Eseguire l'override del nome del pacchetto (solo sparse; impostazione predefinita: dedotto dall'exe)
• --publisher <CN> - Eseguire l'override del nome comune dell'editore (solo sparse; impostazione predefinita: dedotto dal nome della società dell'exe)
• --output-dir <path> - Directory per scrivere il manifesto di tipo sparse e Assets/ (solo sparse; impostazione predefinita: una sparse/ cartella nella directory corrente)
• --force - Sovrascrivere un esistente appxmanifest.xml nella directory di destinazione (solo sparse). Senza di esso, init non riesce invece di sostituire un manifesto/asset esistente.
• --add-js-bindings (solo npm) - Aggiungi winapp.jsBindings a package.json e genera associazioni JS/TypeScript, senza chiedere conferma (incompatibile con --setup-sdks none)

Risultato:

• Crea winapp.yaml il file di configurazione (solo quando i pacchetti SDK vengono gestiti; ignorati con --setup-sdks none)
• Scarica i pacchetti di Windows SDK e SDK per app di Windows
• Genera intestazioni e file binari C++/WinRT
• Crea Package.appxmanifest
• Configura gli strumenti di compilazione e abilita la modalità sviluppatore
• Aggiorna .gitignore per escludere i file generati
• Archivia i file condivisibili nella directory della cache globale
• Genera associazioni JS per le API SDK per app di Windows quando è abilitata (solo npm)

Rilevamento automatico dei progetti:

Quando init viene eseguito senza un argomento di directory, esegue una ricerca in ampiezza dell'albero delle directory corrente per trovare progetti compatibili (fino a 10). Tipi di progetto supportati:

• Tauri : tauri.conf.json trovato un livello sotto la directory
• Electron - package.json con electron dipendenze o devDependencies
• Flutter — pubspec.yaml alla radice del progetto
• .NET : .csproj nella radice del progetto
• Rust : Cargo.toml nella radice del progetto
• C++ - CMakeLists.txt nella radice del progetto

La ricerca ignora le directory comunemente ignorate (node_modules, bin, obj, .git e così via). Quando viene trovato un progetto compatibile, le sottodirectory sottostanti non vengono eseguite ricerche.

• Se viene specificato un argomento della directory (ad esempio, winapp init . o winapp init path/to/project), la ricerca viene ignorata e init controlla solo la directory per un progetto compatibile
• Se --use-defaults (o --no-prompt) è impostato senza un argomento di directory, init ignora la ricerca e inizializza la directory corrente in modo non interattivo, avvisa prima se non viene rilevato alcun tipo di progetto noto (ad esempio, winapp init --use-defaults)
• Negli ambienti non interattivi (stdin piped, CI, input reindirizzato), init usa --use-defaults automaticamente il comportamento e genera un avviso: Non-interactive environment detected. Using default values.
• Se la directory corrente è un progetto compatibile, init procede immediatamente
• Se si trova esattamente un progetto altrove, viene richiesto di confermare
• Se vengono trovati più progetti, è possibile selezionare quale inizializzare: la directory corrente è sempre disponibile come opzione di fallback
• Se non vengono trovati progetti, viene visualizzato un avviso e viene chiesto se procedere comunque
• Se la ricerca raggiunge il limite di 10 progetti, un avviso suggerisce di fornire un argomento della directory

Flusso automatico .NET progetto:

Quando un file .csproj viene trovato nella directory di destinazione, init usa un flusso semplificato specifico di .NET.

• Convalida e aggiorna il TargetFramework a un TFM compatibile con Windows (ad esempio, net10.0-windows10.0.26100.0)
• Aggiunge Microsoft.WindowsAppSDK e Microsoft.Windows.SDK.BuildTools come voci NuGet PackageReference direttamente in .csproj
• Genera Package.appxmanifest, asset e un certificato di sviluppo
• Non crea o winapp.yaml scarica proiezioni C++ (da usare dotnet restore per i pacchetti NuGet)

Modalità identità di tipo sparse (--exe + --sparse):

Genera un manifesto del pacchetto sparse di sola identità per un eseguibile desktop esistente, ovvero il primo passaggio del flusso di lavoro di creazione di pacchetti di tipo sparse. A differenza del flusso completo init , questa operazione ignora l'installazione di tutti gli SDK/pacchetti (i pacchetti identity sparse non hanno dipendenze SDK) e genera solo un manifesto e asset segnaposto.

• Deduce il nome del pacchetto, l'autore, la descrizione e la versione dall'exe tramite FileVersionInfo (eseguire l'override con --name, --publishero in modo interattivo)
• Scrive appxmanifest.xml (con il nome exe sostituito in Executable) più una Assets/ cartella in una sparse/ cartella nella directory corrente (o --output-dir)
• Usa --use-defaults/--no-prompt per ignorare le richieste di override interattive (ci-friendly)
• --exe senza --sparse è un errore

Gli asset sono esterni. Il sparse .msix è solo identità: il generato Assets/ viene risolto dalla directory di installazione dell'app (il percorso del contenuto esterno) in fase di esecuzione, non in bundle in .msix. Distribuirli insieme all'applicazione.

Passaggi successivi a winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> per compilare l'identità .msix, quindi winapp embed-identity <exe>. Per la procedura dettagliata completa, vedere la Guida alla creazione di pacchetti di tipo sparse .

Esempi:

# 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

Suggerimento: Installare GLI SDK dopo l'installazione iniziale

Se è stata eseguita init con --setup-sdks none (o ignorata l'installazione dell'SDK) e in un secondo momento sono necessari gli SDK:

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

Usare --setup-sdks preview o --setup-sdks experimental per le versioni dell'SDK di anteprima/sperimentale.

Nuovo…

Creare una nuova app WinUI da un modello di SDK per app di Windows dotnet new ufficiale. Interattivo per impostazione predefinita; usa automaticamente le impostazioni predefinite in ambienti non interattivi.

winapp new [options]

Opzioni:

• -t, --template <short-name>- Nome breve del modello (ad esempiowinui, , winui-navviewwinui-mvvm, winui-libwinui-unittest). Convalidato in base al pacchetto installato in fase di esecuzione; eseguire winapp new --list per visualizzare tutto. Impostazione predefinita: winui (app vuota).
• -n, --name <name> - Nome per il nuovo progetto/app (impostazione predefinita: derivato da --output, else WinUIApp)
• -o, --output <path> - Directory per creare l'app in (impostazione predefinita: ./<name>)
• --use-defaults, --no-prompt - Non richiedere; usare le impostazioni predefinite (modello vuoto, nome da --output/--namee mantenere il pacchetto di modelli installato anziché aggiornarlo)
• --force - Eseguire lo scaffolding anche se la directory di output contiene già file
• --template-version <latest|installed|version> - Versione del pacchetto di modelli WinUI: latest installa il pacchetto pubblicato più recente, installed mantiene tutto ciò che è già scaricato (nessuna rete) o aggiunge una versione esplicita, 1.2.3ad esempio . Impostazione predefinita: installare la versione più recente quando non è presente alcun pacchetto; in caso contrario, richiedere di aggiornare un pacchetto non aggiornato (mantenuto as-is in --use-defaults).
• --list - Elencare i modelli WinUI disponibili e uscire (installa prima il pacchetto più recente se non è installato nessuno)
• --json - Formattare l'output come JSON

Modelli:

L'elenco dei modelli è in tempo reale dal pacchetto installato, quindi riflette sempre la versione in esecuzione winapp new --list per visualizzare il set corrente. Modelli comuni:

Il nome breve canonico di ogni modello è il primo elenco di aliasdotnet new. Viene accettato anche qualsiasi alias elencato ( ad esempio winui3, ). wasdk-single Quando viene eseguito all'interno di un progetto WinUI esistente, dotnet new visualizza anche i modelli di elemento ,ad esempio una pagina vuota, che winapp new aggiunge al progetto corrente anziché crearne uno nuovo.

Controllo delle versioni dei pacchetti di modelli:

winapp new non aggiunge più una versione specifica del pacchetto di modelli. Se non è installato alcun pacchetto, viene installata la versione più recente. Se un pacchetto meno recente è già installato, controlla il feed e, quando esiste un pacchetto più recente, chiede se aggiornare, tranne in esecuzioni non interattive--use-defaults , che mantengono il pacchetto installato. Usare --template-version latest per prendere sempre il più recente senza chiedere conferma o --template-version installed per usare sempre il pacchetto scaricato senza un controllo di rete. Il passaggio di una versione esplicita (ad esempio --template-version 1.2.3) installa sempre esattamente tale versione, reinstallando anche quando è già presente un pacchetto più recente, in modo che lo scaffolding sia riproducibile tra i computer.

Risultato:

• Verifica che l'SDK di .NET sia installato (non riesce rapidamente con indicazioni se mancanti, winapp non installa toolchain)
• Installa o aggiorna il pacchetto di modelli WinUI ufficiale (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) su richiesta
• Enumera i modelli disponibili dal pacchetto installato e delega lo scaffolding a dotnet new <short-name>

I modelli di app WinUI includono già Windows creazione di pacchetti e identità (Package.appxmanifest), quindi non è necessario alcun passaggio separatowinapp init. Per i modelli di app, usare winapp run per compilare e avviare l'app. Il winui-lib modello produce una libreria di classi a cui fare riferimento da un progetto di app (non ha un manifesto dell'app). Il winui-unittest modello è un'app MSTest in pacchetto i cui test vengono eseguiti all'avvio dell'app (winapp run) e non tramite dotnet test. winapp neweseguire lo scaffolding nel framework di destinazione di .NET SDK installato e stampa il passaggio successivo appropriato per il modello scelto.

Passare il flag globale --verbose (-v) per eseguire l'eco di ogni chiamata sottostante dotnet (query pack, controllo di aggiornamento, installazione, dotnet new listscaffolding) insieme al relativo output completo, utile per la diagnosi di problemi di template-pack o scaffolding.

Esempi:

# 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

# 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

restaurare

Ripristinare i pacchetti e rigenerare i file in base alla configurazione esistente winapp.yaml .

winapp restore [options]

Opzioni:

• --config-dir <path> - Directory contenente winapp.yaml (impostazione predefinita: directory corrente)

Risultato:

• Legge la configurazione esistente winapp.yaml
• Download/aggiornamenti dei pacchetti SDK nelle versioni specificate
• Rigenera intestazioni e file binari C++/WinRT
• Archivia i file condivisibili nella directory della cache globale

Esempi:

# Restore from winapp.yaml in current directory
winapp restore

aggiornare

Aggiornare i pacchetti alle versioni più recenti e aggiornare il file di configurazione.

winapp update [options]

Opzioni:

• --setup-sdks <stable|preview|experimental|none> - Modalità di installazione dell'SDK: stable (impostazione predefinita), preview, experimentalo none (ignorare l'installazione dell'SDK)

Risultato:

• Legge la configurazione esistente winapp.yaml nella directory corrente
• Aggiorna tutti i pacchetti alle versioni disponibili più recenti
• Aggiorna il winapp.yaml file con nuovi numeri di versione
• Rigenera intestazioni e file binari C++/WinRT

Esempi:

# Update packages to latest versions
winapp update

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

pack

Creare pacchetti MSIX da directory dell'applicazione preparate. Richiede che un file manifesto (Package.appxmanifest preferito, appxmanifest.xml supportato anche) sia presente nella directory di destinazione, nella directory corrente o passato con l'opzione --manifest . (eseguire init o manifest generate per creare un manifesto)

Passare più cartelle di input per creare un .msixbundle oggetto per la distribuzione con più architetture (vedere Bundle a più architetture di seguito).

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

Argomenti:

• input-folder - Una o più directory contenenti i file dell'applicazione da creare nel pacchetto. Passare più cartelle (ad esempio, ./publish/x64 ./publish/arm64) per creare un bundle MSIX. Per i pacchetti identity di tipo sparse, passare direttamente un file sparse appxmanifest.xml anziché una cartella (vedere Pacchetti di identità di tipo sparse di seguito).

Opzioni:

• --output <filename> - Nome file di output. Per i singoli pacchetti: <name>_<version>_<arch>.msix (fallback a <name>_<version>.msix, <name>_<arch>.msixo <name>.msix). Per i bundle: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --name <name> - Nome pacchetto (impostazione predefinita: dal manifesto)
• --manifest <path> - Percorso del file manifesto (Package.appxmanifest preferito, appxmanifest.xml supportato; impostazione predefinita: rilevamento automatico)
• --cert <path> - Percorso del certificato di firma (abilita la firma automatica)
• --cert-password <password> - Password del certificato (impostazione predefinita: "password")
• --generate-cert - Generare un nuovo certificato di sviluppo
• --install-cert - Installare il certificato nel computer
• --publisher <name>- Publisher per la generazione di certificati. Accetta un nome distinto X.500 completo o un nome bare (incapsulato automaticamente come CN=<name>)
• --self-contained - Runtime SDK per app di Windows bundle
• --skip-pri - Ignorare la generazione di file PRI
• --executable <path> - Percorso dell'eseguibile relativo alla cartella di input (anche --exe). Usato per risolvere $targetnametoken$ i segnaposto nel manifesto.

Risultato:

• Convalida ed elabora i file Package.appxmanifest
• Risolve i $placeholder$ token nel manifesto (vedere Segnaposto manifesto di seguito)
• Assicura le dipendenze appropriate del framework
• Aggiorna manifesti side-by-side con registrazioni
• Individua e aggrega automaticamente tutti i file non immagine a cui viene fatto riferimento nel manifesto (ad esempio, AppExtension manifest.json, file di configurazione) dalla directory del manifesto o dalla cartella di input se non sono presenti nella gestione temporanea
• Individua automaticamente i componenti WinRT di terze parti e registra le classi attivabili (vedere Individuazione dei componenti WinRT di seguito)
• Gestisce la distribuzione winAppSDK autonoma
• Firma il pacchetto se il certificato fornito

Pacchetti di identità di tipo sparse

Quando l'input è un file di tipo sparse appxmanifest.xml (uno che <uap10:AllowExternalContent>true</uap10:AllowExternalContent><Properties>dichiara in ) anziché una cartella, compila un'identità di sola.msix identità, winapp pack ma solo il manifesto, senza file binari o asset dell'applicazione. Questo è il passaggio 2 del flusso di lavoro di creazione di pacchetti di tipo sparse.

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

• L'output viene impostato <PackageName>.identity.msix per impostazione predefinita nella directory corrente (eseguire l'override con --output).
• La firma si verifica solo quando --cert viene fornito (o --generate-cert).
• Se invece si passa una cartella il cui manifesto dichiara AllowExternalContent, si applica il comportamento esistente per la creazione di pacchetti di cartelle, ma winapp pack avvisa se trova asset (/.ico.png/.jpg) o file binari (.exe.dll//.so) per i pacchetti di tipo sparse che appartengono al percorso esterno, non all'interno di ..msix

Dopo la compressione, eseguire winapp embed-identity <exe> e registrare il pacchetto nel programma di installazione con Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Vedere la Guida alla creazione di pacchetti di tipo sparse.

Individuazione dei componenti WinRT

Durante la winapp pack creazione di pacchetti, winapp.yaml analizza automaticamente i pacchetti NuGet definiti in o *.csproj per i componenti WinRT di terze parti ,ad esempio Win2D. Analizza i .winmd file per estrarre i nomi delle classi attivabili e individua le DLL di implementazione. Le voci individuate vengono registrate nel modo seguente:

• Dipendente dal framework (impostazione predefinita): le classi attivabili vengono aggiunte come <InProcessServer> voci nel Package.appxmanifest
• Indipendente (--self-contained): le classi attivabili sono incorporate in manifesti SxS (Side-By-Side) all'interno del file eseguibile

Risoluzione segnaposto durante la creazione del pacchetto:

Se il manifesto contiene $targetnametoken$ nell'attributo Executable :

1. Se --executable viene specificato (percorso relativo alla cartella di input), il segnaposto viene sostituito con il valore specificato
2. In caso contrario, winapp pack analizza la radice della cartella di input per .exe i file, se ne viene trovata una, viene usata automaticamente
3. Se vengono trovati zero o più .exe file, viene visualizzato un errore che chiede di specificare --executable

Esempi:

# 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

Aggregazioni a più architetture

Quando vengono passate più cartelle di input, winapp pack crea un oggetto .msixbundle contenente uno .msix per ogni architettura:

# 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

Il comando rileva automaticamente l'architettura di ogni cartella dall'intestazione PE dell'eseguibile primario, convalida la coerenza tra sezioni (identità, funzionalità, dipendenze) e produce un oggetto <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Risoluzione del manifesto per i bundle:

Ogni sezione del bundle richiede un manifesto. Il comando risolve i manifesti in questo ordine:

1. --manifest <path> — Se specificato, questo singolo manifesto viene utilizzato per tutte le sezioni. L'oggetto ProcessorArchitecture viene aggiornato automaticamente per sezione in modo che corrisponda all'architettura rilevata.

2. Manifesto per cartella : se ogni cartella di input contiene un Package.appxmanifest manifesto della cartella (o appxmanifest.xml), viene usato per la sezione corrispondente.

3. Fallback della directory corrente : se una cartella non contiene manifesto, il comando cerca Package.appxmanifest nella directory di lavoro corrente e lo usa (con architettura contrassegnata automaticamente).

In tutti i casi, il manifesto viene aggiornato automaticamente: i segnaposto vengono risolti, le dipendenze vengono inserite e viene ProcessorArchitecture impostato forzatamente sull'architettura rilevata. Dopo la risoluzione, una convalida tra sezioni garantisce che l'identità (nome, versione, Publisher), le funzionalità e le dipendenze siano coerenti in tutte le sezioni, ma possono essere diverse.ProcessorArchitecture La versione del pacchetto definita nelle sezioni viene distribuita alla versione del bundle MSIX, tranne se è 0.0.0.0, nel qual caso viene generata automaticamente una versione basata su timestamp.

# 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

Creare l'identità dell'app per il debug usando la creazione di pacchetti di tipo sparse. L'exe rimane nella posizione originale, Windows associa l'identità tramite Add-AppxPackage -ExternalLocation.

Quando usare questo vs winapp run: usare create-debug-identity quando l'exe è separato dal codice dell'app (ad esempio, app Electron in electron.exe), node_modules o quando si testa in modo specifico il comportamento del pacchetto sparse. Per la maggior parte dei framework in cui l'exe si trova nella cartella di output di compilazione, usa winapp run invece , registra un pacchetto di layout libero completo e avvia l'app. Per un confronto completo, vedere la Guida al debug .

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

Argomenti:

• entrypoint - Percorso dell'eseguibile (.exe) o script che richiede l'identità

Opzioni:

• --manifest <path> - Percorso del file manifesto dell'app o Package.appxmanifestappxmanifest.xml (impostazione predefinita: rilevamento Package.appxmanifest automatico o appxmanifest.xml nella directory corrente)
• --no-install - Non installare il pacchetto dopo la creazione
• --keep-identity - Mantenere l'identità del manifesto as-is, senza aggiungere .debug al nome del pacchetto e all'ID applicazione

Risultato:

• Modifica il manifesto parallelo del file eseguibile
• Registra il pacchetto sperse per l'identificazione
• Abilita il debug delle API che richiedono identità

Esempi:

# 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

embed-identity

Connettere un'applicazione desktop al pacchetto di identità sparse incorporando l'elemento <msix> nel manifesto side-by-side (fusion) dell'app. Questo è il passaggio 3 del flusso di lavoro di creazione di pacchetti sparse: indica a Windows a quale pacchetto di identità appartiene l'exe in esecuzione.

winapp embed-identity <target> [options]

Argomenti:

• target - File da aggiornare. Rilevato automaticamente dall'estensione:
  • .exe (modalità EXE): incorpora l'elemento <msix> direttamente nel manifesto side-by-side dell'exe usando mt.exe.
  • .xml / .manifest (modalità XML): inserisce o sostituisce l'elemento <msix> in un file manifesto SxS esterno (creato se non esiste). Ricompilare l'app in un secondo momento in modo che il manifesto aggiornato sia incorporato nel file binario.

Opzioni:

• --manifest <path> - Percorso del sparse appxmanifest.xml da cui leggere l'identità (packageName, publisher, applicationId). Quando omesso, il comando cerca prima una sparse/ cartella accanto alla destinazione, quindi nella directory corrente, quindi nella directory di destinazione e nella directory corrente per appxmanifest.xml.

Esempi:

# 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

Questo comando è idempotente: la ripetizione dell'esecuzione sostituisce qualsiasi elemento esistente <msix> anziché duplicarlo.

manifesto

Generare e gestire i file Package.appxmanifest.

manifesto generato

Generare Package.appxmanifest dai modelli.

winapp manifest generate [directory] [options]

Argomenti:

• directory - Directory in cui generare il manifesto (impostazione predefinita: directory corrente)

Opzioni:

• --package-name <name> - Nome pacchetto (impostazione predefinita: nome cartella)
• --publisher-name <name>- Publisher nome distinto (impostazione predefinita: CN=<utente> corrente). Accetta qualsiasi DN X.500 valido; I nomi bare vengono racchiusi automaticamente come CN=<name>.
• --version <version> - Versione (impostazione predefinita: "1.0.0.0")
• --description <text> - Descrizione (impostazione predefinita: "Applicazione personale")
• --entrypoint <path> - Eseguibile o script del punto di ingresso
• --template <type> - Tipo di modello: packaged (impostazione predefinita) o sparse
• --logo-path <path> - Percorso del file di immagine del logo
• --if-exists <Error|Overwrite|Skip> - Comportamento quando il file manifesto esiste già nel percorso di destinazione (impostazione predefinita: Error)

Modelli:

• packaged - Manifesto dell'app in pacchetto standard
• sparse - Manifesto dell'app con la creazione di pacchetti di posizione sparse/esterna

Segnaposto nel manifesto

I manifesti generati utilizzano token $placeholder$ (delimitati dal segno del dollaro) che vengono risolti automaticamente in fase di creazione del pacchetto.

Questo segue la stessa convenzione usata dai modelli di progetto Visual Studio, quindi i manifesti sono portabili tra gli strumenti.

Come vengono risolti i segnaposto:

• winapp pack - Durante la creazione di pacchetti, $targetnametoken$ viene risolto usando l'opzione --executable o rilevando automaticamente il singolo .exe nella cartella di input. Se vengono trovati più file (o zero) .exe e --executable non viene specificato, viene visualizzato un errore.
• winapp create-debug-identity — Quando viene fornito un argomento del punto di ingresso, $targetnametoken$ viene risolto da esso. Senza un punto di ingresso, il segnaposto eseguibile deve essere già risolto nel manifesto.
• winapp manifest generate --executable — Quando --executable viene specificato, i metadati del manifesto (versione, descrizione) e le icone vengono estratti dal file eseguibile, ma il manifesto generato usa $targetnametoken$.exeancora ; questo segnaposto viene risolto in un secondo momento (ad esempio winapp pack o winapp create-debug-identity).

PS: Mantenere $targetnametoken$ nel manifesto archiviato evita i nomi eseguibili hardcoded e funziona con entrambe le build winapp pack e Visual Studio.

Esempi:

# Generate standard manifest interactively
winapp manifest generate

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

manifest add-alias

Aggiungere un alias di esecuzione (uap5:AppExecutionAlias) a package.appxmanifest. Ciò consente di avviare l'app in pacchetto dalla riga di comando digitando il nome dell'alias.

winapp manifest add-alias [options]

Opzioni:

• --name <alias> - Nome alias (ad esempio myapp.exe). Impostazione predefinita: dedotto dall'attributo Executable nel manifesto.
• --manifest <path> - Percorso di Package.appxmanifest (impostazione predefinita: directory corrente di ricerca)
• --app-id <id> - ID applicazione a cui aggiungere l'alias (impostazione predefinita: primo elemento Application)

Risultato:

• Legge il manifesto e deduce l'alias dall'attributo Executable (mantenendo segnaposto come $targetnametoken$.exe)
• Aggiunge la uap5 dichiarazione dello spazio dei nomi se non è già presente
• Aggiunge un <Extensions> blocco con <uap5:AppExecutionAlias> all'interno dell'elemento Application di destinazione
• Se l'alias esiste già, lo segnala e viene chiuso correttamente

Esempi:

# 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

aggiornamento asset del manifesto

Generare tutti gli asset di immagine MSIX necessari da un'unica immagine di origine.

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

Argomenti:

• image-path - Percorso del file di immagine di origine (PNG, JPG, SVG, ICO, GIF, BMP e così via)

Opzioni:

• --manifest <path> - Percorso del file Package.appxmanifest (impostazione predefinita: directory corrente di ricerca)
• --light-image <path> - Percorso di un'immagine di origine separata per le varianti del tema chiaro

Descrizione:

Accetta una singola immagine di origine e genera un set completo di asset di immagine MSIX in base ai riferimenti asset del manifesto:

Per ogni asset a cui viene fatto riferimento nel manifesto:

• 5 varianti di scala — base (nessun suffisso), .scale-125, .scale-150, .scale-200, .scale-400

Per l'icona dell'app (Square44x44Logo/AppList, 44×44 base):

• 14 varianti con destinazioni piattate — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14 destinazioni non conpiattata - .targetsize-{size}_altform-unplated

Inoltre:

• app.ico : file ICO a risoluzione multipla (16, 24, 32, 48, 256) per l'integrazione della shell. Se un file esistente .ico viene trovato nella directory assets (ad esempio AppIcon.ico da un modello di progetto), viene sostituito sul posto anziché creare un duplicato

Con --light-image:

• Tema chiaro destinazioni varianti - .targetsize-{size}_altform-lightunplated (icona dell'app)
• Varianti di scala del tema chiaro - .scale-{factor}_altform-colorful_theme-light (riquadri, logo dello store)

Supporto SVG: I file SVG sono completamente supportati come immagini di origine. Vengono visualizzati come vettori direttamente a ogni dimensione di destinazione, producendo risultati perfetti in pixel a tutte le risoluzioni.

Il comando ridimensiona le immagini in modo proporzionale mantenendo le proporzioni, centrandole con sfondi trasparenti quando necessario. Le risorse vengono salvate nella Assets cartella relativa alla posizione del manifesto.

Esempi:

# 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

run

Creare un pacchetto di layout libero da una cartella di output di compilazione, registrarlo con Windows usando l'API Windows.Management.Deployment.PackageManager e avviare l'applicazione, simulando un'installazione MSIX completa per il debug. Restituisce l'ID del processo per l'allegato del debugger.

winapp run opera in una delle due modalità scelte automaticamente dall'input:

• Modalità cartella: l'input è una cartella di output di compilazione (contiene un ).Package.appxmanifest/AppxManifest.xml
• Project modalità : l'input è una .csproj.sln/.slnx soluzione o una directory contenente uno. winapp run compila il progetto e lo avvia, supportando sia le app WinUI in pacchetto che non in pacchetto . Vedere Project modalità di seguito.

Questo è il comando preferito per il debug con l'identità del pacchetto per la maggior parte dei framework (.NET, C++, Rust, Flutter, Tauri). A differenza del create-debug-identity quale registra un pacchetto sparse per un singolo exe, winapp run registra l'intera cartella come pacchetto di layout libero, proprio come un'installazione MSIX reale. Vedere la Guida al debug per i flussi di lavoro di debug comuni.

winapp run [<input>] [options]

Argomenti:

• input - L'app da eseguire: una cartella di output di compilazione (modalità cartella), un .csproj progetto, una .sln/.slnx soluzione o una directory contenente uno di quelli al livello superiore (modalità progetto; la directory non viene eseguita in modo ricorsivo). Usare . per compilare/eseguire il progetto nella directory corrente. Facoltativo: il valore predefinito è la directory corrente quando viene omesso (corrisponde a dotnet run).

Opzioni:

• --manifest <path> - Percorso di Package.appxmanifest (impostazione predefinita: rilevamento automatico dalla cartella di input o dalla directory corrente)
• --output-appx-directory <path> - Directory di output per il pacchetto di layout libero (impostazione predefinita: AppX all'interno della directory della cartella di input)
• --args <string> - Argomenti della riga di comando da passare all'applicazione. In alternativa, usare -- seguito da argomenti per evitare l'escape ,ad esempio winapp run . -- --flag value.
• --no-launch - Creare solo l'identità di debug e registrare il pacchetto senza avviare l'applicazione
• --with-alias - Avviare l'app usando l'alias di esecuzione anziché l'attivazione AUMID. L'app viene eseguita nel terminale corrente con stdin/stdout/stderr ereditato. Richiede un oggetto uap5:ExecutionAlias nel manifesto (usare winapp manifest add-alias per aggiungerne uno). Non è possibile combinare con --no-launch. Non è possibile combinare con --json.
• --debug-output - Acquisire OutputDebugString messaggi ed eccezioni first-chance dall'applicazione avviata. Il disturbo del framework (WinUI, COM, DirectX) viene filtrato dall'output della console; il file di log completo acquisisce tutti gli elementi. Se l'app si arresta in modo anomalo, acquisisce automaticamente un minidump e lo analizza per visualizzare il tipo di eccezione, il messaggio e l'analisi dello stack con i numeri di riga del file di origine (risolti dai PDB nella cartella di output di compilazione). Gli arresti anomali gestiti (.NET) vengono analizzati immediatamente senza strumenti esterni. Gli arresti anomali nativi (C++/WinRT) mostrano i nomi e gli offset dei moduli. Quando l'app arrestata in modo anomalo è un'app WinUI 3 (Microsoft.UI.Xaml.dll viene caricata), viene eseguito automaticamente un passaggio aggiuntivo di valutazione delle eccezioni per visualizzare l'HRESULT di origine, la catena ErrorContext e lo stack di dispatch XAML nativo completo; i componenti del debugger necessari vengono scaricati al primo uso (vedere Debug, sottoponibile a override tramite la WINAPP_DBGTOOLS_DIR variabile di ambiente). È possibile collegare un solo debugger a un processo alla volta, quindi non è possibile usare simultaneamente altri debugger (Visual Studio, VS Code). Usare --no-launch invece se è necessario collegare un debugger diverso. Non è possibile combinare con --no-launch. Non è possibile combinare con --json.
• --symbols - Scaricare i simboli PDB da Microsoft Server simboli per un'analisi degli arresti anomali nativa più completa con nomi di funzione risolti. Usati solo con --debug-output. Se omesso e si verifica un arresto anomalo nativo, l'output suggerisce di aggiungere questo flag. Questo flag migliora anche lo stack di valutazione delle eccezioni winUI per le app WinUI 3. Prima esecuzione scarica i simboli e li memorizza nella cache in locale; le esecuzioni successive usano la cache.
• --unregister-on-exit - Annullare la registrazione del pacchetto di sviluppo dopo l'uscita dell'applicazione. Rimuove solo i pacchetti registrati in modalità di sviluppo. Non è possibile combinare con --no-launch.
• --detach - Avviare l'applicazione e tornare immediatamente senza attendere che venga chiusa. Utile per l'integrazione continua/automazione in cui è necessario interagire con l'app dopo l'avvio. Stampa il PID in stdout (o in JSON con --json). Non è possibile combinare con --no-launch, --debug-output, --with-aliaso --unregister-on-exit.
• --clean - Rimuovere i dati dell'applicazione del pacchetto esistente (LocalState, impostazioni e così via) prima della ri-distribuzione. Per impostazione predefinita, i dati dell'applicazione sono mantenuti tra le distribuzioni.
• --json - Formattare l'output come JSON per l'utilizzo a livello di codice ,ad esempio CI/automazione. Utile con --detach per acquisire il PID. Non può essere combinato con --with-alias o --debug-output.

Persistenza dei dati dell'applicazione:

Per impostazione predefinita, winapp run mantiene i dati dell'applicazione (LocalState, RoamingState, Settingse così via) durante la ri-distribuzione. Se l'app scrive i dati nel ApplicationData.Current.LocalFolder contesto del pacchetto o Environment.GetFolderPath(SpecialFolder.LocalApplicationData) all'interno del contesto del pacchetto, tali dati sopravviveranno tra winapp run le chiamate.

Usare --clean quando è necessario un nuovo avvio (ad esempio, per reimpostare lo stato danneggiato o testare il comportamento della prima esecuzione).

Risultato:

• Individua o genera package.appxmanifest
• Crea e registra un'identità di debug usando un pacchetto di layout libero
• Calcola l'ID modello utente applicazione (AUMID)
• Avvia l'applicazione usando l'identità registrata (a meno che non --no-launch sia specificato)
• Stampa l'ID processo (PID) per l'allegato del debugger

Esempi:

# 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

modalità Project (progetti SDK .NET)

Quando l'input è , .csprojuna .sln/.slnx soluzione o una directory contenente uno (incluso .), winapp runcompila il progetto con dotnet build e lo avvia. Supporta sia le app WinUI in pacchetto che non in pacchetto e installa l'architettura corrispondente app di Windows Runtime necessarie per l'avvio dell'app.

Input della soluzione: punta winapp run a una (o a una .sln/.slnx directory contenente una , una soluzione è preferibile rispetto ai file separati.csproj) e risolve il progetto di app eseguibile, quindi lo compila con $(SolutionDir) e le proprietà di pari Solution* livello definite, in modo che i progetti che dipendono da essi vengano compilati come fanno in Visual Studio. Regole di risoluzione:

• I progetti di test vengono ignorati durante la selezione automatica, quindi una soluzione contenente un'app e i relativi test vengono risolti nell'app senza --project bisogno. Un progetto di test WinUI è un'app in pacchetto, quindi il tipo di output da solo non può distinguerlo.
• Se l'unico progetto eseguibile è un progetto di test, viene eseguito.
• Se esiste più di un progetto di app eseguibile, winapp run non indovina un progetto di avvio, ma si verifica un errore nell'elenco dei candidati. Usare --project <name> per scegliere, che viene sempre rispettato, incluso per selezionare un progetto di test.

Packaged vs. unpackaged viene rilevato automaticamente dalla proprietà MSBuild effettiva WindowsPackageType del progetto (mai dalla presenza del manifesto):

• Pacchetto (WindowsPackageType=MSIXimpostazione predefinita in pacchetto winUI): compila, quindi registra l'output di compilazione come pacchetto di layout libero e viene avviato tramite AUMID (la stessa pipeline della modalità cartella).
• Unpackaged (WindowsPackageType=None): le compilazioni assicurano che il runtime di app di Windows dipendente dal framework sia installato, quindi avvia direttamente la compilazione.exe. Forzare questa operazione per un progetto in pacchetto con -p WindowsPackageType=None.

Project modalità richiede .NET SDK 8.0.100 o versione successiva (per MSBuild--getProperty).

opzioni in modalità Project (ignorate in modalità cartella):

• -c, --configuration <name> - Configurazione della compilazione. Impostazione predefinita: Debug.
• --arch <x64|arm64|x86> - Architettura di destinazione. Impostazione predefinita: architettura del processo corrente. Determina sia il RID di compilazione che l'architettura del runtime di app di Windows che viene installato.
• -r, --runtime <rid>- Specificare .NET identificatore di runtime ,ad esempio win-x64. Project modalità usa solo l'architettura del RID, compila sempre il canonico win-<arch>e rifiuta i RID non Windows ( ad esempio linux-x64). L'architettura esegue l'override di --arch.
• -f, --framework <tfm> - Moniker del framework di destinazione per i progetti con più destinazioni ( ad esempio net10.0-windows10.0.26100.0).
• --project <name-or-path> - Quando l'input è una soluzione (.sln/.slnx) o una directory con più progetti di app eseguibili, seleziona il progetto da avviare (in base al nome o al percorso del progetto).
• --no-build - Ignorare la compilazione ed eseguire l'output di compilazione esistente (valuta comunque le proprietà di output).
• --no-restore - Ignorare il ripristino del progetto prima della compilazione.
• -p, --property <Name=Value> - Proprietà MSBuild inoltrata sia alla compilazione che alla valutazione della proprietà. Ripetibile (ad esempio -p WindowsPackageType=None).

Output e dettaglio della compilazione: il progetto viene compilato in due passaggi, ovvero un oggetto i dotnet build cui flussi di output sono live nella console, seguiti da un passaggio rapido di valutazione delle proprietà. Winapp stampa la chiamata esatta dotnet build … prima dell'output e trasmette gli avvisi anche in caso di compilazione riuscita. Dettaglio:

In --json o --quiet l'output di chiamata e compilazione passa a stderr in modo che stdout rimanga puro JSON/pulito.

Applicabilità delle opzioni di opzione: le opzioni identity/loose-layout (--manifest, --output-appx-directory, --clean--unregister-on-exit--no-launch--with-alias, , --executable) si applicano solo alle app in pacchetto. Vengono rifiutati con un errore chiaro per le app non in pacchetto (senza pacchetto MSIX). Le opzioni di avvio/debug (--args/--, --detach, --debug-output--symbols, , ) --jsonfunzionano in entrambi.

esempi in modalità 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

# 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

Proprietà di MSBuild (pacchetto NuGet):

Quando si usa il pacchetto NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run richiama automaticamente winapp run. Per controllare il .csproj comportamento, è possibile impostare le proprietà MSBuild seguenti:

Impostazioni che si escludono a vicenda. WinAppRunNoLaunch e WinAppRunDetach ognuno descrive un comportamento di avvio diverso, in modo che siano in conflitto con le altre proprietà di avvio e tra loro. L'impostazione di una coppia in conflitto non riesce con --X and --Y cannot be used together:

WinAppRunUseExecutionAlias, WinAppRunDebugOutpute WinAppRunUnregisterOnExit possono essere combinati tra loro. WinAppRunClean WinAppRunExecutable, WinAppRunSymbols, e WinAppLaunchArgs non hanno restrizioni. WinAppRunArgs non aggiunge alcuna restrizione propria, ma un'opzione passata attraverso di esso viene controllata come qualsiasi altra, quindi WinAppRunArgs="--detach" è ancora in conflitto con WinAppRunNoLaunch.

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

Unregister

Annullare la registrazione di un pacchetto di sviluppo trasferita localmente. Rimuove solo i pacchetti registrati in modalità di sviluppo ,ad esempio tramite winapp run o create-debug-identity. I pacchetti installati dall'archivio o installati da MSIX non vengono mai rimossi.

winapp unregister [options]

Opzioni:

• --manifest <path> - Percorso di Package.appxmanifest (impostazione predefinita: rilevamento automatico dalla directory corrente)
• --force - Ignorare il controllo della directory install-location e annullare la registrazione anche se il pacchetto è stato registrato da un albero del progetto diverso
• --json - Formattare l'output come JSON

Risultato:

• Legge il nome del pacchetto dal manifesto
• Cerca entrambi i {name} pacchetti e {name}.debug (la variante di debug viene creata da create-debug-identity)
• Verifica che ogni pacchetto sia stato registrato in modalità di sviluppo (IsDevelopmentMode == true)
• Verifica che il percorso di installazione del pacchetto si trova nell'albero della directory corrente (a meno che --force)
• Annulla la registrazione dei pacchetti corrispondenti

Esempi:

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

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

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

# JSON output for scripting
winapp unregister --json

cert

Generare, esaminare e installare i certificati di sviluppo.

Generazione di certificati

Generare certificati di sviluppo per la firma del pacchetto.

winapp cert generate [options]

Opzioni:

• --manifest <Package.appxmanifest> - Estrarre informazioni sull'editore da Package.appxmanifest
• --publisher <name>- Publisher per il certificato. Accetta un nome distinto X.500 completo (ad esempio) CN=Contoso, O=Contoso Ltd, C=USo un nome bare che viene eseguito automaticamente come wrapping CN=<name>
• --output <path> - Percorso del file di certificato di output (supporta percorsi assoluti e relativi)
• --password <password> - Password del certificato (impostazione predefinita: "password")
• --valid-days <valid-days> - Numero di giorni in cui il certificato è valido (impostazione predefinita: 365)
• --install - Installare il certificato nell'archivio del computer locale dopo la generazione
• --if-exists <Error|Overwrite|Skip> - Impostare il comportamento se il file di certificato esiste già (impostazione predefinita: Errore)
• --export-cer - Esportare un .cer file (solo chiave pubblica) insieme a .pfx. Utile per distribuire il certificato pubblico separatamente per l'installazione trust.
• --json - Formattare l'output come JSON per l'utilizzo a livello di codice. Gli errori vengono restituiti anche come JSON ({"error": "..."}).

Informazioni sul certificato

Visualizzare i dettagli del certificato da un file PFX. Utile per verificare che un certificato corrisponda al manifesto prima della firma.

winapp cert info <cert-path> [options]

Argomenti:

• cert-path - Percorso del file di certificato (PFX)

Opzioni:

• --password <password> - Password per il file PFX (impostazione predefinita: "password")
• --json - Formattare l'output come JSON

Installazione del certificato

Installare il certificato nell'archivio certificati del computer.

winapp cert install <cert-path> [options]

Argomenti:

• cert-path - Percorso del file di certificato da installare

Esempi:

# 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

segno

Firmare pacchetti MSIX ed eseguibili con certificati.

winapp sign <file-path> [options]

Argomenti:

• file-path - Percorso del pacchetto MSIX o del file eseguibile da firmare

Opzioni:

• --cert <path> - Percorso del certificato di firma
• --cert-password <password> - Password del certificato (impostazione predefinita: "password")

Esempi:

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

az-sign

Firmare un file (exe, MSIX o bundle MSIX) usando Firma attendibile di Azure, ovvero un'identità di firma gestita dal cloud, quindi non esiste mai una chiave privata (PFX) nel computer locale.

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

Argomenti:

• file-path - Percorso del file da firmare (exe, msix o msixbundle)

Opzioni:

• --subscription, - -s Azure ID sottoscrizione da usare. Se non sono disponibili e sono presenti più sottoscrizioni, verrà richiesto di
• --resource-group, -r - Gruppo di risorse per limitare gli account di firma
• --account - Nome dell'account di firma. Deve essere usato con --resource-group
• --profile, -p - Nome del profilo certificato. Deve essere usato con --account
• --metadata-file, -m - Percorso di un oggetto esistente metadata.json. Ignora le richieste di individuazione delle risorse e la selezione di account/profilo direttamente. Una credenziale Azure non interattiva dovrebbe essere già disponibile. L'interfaccia della riga di comando può altrimenti eseguire il fallback a un prompt interattivo del tenant o az login, ma l'API programmatica npm è sempre non interattiva e non riesce anziché richiedere

Autenticazione:

az-signusa la catena di credenziali standard di Azure (DefaultAzureCredential). Per CI/CD, impostare AZURE_TENANT_ID, AZURE_CLIENT_IDe AZURE_CLIENT_SECRET (o usare GitHub Actions'identità OIDC/gestita). In qualsiasi ambiente viene rispettata anche una sessione di interfaccia della riga di comando di Azure esistente (az logininclusa l'azione azure/login GitHub). Solo quando non vengono trovate credenziali e la sessione è interattiva verrà az-sign avviata az login automaticamente.

Prerequisiti:

• Un account di firma del codice Azure e un profilo certificato (creato nel portale di Azure dopo la convalida dell'identità), oltre al ruolo di firmatario del profilo certificato di firma del codice assegnato all'identità. Per altre indicazioni, vedere Azure documentazione di avvio rapido sulla firma degli artefatti.
• Un runtime x64 a livello di computer .NET 8 (o versione successiva) installato. La libreria client di firma Azure è un assembly gestito che signtool.exe carica in un processo separato; il runtime autonomo di winapp non lo soddisfa. Installarlo da https://dotnet.microsoft.com/download se la firma non riesce con un errore di runtime-load.
• Oggetto Microsoft Visual C++ Redistributable (x64). La libreria client di firma Azure dipende dal runtime vc++ e poiché winapp scarica il pacchetto NuGet non elaborato anziché il programma di installazione ufficiale degli strumenti client, questa dipendenza non viene installata automaticamente. Un computer pulito può avere esito negativo anche con .NET e SignTool presenti. Installare la versione più recente di x64 ridistribuibile da https://aka.ms/vs/17/release/vc_redist.x64.exe se la firma ha esito negativo con un 0xc000007berrore , "L'applicazione non è stata in grado di avviarsi correttamente" o un errore di DLL mancante da dlib.

CI con privilegi minimi: L'individuazione automatica (elenco di sottoscrizioni, gruppi di risorse, account e profili) richiede l'accesso in lettura a un ambito padre. Per evitare ogni chiamata all'elenco di --subscriptionraccolte, passare tutte e quattro le operazioni , --resource-group, --accounte --profile: az-sign convalida quindi l'account e il profilo con letture di risorse dirette (get su ogni risorsa denominata) anziché enumerare la raccolta padre, quindi un'entità con ambito limitato a tale account e profilo è sufficiente. L'omissione di una di esse introduce nuovamente una chiamata di presentazione, ad esempio lasciando fuori --subscriptionaz-sign l'elenco delle sottoscrizioni a cui l'identità può accedere, che un'entità con ambito ristretto potrebbe non essere consentita. Un'entità con ambito solo a un singolo profilo certificato può ignorare completamente la convalida passando un'entità pregenerata --metadata-file (che specifica direttamente l'endpoint e il profilo dell'account).

Esempi:

# 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

Generare un CodeIntegrityExternal.cat file di catalogo contenente hash di file eseguibili dalle directory specificate. Questo catalogo viene usato con il flag TrustedLaunch nei manifesti del pacchetto sparse MSIX (AllowExternalContent) per consentire l'esecuzione di file esterni non inclusi nel pacchetto stesso.

Questo è simile al modo in cui viene creato signtool.exe durante la firma di un pacchetto MSIX, ma genera un catalogo esterno da usare con AppxMetadata\CodeIntegrity.cat.

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

Argomenti:

• input-folder - Una o più directory contenenti file eseguibili da elaborare. Separare più directory con punti e virgola (ad esempio, "dir1;dir2")

Opzioni:

• --recursive, -r - Includere file da sottodirectory
• --use-page-hashes - Includi hash di pagina durante la generazione del catalogo (produce un catalogo più grande con dati hash per pagina)
• --compute-flat-hashes - Includere hash di file flat durante la generazione del catalogo
• --if-exists <Error|Overwrite|Skip> - Comportamento quando il file di output esiste già (impostazione predefinita: Error)
• --output, -o - Percorso del file del catalogo di output. Se non specificato, CodeIntegrityExternal.cat viene creato nella directory corrente. Se viene specificata una directory, viene aggiunto il nome file predefinito.

Risultato:

• Analizza le directory specificate per i file eseguibili (file binari PE con sezioni di codice)
• Genera un file di definizione del catalogo (CDF) con hash di tutti i file eseguibili trovati
• Usa Windows API CryptoCAT per produrre il file di catalogo .cat
• I file non eseguibili (ad esempio .txt, , .dll senza sezioni di codice) vengono ignorati automaticamente

Esempi:

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

Usare questo comando quando si compila un pacchetto MSIX sparse che usa TrustedLaunch per verificare gli eseguibili esterni. Il flusso di lavoro tipico è:

1. winapp manifest generate --template sparse — Creare un manifesto di tipo sparse con AllowExternalContent
2. winapp create-external-catalog ./bin - Generare il catalogo di integrità del codice per i file eseguibili dell'app
3. winapp pack — Creare un pacchetto del manifesto, degli asset e del catalogo in un file MSIX

strumento

Accedi direttamente agli strumenti del Windows SDK. Usa gli strumenti disponibili in Microsoft.Windows. SDK. BuildTools

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

Strumenti disponibili:

• makeappx - Creare e modificare pacchetti di app
• signtool - Firmare i file e verificare le firme
• mt - Strumento manifesto per assembly affiancate
• E altri strumenti sdk di Windows da Microsoft.Windows. SDK. BuildTools

Esempi:

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

store

Eseguire un comando di Microsoft Store Developer CLI. Questo comando scaricherà l'interfaccia della riga di comando per sviluppatori Microsoft Store se non è già stata scaricata. Altre informazioni sull'interfaccia della riga di comando Microsoft Store Developer.

winapp store [args...]

Argomenti:

• args... : argomenti da passare direttamente all'interfaccia della msstore riga di comando. Vedere la documentazione dell'interfaccia della riga di comando di MSStore per i comandi e le opzioni disponibili.

Risultato:

• Assicura che l'interfaccia della riga di comando Microsoft Store Developer (msstore) sia scaricata e disponibile nel sistema.
• Inoltra tutti gli argomenti all'interfaccia della msstore riga di comando.
• Esegue il comando che mostra l'output direttamente nel terminale.

Esempi:

# 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

Ottieni i percorsi dei componenti di Windows SDK installati.

winapp get-winapp-path [options]

Cosa restituisce:

• Percorsi della directory dell'area .winapp di lavoro
• Directory di installazione dei pacchetti
• Percorsi di intestazione generati

find-ui

Cercare controlli e esempi winUI per un esempio di codice funzionante. Solo WinUI: il corpus è winUI 3 Gallery e Windows Community Toolkit (oltre ad alcuni modelli di base curati), non copre macchine virtuali Windows, WinForms o altri framework dell'interfaccia utente. Una terza origine, microsoft-ui-reactor ReactorGallery, è esplicita: è esclusa da una ricerca normale e cercata solo quando passi --source reactor (i relativi campioni dichiarativi C#-only non incollano in un'app XAML standard, quindi contattalo solo durante la compilazione di un progetto Reactor/MVU).

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

Il corpus viene recuperato da GitHub al primo utilizzo e memorizzato nella cache per utente in <global .winapp>/cache/find-ui, quindi la prima esecuzione richiede l'accesso alla rete. Le esecuzioni successive vengono gestite dalla cache locale (aggiornate al massimo ogni 7 giorni o su richiesta con --refresh).

Opzioni:

• --id <id> - Recuperare il codice (Gallery/Toolkit restituisce XAML e/o C#; Reactor è C#-only) più le note dei prerequisiti per uno o più ID scenario da una ricerca precedente (ad esempio gallery-tabview-1). Ripetibile. Gli ID non fanno distinzione tra maiuscole e minuscole : GALLERY-TABVIEW-1 risolve lo stesso valore di gallery-tabview-1.
• --list - Elencare ogni ID di controllo o di esempio individuabile invece di eseguire ricerche (Gallery + Toolkit + core; l'origine del reattore di consenso esplicito è esclusa).
• --source <gallery|toolkit|reactor|core> - Limitare i risultati della ricerca a una singola origine. (Solo ricerca - non valido con --list/--id.) Reattore è opt-in — è escluso da una ricerca normale, quindi --source reactor è l'unico modo per cercarlo.
• --max <N> - Numero massimo di controlli corrispondenti da restituire (impostazione predefinita: 3). Si applica solo alla ricerca; ignorato con --list/--id.
• --refresh- Ignorare la cache locale e recuperare nuovamente il corpus winUI da GitHub.
• --json - Generare json strutturato (compatibile con l'agente). Per la ricerca, ogni corrispondenza contiene , , , e una scenarios matrice le cui voci contengono il per-scenario id e header; per --id, il codice completo. descriptionscorecontrolsource In --jsonogni errore, inclusi gli errori dell'argomento/parser, ad esempio un numero intero --max , viene generato come oggetto flat {"error": "..."} in stdout con un codice di uscita diverso da zero, quindi l'output rimane leggibile dal computer.

Flusso di lavoro: cercare compattamente per trovare il controllo corretto e i relativi ID scenario, quindi recuperare il codice completo per ottenere la corrispondenza migliore con --id.

Esempi:

# 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

binding di generazione di nodi

(Disponibile solo nel pacchetto NPM) Generare associazioni JS per SDK per app di Windows API. Le associazioni vengono dichiarate da uno "winapp": { "jsBindings": {...} } spazio dei nomi in e scritte in package.json.winapp/bindings/.

npx winapp node generate-bindings [options]

Opzioni:

• --verbose, -v - Abilitare l'output dettagliato per ogni file codegen
• --quiet, -q - Eliminare lo stato di avanzamento e l'output informativo

Risultato:

• Legge il blocco da winapp.jsBindings e l'oggetto package.json scritto dall'ultimo winmds.lock.json, quindi genera associazioni tipate winapp restore.js + in .d.ts.winapp/bindings/
• Non modificapackage.json : è un rigeneratore passivo. L'aggiunta del winapp.jsBindings blocco e della dipendenza di runtime si verifica durante @microsoft/dynwinrt l'abilitazione winapp init delle associazioni JS. Questo comando ha esito negativo se il blocco è assente
• Avvisa (ma non scrive) se @microsoft/dynwinrt non è presente nelle dipendenze, eseguire npm install dopo init averlo aggiunto

Esempi:

# 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

Vedere la guida alle associazioni JS per il flusso di lavoro end-to-end e le winapp.jsBindings opzioni di configurazione.

node create-addon

(disponibile solo nel pacchetto NPM) Generare modelli di componente aggiuntivo C++ o C# nativi con Windows SDK e integrazione SDK per app di Windows.

npx winapp node create-addon [options]

Opzioni:

• --name <name> - Nome del componente aggiuntivo (impostazione predefinita: "nativeWindowsAddon")
• --template - Selezionare il tipo di componente aggiuntivo. Le opzioni sono cs o cpp (impostazione predefinita: cpp)
• --verbose - Abilitare l'output dettagliato

Risultato:

• Crea la directory del componente aggiuntivo con i file modello
• Genera binding.gyp e addon.cc con esempi Windows SDK
• Installa le dipendenze npm necessarie (nan, node-addon-api, node-gyp)
• Aggiunge script di compilazione a package.json

Esempi:

# 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

(Disponibile solo nel pacchetto NPM) Aggiungere l'identità dell'app al processo di sviluppo electron usando la creazione di pacchetti di tipo sparse. Richiede un Package.appxmanifest (crearne uno con winapp init o winapp manifest generate se non ne hai uno).

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

Opzioni:

Risultato:

• Registra l'identità di debug per electron.exe processo
• Consente di testare le API che richiedono identità nello sviluppo di Elettroni
• Usa package.appxmanifest esistente per la configurazione delle identità

Esempi:

# 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

nodo clear-electron-debug-identity

(Disponibile solo nel pacchetto NPM) Rimuovere l'identità del pacchetto dal processo di debug Electron ripristinando il electron.exe originale dal backup.

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

Opzioni:

Risultato:

• Ripristina electron.exe dal backup creato da add-electron-debug-identity
• Rimuove i file di backup dopo il ripristino
• Restituisce Electron allo stato originale senza identità del pacchetto

Esempi:

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

Opzioni globali

Tutti i comandi supportano queste opzioni globali:

• --verbose, -v - Abilitare l'output dettagliato per la registrazione dettagliata
• --quiet, -q - Elimina i messaggi di stato
• --help, -h - Mostra guida ai comandi

Global Cache Directory

Winapp crea una directory per memorizzare nella cache i file che possono essere condivisi tra più progetti.

Per impostazione predefinita, winapp crea una directory in $UserProfile/.winapp come directory della cache globale.

Per usare un percorso diverso, impostare la WINAPP_CLI_CACHE_DIRECTORY variabile di ambiente.

In cmd:

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

In PowerShell e pwsh:

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

Winapp creerà automaticamente questa directory quando si eseguono comandi come init o restore.

Controlli di aggiornamento

L'interfaccia della riga di comando di winapp verifica periodicamente la presenza di nuove versioni e visualizza un avviso una riga quando è disponibile un aggiornamento. Questo controllo viene eseguito in background e non aggiunge alcuna latenza ai comandi.

I controlli di aggiornamento vengono disabilitati automaticamente negli ambienti ci (GitHub Actions, Azure Pipelines e così via).

Per disabilitare manualmente i controlli di aggiornamento, impostare la WINAPP_CLI_UPDATE_CHECK variabile di ambiente su 0.

In cmd:

set WINAPP_CLI_UPDATE_CHECK=0

In PowerShell e pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Per rendere permanente questa operazione:

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

ui

Esaminare e interagire con l'esecuzione di interfacce utente dell'app Windows usando Automazione interfaccia utente (UIA).

winapp ui [command] [options]

Comandi:

• status - Connettersi all'app e visualizzare informazioni
• inspect - Struttura ad albero degli elementi di visualizzazione
• search - Trovare elementi in base al selettore
• get-property - Proprietà degli elementi di lettura
• get-text / get-value - Valore di lettura/testo dall'elemento (TextPattern, ValuePattern o Name)
• screenshot - Acquisisci finestra/elemento come PNG (acquisisce automaticamente le finestre di dialogo separatamente)
• record- Registrare un'area finestra/elemento in un video H.264 MP4 (Windows Acquisizione grafica + Media Foundation)
• invoke - Attiva elemento (fare clic, attivare o disattivare, espandere)
• click - Fare clic sull'elemento tramite simulazione del mouse (per i controlli che non supportano invoke)
• hover - Spostare il mouse nell'elemento per attivare descrizioni comando, riquadri a comparsa e stati di passaggio del mouse (attesa predefinita: 800 ms)
• drag - Trascinare il mouse da un punto a un altro, in base al selettore di elementi o alle coordinate dello schermo x,y (riordinare, ridimensionare, dispositivi di scorrimento, trascinare e rilasciare)
• touch - Inserire movimenti di tocco sintetici (tocco, doppio tocco, pressione prolungata, scorrimento rapido, avvicinamento delle dita) in corrispondenza di coordinate del centro o dello schermo x,y di un elemento
• pen - Inserire input penna/stilo sintetico — tocco e tratti input penna con pressione configurabile, inclinazione e modalità gomma
• send-keys - Inviare input da tastiera sintetica (tasti denominati, combo, vk=0xNN o testo letterale) a una finestra
• set-value - Imposta il valore sull'elemento modificabile (testo, numero); esegue il fallback a LegacyIAccessible put_accValue per i controlli rich edit solo TextPattern
• focus - Spostare lo stato attivo della tastiera
• scroll-into-view - Elemento scroll visibile
• wait-for - Attendere lo stato dell'elemento
• list-windows - Elencare tutte le finestre per un'app
• get-focused - Segnalare l'elemento attualmente attivo

Opzioni:

• -a, --app <app> - App di destinazione (nome, titolo o PID)
• -w, --window <hwnd> - Finestra di destinazione di HWND (stabile)

record dell'interfaccia utente

Registrare una finestra o un'area dell'elemento in un mp4 H.264.

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

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

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

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

Opzioni record:

• --duration-sec <n> - Lunghezza della registrazione in secondi. 0 registra fino a CTRL+C (impostazione predefinita 0).
• --fps <n> - Fotogrammi al secondo da acquisire (impostazione predefinita 15).
• --max-edge <px> - Ridimensionamento in modo che il bordo più lungo sia al massimo questo numero di pixel (0 = nessuna scala inferiore).
• --capture-screen - Acquisizione dallo schermo in modo da includere sovrimpressioni/popup (può acquisire finestre occluding).
• -o, --output <path> - Percorso di output .mp4 (per impostazione predefinita è recording-<timestamp>-<guid>.mp4).
• --frames - Scrivere JPEG con timestamp, frames.ndjsone manifest.json in <output-name>.frames. Supporta 1-30 fps e --max-edge 64-4096 (impostazione predefinita 1280), con un limite di 1 GiB frame-data.

Con --json, il risultato finale include il percorso di output, le dimensioni, il codec, la modalità di acquisizione, la frequenza, il motivo di arresto, gli avvisi facoltativi frameArtifactse .

Limitazione nota: la registrazione di un elemento specifico all'interno di un popup che esegue il rendering nella propria finestra di primo livello (riquadro a comparsa WinUI/XAML, suggerimento per l'insegnamento, descrizione comando) può invece acquisire la finestra principale sottostante. Registrare l'intera finestra o usarla ui screenshot --capture-screen per i popup. Rilevato nel numero 646.

Per la documentazione completa, vedere docs/ui-automation.md.