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

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

Rilevamento automatico del progetto .NET:

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)

winapp pack <input-folder> [options]

Argomenti:

• input-folder - Directory contenente i file dell'applicazione da creare nel pacchetto

Opzioni:

• --output <filename> - Nome file MSIX di output (impostazione predefinita: <name>_<version>_<arch>.msix, il fallback a <name>_<version>.msix, <name>_<arch>.msixo <name>.msix quando non è possibile determinare la versione/arch)
• --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> - Nome Publisher per la generazione di certificati
• --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 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.yaml creazione di pacchetti, winapp pack 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

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 node_modules), electron.exe 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> - CN Publisher (impostazione predefinita: CN=<utente corrente>)
• --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. È 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. 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> - Nome Publisher per il certificato
• --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 AppxMetadata\CodeIntegrity.cat durante la firma di un pacchetto MSIX, ma genera un catalogo esterno da usare con la creazione di pacchetti di percorsi di tipo sparse/esterno.signtool.exe

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

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.

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)
• 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)
• set-value - Impostare il valore sull'elemento modificabile (testo, numero)
• 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)

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