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
• --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)

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

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.

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.

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

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

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.

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-folder> [options]

Argomenti:

• input-folder - Directory contenente l'app da eseguire (obbligatorio)

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

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:

<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

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

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 package.json e l'oggetto winmds.lock.json scritto dall'ultimo winapp restore, quindi genera associazioni tipate .js + .d.ts in winapp.jsBindings.winapp/bindings/
• Non modificapackage.json : è un rigeneratore passivo. L'aggiunta del winapp.jsBindings blocco e della dipendenza di runtime si verifica durante winapp init l'abilitazione @microsoft/dynwinrt 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 la finestra di destinazione , o l'area di un singolo elemento, in un video H.264 MP4. I fotogrammi vengono acquisiti tramite Windows Acquisizione grafica (con fallback PrintWindow) e codificati in modo incrementale con Media Foundation, quindi le registrazioni lunghe non memorizzano mai nel buffer in memoria.

# 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

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).

Con --json, genera una UiRecordResult busta che include l'output path, frames, width, height, fileSize, (codec"h264") e mode , ovvero il percorso di acquisizione effettivamente usato (wgc, printwindowo screen).

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.