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 del progetto selezionata o directory corrente se non viene rilevato alcun progetto)
  • --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-lib, winui-unittest, o un modello sperimentale di Reattore, reactor ad esempio o reactor-mvu). Convalidato in base al pacchetto installato in fase di esecuzione; eseguire winapp new --list per visualizzare tutto. Impostazione predefinita: winui (app XAML 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:

Il pacchetto include due stili di app WinUI. I modelli XAML definiscono l'interfaccia utente nel markup con un code-behind C#. I modelli di Reattore sono C# puri senza XAML, usando un modello MVU (Model-View-Update). 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:

Nome breve Descrizione
winui App XAML vuota minima (creazione di pacchetti MSIX)
winui-navview App iniziale xaml NavigationView
winui-tabview App di avvio TabView XAML
winui-mvvm App MVVM XAML (CommunityToolkit.Mvvm)
winui-lib Libreria di classi WinUI 3
winui-unittest App MSTest in pacchetto; i test vengono eseguiti al momento dell'avvio
reactor Sperimentale. App Reactor vuota : pura C#, senza XAML
reactor-mvu Sperimentale. App Reactor che illustra il modello MVU
reactor-navview Sperimentale. App di avvio Reactor NavigationView
reactor-tabview Sperimentale. App iniziale Reactor TabView

I modelli di reattore sono sperimentali. Fanno riferimento ai pacchetti in versione non definitiva Microsoft.UI.Reactor , le cui API possono cambiare o essere rimosse in una versione futura. winapp new le contrassegna (sperimentale) in --list e nella selezione interattiva, imposta "Experimental": true in --jsone stampa un avviso dopo lo scaffolding di uno. Non vengono mai scelti come modello predefinito. Reactor richiede anche l'SDK .NET 10 o versione successiva. In un SDK winapp new meno recente si verifica un errore prima della versione necessaria anziché eseguire lo scaffolding di un progetto che non è possibile compilare.

Il nome breve canonico di ogni modello è il primo elenco di alias dotnet new . Viene accettato anche qualsiasi alias elencato , ad esempio winui3, wasdk-single, winui-reactor. 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.

Una prima esecuzione potrebbe richiedere più tempo: L'installazione o l'aggiornamento del pacchetto modello o il ripristino di pacchetti NuGet mancanti SDK per app di Windows usati dal modello selezionato possono richiedere download aggiuntivi. Questa situazione può verificarsi anche dopo la pubblicazione di una nuova versione SDK per app di Windows. Se lo scaffolding è ancora in esecuzione dopo 10 secondi, winapp new aggiorna il messaggio di stato per indicare che i pacchetti potrebbero essere scaricati o ripristinati.

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

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

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

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

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

restaurare

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

winapp restore [base-directory] [options]

Argomenti:

  • base-directory - Directory da ripristinare (impostazione predefinita: directory corrente). Seleziona anche da dove winapp.yaml e nuget.config vengono letti a meno che non --config-dir ne esegua l'override.

Opzioni:

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

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

Annotazioni

Per i progetti .NET non winapp.yaml è disponibile, ovvero le versioni dell'SDK sono attive come PackageReference voci in , quindi vengono eseguite winapp restoredotnet restore per l'utente .csproj .

Esempi:

# Restore from winapp.yaml in current directory
winapp restore

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

Feed NuGet personalizzati e privati:

winapp init, restoree update scaricano i pacchetti Windows SDK e SDK per app di Windows tramite NuGet, rispettando la gerarchia standardnuget.config. Feed privati e mirror, credenziali di feed (inclusi i provider di credenziali) e un tutto personalizzato globalPackagesFolder funziona come funzionano per dotnet restore. Per eseguire il ripristino esclusivamente dal proprio mirror, <clear /> le origini ereditate e aggiungere solo il proprio:

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

Annotazioni

Per i nuget.config progetti nativi winapp viene risolto dalla directory su cui opera: l'argomentorestoreinit/della directory, --config-dir se specificato, altrimenti la directory corrente. Per .NET progetti le origini provengono invece dalla gerarchia nuget.config del progetto, perché è ciò che dotnet add package e dotnet restore usano, quindi inserire la configurazione di un feed privato nella directory del progetto o in un predecessore. Un --config-dir oggetto esterno a tale gerarchia viene segnalato e ignorato anziché selezionare automaticamente le versioni che il progetto non può ripristinare. Eseguire questi comandi solo sulle directory attendibili, la stessa cautela che si applica a dotnet restore. Quando sono configurate più origini, usare Mapping origine pacchetti per aggiungere ogni pacchetto a un feed.

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 un progetto o directory di applicazioni 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 un singolo .csproj elemento per compilare il progetto e crearne il pacchetto in un unico passaggio (modalità progetto, vedere Creazione di pacchetti di un progetto direttamente sotto). 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 - Singolo .csproj oggetto da compilare e creare un pacchetto (modalità progetto) o 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
  • --no-sign - Recapitare il pacchetto senza firma, eseguendo l'override di qualsiasi configurazione di firma del progetto, ad esempio per l'invio nello Store o una pipeline di firma esterna. Non può essere combinato con --cert o --generate-cert.
  • --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.

opzioni in modalità Project (richiedono un .csproj input; rifiutate per input di cartella/bundle/manifesto):

  • --configuration <name> (-c) - Configurazione della compilazione (impostazione predefinita: Release)
  • --arch <arch> - Architettura di destinazione: x64, arm64o x86 (impostazione predefinita: architettura del processo corrente)
  • --framework <tfm> (-f) - Moniker del framework di destinazione per progetti con più destinazioni
  • --no-build - Creare un pacchetto dell'output di compilazione esistente senza ricompilare
  • --no-restore - Ignorare il ripristino del progetto prima della compilazione
  • --property <name=value> (-p) - Proprietà MSBuild inoltrata per la compilazione e la valutazione (ripetibile)

Nota: Per un progetto WinUI/ EnableMsixTooling.csproj (modalità progetto con strumenti MSIX), il SDK per app di Windows è proprietario del manifesto, del punto di ingresso e della generazione PRI, quindi --manifest, --executablee --skip-pri vengono rifiutati, configurare , il punto di ingresso del progetto e la relativa compilazione <AppxManifest>delle risorse nel progetto stesso. Queste tre opzioni si applicano ancora agli input delle cartelle e alla modalità di progetto generica (non MSIX-tooling). .csproj

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

Creazione diretta del pacchetto di un progetto

Quando l'input è un singolo .csproj, winapp pack compila il progetto (usando le opzioni precedenti) e crea un pacchetto dell'output risultante, senza dover compilare separatamente o individuare prima la cartella di output. Questo rispecchia winapp runla modalità di progetto.

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

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

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

L'architettura di destinazione proviene da --archo da un solitario -p RuntimeIdentifier=<rid> quando non si passa --arch (l'esatto RID viene mantenuto e guida la compilazione). Il passaggio di e --arch-p RuntimeIdentifier è un conflitto e viene rifiutato.

Il progetto deve essere compilato come app in pacchetto (EnableMsixTooling=true con un Package.appxmanifest). Un progetto compilato come app non in pacchetto (WindowsPackageType=None) non ha un manifesto MSIX per creare un pacchetto e winapp pack segnala un errore eseguibile. Gli input di cartelle, aggregazioni e manifesti di tipo sparse sono invariati.

Project modalità produce un'unica .msix architettura o solo architettura .msixbundle (vedere Bundle con più architetture). Non produce archivi di caricamento dello Store o bundle di suddivisione delle risorse (lingua/scalabilità): un pacchetto esplicito -p UapAppxPackageBuildMode=StoreUpload o -p AppxBundleAutoResourcePackageQualifiers=... viene rifiutato con una nota per eseguire il comando nativo per la creazione di pacchetti SDK direttamente per tali flussi.

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 un DN X.500 con componenti delimitati da virgole con valori singoli (rdn multivalore + e barre rovesciate non sono supportati); 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:

Segnaposto nel manifesto

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

Segnaposto Risolto a Esempio
$targetnametoken$ Nome eseguibile senza estensione Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Sempre risolto automaticamente

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 file deve dichiarare le proprie dimensioni, tramite un viewBox attributo o assoluto width e height , una larghezza percentuale senza viewBox descrivere alcuna dimensione specifica. Un'origine che dichiara nessuno dei due viene rifiutato con SVG image has no usable dimensions invece di produrre asset vuoti.

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 tre 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.
  • Modalità a file singolo: l'input è un'app .csbasata su file .NET. winapp run lo compila, genera un manifesto dalle relative #:property direttive e lo avvia con l'identità del pacchetto.

Tip

La selezione della modalità è invisibile all'utente per impostazione predefinita. Se una directory è stata considerata come una cartella di output di compilazione quando si prevede che venga compilata come progetto, eseguire di nuovo con --verbose : la modalità cartella segnala il motivo per cui è stato scelto (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Una directory viene compilata come progetto solo quando un oggetto .csproj/.slnx/.slncon un'app eseguibile si trova al livello superiore. Non viene eseguita la ricerca in modo ricorsivo.

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'app .cs basata su file .NET (modalità file singolo), un .csproj progetto, una .sln/.slnx soluzione o una directory contenente uno di questi 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 layout libero (impostazione predefinita: AppX all'interno della cartella di input). Il layout predefinito rimuove i file non più nella compilazione; una directory personalizzata mantiene file aggiuntivi. Usare una nuova directory personalizzata quando è necessario un layout pulito.
  • --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. Raramente necessario: un'app con OutputType=Exe già avviato in questo modo per impostazione predefinita. winapp aggiunge il necessario uap5:ExecutionAlias al manifesto che esegue le fasi nel layout AppX, quindi non è necessaria alcuna modifica al manifesto archiviato; viene usato un alias che l'app dichiara se stessa as-is. Non è possibile combinare con --no-launch, --detach, --without-aliaso --json.
  • --without-alias - Forzare l'attivazione AUMID per un'app che altrimenti viene avviata tramite un alias di esecuzione. Un'app console viene quindi eseguita senza una console e non stampa nulla in questo terminale. Non è possibile combinare con --with-alias.
  • --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. Le esecuzioni locali stampano il PID; le esecuzioni di destinazione stampano la destinazione dell'interfaccia utente con ambito. JSON include il PID e l'ambito di destinazione. 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.
  • --on <target> - Compilare nell'host, quindi registrare ed eseguire nella destinazione. Attualmente supporta sandbox, senza fallback all'esecuzione locale. Usare --detach prima dei comandi dell'interfaccia utente di completamento. Sandbox --debug-output richiede un'app in pacchetto. Vedi Windows esecuzione sandbox per la configurazione, il supporto del runtime e la durata delle app scollegate.

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

AOT nativo: aggiungere questo gruppo di proprietà all'interno dell'elemento del <Project> file project, quindi aggiungere --aot:

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

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

--aot supporta progetti x64 e ARM64. Viene eseguito dotnet publish con la configurazione AOT del progetto, quindi avvia l'output. Usare -p PublishAot=true per un override monouso. Non esegue una certificazione di runtime separata e non può essere combinata con --no-build o --manifest.

Per le app che usano l'identità del pacchetto senza un layout MSIX generato, includere Package.appxmanifest o appxmanifest.xml nell'output di pubblicazione del progetto. Winapp esegue le fasi dei file pubblicati con tale manifesto. Se sono presenti entrambi i nomi, winapp si arresta invece di sceglierne uno; rimuovere il manifesto non aggiornato e configurare il progetto per pubblicare solo il manifesto previsto.

opzioni in modalità Project (ignorate in modalità cartella, a meno che non sia specificato):

  • -c, --configuration <name> - Configurazione della compilazione. Impostazione predefinita: Debug. (Rispettato anche in modalità file singolo).
  • --arch <x64|arm64|x86> - Architettura di destinazione. Impostazione predefinita: architettura del processo corrente. Determina il RID di compilazione e l'architettura di runtime di app di Windows e seleziona un profilo di pubblicazione dipendente dalla piattaforma corrispondente quando richiesto dalla compilazione effettiva. (Rispettato anche in modalità file singolo).
  • -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 --arch e può selezionare il profilo di pubblicazione richiesto. Viene rispettato anche in modalità file singolo, in cui esegue l'override di un #:property RuntimeIdentifier oggetto dichiarato dal file.
  • -f, --framework <tfm> - Moniker del framework di destinazione per i progetti con più destinazioni ( ad esempio net10.0-windows10.0.26100.0). (Rifiutato in modalità file singolo - usare #:property TargetFramework=....)
  • --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). (Rifiutato in modalità a file singolo: un'app .cs basata su file è il progetto).
  • --no-build - Ignorare la compilazione ed eseguire l'output di compilazione esistente (valuta comunque le proprietà di output). (Rispettato anche in modalità file singolo).
  • --no-restore - Ignorare il ripristino prima della compilazione o della pubblicazione AOT nativa. (Rispettato anche in modalità file singolo).
  • --aot- Eseguire il progetto configurato .NET pubblicazione AOT nativa. Richiede un valore effettivo PublishAot=true. Rifiutata nelle modalità cartella e a file singolo.
  • -p, --property <Name=Value> - Proprietà MSBuild inoltrata sia alla compilazione che alla valutazione della proprietà. Ripetere -p per più proprietà; utilizzare %3B o %2C per un punto e virgola letterale o una virgola in un valore. (Anche rispettato in modalità a file singolo, dove è l'unico modo per impostare TargetFramework.)

Output di compilazione e dettaglio: un'esecuzione di progetto normale usa dotnet build, quindi valuta l'output compilato. Ripristinare e compilare il flusso di output live, con le credenziali degli URL del feed autenticati elaborati. Con --aot, winapp usa dotnet publish; --verbose mostra il comando di pubblicazione e i percorsi risolti. Usare le opzioni di dettaglio seguenti per controllare ciò che viene mostrato:

Flag dotnet verbosity Aggiunge
(impostazione predefinita) minimal —
--verbose minimal Tracce delle decisioni di compilazione di winapp
--quiet quiet —

L'AOT nativo pubblica i flussi di output non appena arriva, inclusa la proprietà finale JSON di MSBuild. In --json, le chiamate di ripristino/compilazione e l'output figlio passano a stderr in modo che stdout rimanga json puro. In --quietle chiamate vengono eliminate e l'output di ripristino/compilazione non interattiva di dotnet viene instradato a stderr in modo che stdout rimanga pulito. L'output di pubblicazione AOT nativo passa anche a stderr in entrambe le opzioni.

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

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

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

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

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

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

Modalità file singolo (app basate su file .NET)

.NET 10 consente di eseguire un singolo .cs file senza file di progetto, configurandolo con #: direttive nella parte superiore. Puntare winapp run a tale file e compila l'app, genera un appxmanifest e la avvia con l'identità del pacchetto , quindi Windows.ApplicationModel.Package.Current funziona, l'app ottiene un AUMID reale e una voce del menu Start e le API che richiedono semplicemente l'identità (notifiche dell'app, ApplicationData, intelligenza artificiale sul dispositivo).

Le integrazioni della shell, ad esempio gestori di protocollo, associazioni di file, destinazioni di condivisione e attività di avvio richiedono una voce dichiarata <Extensions> , che il manifesto generato non contiene. Per aggiungerne uno, creare il proprio manifesto. Vedere Bring your own manifest di seguito.

winapp run counter.cs

In alternativa, eseguirlo con semplicità dotnet run : vedi Esecuzione con dotnet run di seguito.

Non si crea un manifesto. Descrivere invece il pacchetto con #:property direttive:

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

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

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

Proprietà del manifesto. Tutti sono facoltativi; ogni fallback a un valore predefinito ragionevole:

Proprietà Set Default
WinAppPackageName Identity/@Name (identità del pacchetto) il nome del file, sanificato in [-.A-Za-z0-9], più un breve hash del percorso del file (counter.cs → counter-a1b2c3d4)
WinAppDisplayName Nome visualizzato in Start e Impostazioni il nome del file senza l'estensione
WinAppPublisher Identity/@Publisher CN=<your Windows user name>. Un nome bare viene sottoposto a wrapping come CN=<name>.
WinAppVersion Identity/@Version $(Version), normalizzato (vedere di seguito)
WinAppDescription Descrizione mostrata durante l'installazione e in Impostazioni nome visualizzato
WinAppCapabilities Funzionalità per dichiarare, separati da ; o , none

Version. Una versione del pacchetto deve essere esattamente quattro numeri, ogni 0-65535. WinAppVersion (oppure, se non lo si imposta, la proprietà standard Version ) viene normalizzata in modo da adattarsi: -preview/-rc il suffisso viene eliminato e i componenti mancanti vengono riempiti con zeri, quindi #:property Version=1.2.3-preview.4 diventa 1.2.3.0 e imposta la versione dell'assembly e la versione del pacchetto insieme. Un valore che non può essere impostato per adattarsi, ovvero un componente superiore a 65535 o più di quattro componenti, viene rifiutato con un errore anziché modificato automaticamente.

Capabilities

L'app esegue l'attendibilità totale con l'identità, che soddisfa le API che richiedono solo un'app in pacchetto. Tuttavia, alcune API vengono gestite in base a una funzionalità dichiarata indipendentemente dal fatto che le API di intelligenza artificiale Windows sono il caso comune. Le integrazioni della shell, ad esempio i gestori di protocolli e le associazioni di file, sono un terzo caso: le voci create <Extensions> devono essere create, non una funzionalità, quindi usare il proprio manifesto .

#:property WinAppCapabilities=systemAIModels

Ovvero tutte le API Phi Silica e le altre API del modello su dispositivo necessarie dal manifesto. Dichiarare diversi elementi separandoli:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

Winapp scrive ognuno di essi nello spazio dei nomi XML e dell'elemento che richiede effettivamente, dichiara tale spazio dei nomi e genera MaxVersionTested quando la funzionalità richiede una versione più recente. Questo aspetto conta più di quanto sembri: le funzionalità sono distribuite tra diversi elementi e lo stesso elenco sopra diventa tre forme diverse :

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

I nomi che winapp sa sono scritti automaticamente. Per qualsiasi altra cosa, il set con restrizioni cresce nel tempo, qualificarlo con il prefisso dello spazio dei nomi:

Prefisso Genera
rescap: <rescap:Capability> — funzionalità limitate
uap:, uap6:, uap7:uap11: <uap*:Capability>
systemai: <systemai:Capability>
device: <DeviceCapability>
app: <Capability> nello spazio dei nomi predefinito 
#:property WinAppCapabilities=rescap:broadFileSystemAccess

Un nome bare non riconosciuto viene rifiutato con un errore che denomina questi prefissi, invece di indovinare, una funzionalità generata nello spazio dei nomi sbagliato produce un manifesto Windows rifiuta di registrarsi o accettare mentre non lo concede invisibile all'utente.

Bring your own manifest

Se sono necessarie proprietà che non coprono, ovvero un gestore di protocollo, un'associazione di file, un alias di esecuzione, creare un manifesto e winapp run usarlo verbatim invece di generarne uno. Viene prelevato da, in ordine:

  1. --manifest <path> nella riga di comando.
  2. #:property WinAppManifestPath=<path> .cs nel file.
  3. Manifesto seduto accanto al .cs file, denominato <filename>.appxmanifest (ad esempio counter.appxmanifest accanto a counter.cs).

Solo il nome per file viene prelevato automaticamente. Un Package.appxmanifest oggetto o appxmanifest.xml nella stessa cartella viene deliberatamente ignorato. Diversi .cs file possono condividere una cartella e l'adozione di un nome condiviso eseguirà automaticamente un'app con l'identità di un altro. Per usare un manifesto per diversi file, denominarlo in modo esplicito con --manifest o WinAppManifestPath.

In caso contrario, viene generato un oggetto Package.appxmanifest nell'output di compilazione, insieme agli asset di immagine predefiniti e aggiornato in ogni esecuzione.

Options. Ogni opzione in modalità cartella funziona: --no-launch, --with-alias--without-alias, , --detach, --clean, --debug-output--unregister-on-exit--args----json--manifest--executable/--symbols, -c/--configuration--no-build--output-appx-directory--no-restoree .-p/--property

Tip

Per impostazione predefinita, un'app console viene stampata nel terminale. Un'app in pacchetto avviata tramite AUMID non ha console, quindi un'app solo console viene eseguita correttamente e non viene stampato nulla. Winapp evita che: un'app con OutputType=Exe viene avviata tramite un alias di esecuzione, che eredita invece stdin/stdout/stderr del terminale. Si ottiene comunque l'identità del pacchetto e non è necessario richiederla:

winapp run counter.cs

Passare --without-alias per forzare l'attivazione AUMID. L'app viene quindi eseguita senza una console e non stampa nulla qui. Un'app con finestra (WinExe) mostra una finestra, quindi mantiene l'attivazione AUMID; passa --with-alias se vuoi che uno in questo terminale sia comunque. Per correggere la scelta nel file anziché in ogni riga di comando, impostare la stessa proprietà .csproj utilizzata da :

#:property WinAppRunUseExecutionAlias=false

L'alias winapp dichiara è denominato dopo il nome della famiglia di pacchetti, con un winapp- prefisso , quindi com.contoso.counter pubblicato da CN=You ottiene .winapp-com.contoso.counter_gspb8g6x97k2t.exe Tale parte finale è l'hash dell'editore Windows deriva, quindi due app che condividono un nome in server di pubblicazione diversi ottengono ancora alias diversi. Il prefisso mantiene il nome chiaro dei comandi reali: un'app in python.cs ottiene un winapp-… alias, mai python.exe. Se si crea il proprio manifesto, l'alias dichiarato viene usato as-is e winapp non aggiunge nulla.

Questo vale solo per l'alias. La registrazione stessa viene inserita nel nome del pacchetto, quindi l'esecuzione di una seconda app che dichiara lo stesso WinAppPackageName sotto un editore diverso sostituisce la prima registrazione anziché essere seduta accanto a essa. Assegnare a ogni app il proprio nome se si vuole registrare entrambi contemporaneamente.

winapp run stampa l'alias registrato, quindi non è necessario calcolare l'hash per trovarlo.

L'alias è un comando sul percorso che dura finché il pacchetto rimane registrato. Se un altro pacchetto possiede già il nome, winapp lo dice. Quando ha dedotto l'alias per te viene avviato tramite AUMID, invece di avviare l'app sbagliata; quando hai chiesto esplicitamente , con --with-alias o #:property WinAppRunUseExecutionAlias=true , non riesce invece di fare tranquillamente qualcos'altro.

Due opzioni in modalità progetto non si applicano, perché un'app basata su file si configura. Vengono rifiutati con un messaggio che denomina la direttiva da usare:

Opzione Usare invece
-f/--framework #:property TargetFramework=net10.0-windows10.0.22621.0
--project nothing — il .cs file è il progetto

--arch e -r/--runtime funzionano come fanno in modalità progetto. Quando non si passano neanche le build winapp per l'architettura del computer, che è ciò che un'app SDK per app di Windows indipendente richiede, perché senza di essa viene compilata AnyCPU l'SDK e ha esito negativo con WindowsAppSDKSelfContained requires a supported Windows architecture. Un #:property RuntimeIdentifier=win-arm64 oggetto nel file viene rispettato; ne viene eseguito l'override esplicito/--arch--runtime.

Il pacchetto e l'annullamento del pacchetto funzionano entrambi, rilevati esattamente WindowsPackageType come in modalità progetto: l'impostazione predefinita registra un layout libero e la avvia con l'identità, mentre #:property WindowsPackageType=None compila l'app, installa la corrispondenza app di Windows Runtime e avvia direttamente ..exe Un'app in pacchetto viene avviata tramite l'alias di esecuzione o tramite l'attivazione AUMID. Vedere la nota della console precedente. Tale scelta è separata dal fatto che sia in pacchetto. Le opzioni di identità (--no-launch, --with-alias, --clean--without-alias, --unregister-on-exit, --manifest) --output-appx-directorysi applicano solo alle app in pacchetto.

Esecuzione con dotnet run

Non è necessario digitare winapp affatto. Fare riferimento al Microsoft.Windows.SDK.BuildTools.WinApp pacchetto dal file e si dotnet run ottiene lo stesso avvio in pacchetto:

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

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

dotnet run counter.cs

Le destinazioni MSBuild del pacchetto reindirizzeranno l'esecuzione a winapp, che pacchetti, registra e avvia l'app dotnet run appena compilata, non viene ricompilata. La gestione del manifesto è invariata: winapp lo risolve esattamente come per winapp run, quindi #:property WinAppManifestPath=… un <filename>.appxmanifest accanto .cs a sono entrambi onorati (vedere Bring your own manifest), un'entità a livello Package.appxmanifest di directory viene comunque ignorata e in caso contrario ne viene generata una dalle #:property direttive e aggiornata ogni esecuzione.

Per il reindirizzamento devono essere presenti due condizioni:

Direttiva Perché
#:package Microsoft.Windows.SDK.BuildTools.WinApp@* le destinazioni che eseguono la spedizione di reindirizzamento in questo pacchetto
#:property TargetFramework=net10.0-windows… un file normale net10.0 viene lasciato da solo, quindi viene eseguito senza pacchetti

L'aggiunta #:property WindowsPackageType=None lascia anche il file da solo: dotnet run quindi esegue .exe direttamente, senza identità. Usare winapp run per il percorso non in pacchetto se si vuole che il runtime di app di Windows corrispondente sia installato per primo.

Impostare #:property EnableWinAppRunSupport=false per rifiutare esplicitamente il reindirizzamento completamente e le WinAppRun* proprietà descritte in Configurazione per modellare l'avvio, ad esempio:

#:property WinAppRunUnregisterOnExit=true

Se dotnet run esegue l'app senza pacchetti quando si prevede l'identità, chiedere a MSBuild perché. Usare dotnet build, non dotnet msbuild : esegue solo dotnet build la sintesi del progetto virtuale tramite cui viene compilata un'app basata su file:

dotnet build counter.cs -t:WinAppRunSupportInfo

La modalità a file singolo richiede .NET SDK 10.0.300 o versione successiva.

La registrazione ha una versione finale dell'esecuzione. winapp run counter.cs lascia il pacchetto registrato dopo l'uscita dall'app, esattamente come la modalità cartella e il progetto, quindi LocalState sopravvive e riesegui lo stesso file riutilizza la stessa identità invece di accumulare registrazioni. winapp dice che la prima volta che registra un'app e winapp unregister accetta se .cs stessa:

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

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

winapp unregister counter.cs non richiede alcun percorso manifesto: valuta i valori del #:property file allo stesso modo run e rimuove solo un pacchetto registrato dall'output di compilazione del file. Un'app con lo stesso nome registrata da una cartella diversa viene rifiutata a meno che non passi --force. Se l'esecuzione usa un'opzione che forma l'identità o il layout, passare lo stesso elemento a unregister:

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

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

-p esegue l'override delle direttive del file e un accanto Directory.Build.props a .cs può disattivare WinAppPackageName$(Configuration) o $(RuntimeIdentifier) , in modo che ognuno di questi possa modificare il pacchetto registrato.

Dopo aver pulito l'output temporaneo dell'SDK, winapp unregister counter.cs non è più possibile confermare che la registrazione proviene da tale file e ignorarla, usare winapp unregister --prune per cancellare le registrazioni i cui file sono andati o --force per rimuovere uno specifico in ogni caso. Se l'esecuzione usa --output-appx-directory, passare la stessa directory a unregister in modo che possa riconoscere il layout.

Lo stesso vale per un percorso di output personalizzato: la proprietà viene confermata dal layout standard <root>\bin\<configuration> dell'SDK, quindi un'esecuzione compilata con -p OutputPath=<somewhere-else> non può essere confrontata con il relativo file di origine. unregister ignora la directory invece di indovinare in una directory più ampia, assegnare un nome al layout con --output-appx-directoryo usare --force.

Esempi di file singolo:

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

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

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

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

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

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

# Remove the package it registered
winapp unregister counter.cs

Annotazioni

L'identità predefinita include un breve hash del percorso del file, counter.cs diventa simile counter-a1b2c3d4 a , quindi due counter.cs file in cartelle diverse sono app diverse e mantengono le proprie impostazioni e LocalState. L'hash è derivato dal percorso, quindi sopravvive alle modifiche e alle riesezioni e cambia solo se si sposta il file. Impostare #:property WinAppPackageName=<name> per scegliere manualmente un'identità stabile; viene normalizzata in base a ciò che Identity/@Name consente: i caratteri esterni [-.A-Za-z0-9] vengono eliminati, i nomi più brevi di 3 caratteri vengono riempiti con 1e il risultato è limitato a 50 caratteri, quindi My App registra come MyApp. In entrambi i casi, il menu Start e Le impostazioni mostrano WinAppDisplayName (impostazione predefinita: il nome del file), non l'identità. L'identità ha sempre come ambito l'account utente, quindi non si scontra mai con un altro utente nello stesso computer.

Proprietà di MSBuild (pacchetto NuGet):

Quando si usa il pacchetto NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run richiama automaticamente winapp run.

Tutto ciò che viene scritto dopo dotnet run viene passato all'applicazione, esattamente come sarebbe senza il pacchetto. Configurare l'utilità di avvio con le proprietà di MSBuild seguenti:

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

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

Per controllare il .csproj comportamento, è possibile impostare le proprietà MSBuild seguenti:

Proprietà Default Descrizione
EnableWinAppRunSupport true Abilitare/disabilitare la funzionalità di supporto per l'esecuzione
WinAppLaunchArgs (vuoto) Argomenti da passare all'app all'avvio
WinAppRunUseExecutionAlias dedotto dall'app Avviare tramite alias di esecuzione invece dell'attivazione AUMID. Lasciato non impostato, winapp lo deduce: un'app console usa un alias in modo che l'output raggiunga il terminale, un'app con finestra usa AUMID. Impostare true o false per decidere autonomamente.
WinAppRunNoLaunch false Registra solo l'identità senza avviare
WinAppRunDebugOutput false Acquisire OutputDebugString messaggi ed eccezioni first-chance. È possibile collegare un solo debugger alla volta (impedisce VS/VS Code). Usare WinAppRunNoLaunch invece per collegare un debugger diverso.
WinAppRunDetach false Tornare immediatamente dopo l'avvio anziché attendere l'uscita dell'app. Stampa il PID.
WinAppRunUnregisterOnExit false Annullare la registrazione del pacchetto di sviluppo dopo l'uscita dall'app
WinAppRunClean false Rimuovere i dati dell'applicazione del pacchetto esistente (LocalState, settings) prima di ridribuirli
WinAppRunSymbols false Scaricare i simboli dal server dei simboli di Microsoft per un'analisi più completa degli arresti anomali nativi. Ha solo un effetto con WinAppRunDebugOutput.
WinAppRunExecutable (vuoto) Percorso eseguibile relativo alla cartella build-output. Usare quando il manifesto contiene $targetnametoken$ e la cartella di output ha più di un .exeoggetto .
WinAppRunArgs (vuoto) Argomenti non elaborati accodati alla winapp run riga di comando, per le opzioni senza proprietà dedicata , ad esempio --verbose. Accodato dopo ogni proprietà precedente.

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:

Proprietà Non può essere combinato con
WinAppRunNoLaunch WinAppRunDetach, WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias è deliberatamente non in tale elenco, in entrambe le direzioni. false chiede l'attivazione AUMID, che non viene avviata e scollegata già; true non viene semplicemente applicato quando uno dei due è impostato, perché un alias di esecuzione richiede un processo monitorato ed in esecuzione. Quindi un progetto che esegue ancora il controllo <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> in viene eseguito correttamente in dotnet run -p:WinAppRunDetach=true, avvio tramite AUMID anziché esito negativo.

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

Argomenti:

  • input- Percorso di un'app basata su file .NET (un singolo .cs) il cui pacchetto deve essere annullato. La sua identità viene risolta allo stesso modo winapp run , da un manifesto creato se l'app ne ha uno, altrimenti dai relativi #:property valori, quindi non è necessario alcun percorso manifesto. Omettere di usare --manifest o rilevare automaticamente un manifesto nella directory corrente. Non può essere combinato con --manifest, che denomina il pacchetto in modo diverso e può risolverne uno diverso.

Opzioni:

  • --manifest <path> - Percorso di Package.appxmanifest (impostazione predefinita: rilevamento automatico dalla directory corrente)
  • --force - Solo per annullare la registrazione locale, ignorare il controllo della directory install-location e annullare la registrazione anche se il pacchetto è stato registrato da un albero del progetto diverso. Viene rifiutato con --on; i controlli di proprietà di destinazione non possono essere ignorati.
  • --on <target> - Rimuovere la registrazione di sviluppo winapp-owned corrispondente da , non da sandboxquesto computer. Richiede un manifesto e non supporta --force. Vedi Pulizia dell'app sandbox.
  • --prune - Rimuovere ogni registrazione in modalità di sviluppo i cui file non sono più disponibili. Non può essere combinato con un input, --manifest, --configuration--property, --arch, --runtimeo --output-appx-directory.
  • -p, --property <Name=Value> - Proprietà MSBuild usata per la risoluzione dell'identità di un'app .cs basata su file. Ripetibile. Passare le stesse proprietà che influiscono sull'identità dell'esecuzione usata ,ad esempio -p WinAppPackageName=..., perché una proprietà della riga di comando esegue l'override delle direttive del #:property file. Si applica solo a un .cs input.
  • -c, --configuration <name> - Configurazione di compilazione usata per la risoluzione dell'identità di un'app .cs basata su file. Impostazione predefinita: Debug. Passare la stessa configurazione usata: un accanto Directory.Build.props.cs a può impostare WinAppPackageName o WinAppManifestPath in modo condizionale su $(Configuration). Si applica solo a un .cs input.
  • --arch <x64|arm64|x86> - Architettura di destinazione usata per la risoluzione dell'identità di un'app .cs basata su file. Impostazione predefinita: architettura del processo corrente. Passare la stessa architettura usata dall'esecuzione, poiché l'identità può anche essere keyed off $(RuntimeIdentifier). Si applica solo a un .cs input.
  • -r, --runtime <rid>- Specificare come destinazione .NET identificatore di runtime (ad esempio win-x64) usato per la risoluzione dell'identità di un.cs'app basata su file. Viene usata solo l'architettura ed esegue l'override di --arch. Si applica solo a un .cs input.
  • --output-appx-directory <path> - Directory del layout AppX da cui è stato registrato il pacchetto. È necessario solo quando l'esecuzione è stata usata --output-appx-directory, poiché nulla nei record del pacchetto che eseguono l'opzione ha prodotto il relativo layout.
  • --json - Formattare l'output come JSON

Risultato:

  • Determina il nome del pacchetto, dall'identità .cs risolta del file o leggendo il 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 pacchetto appartenga all'app denominata (a meno --forceche ) , il percorso di installazione deve restare in una directory identificata: l'output .cs di compilazione del file, la directory del manifesto, la directory corrente o un oggetto esplicito --output-appx-directory. Un pacchetto il cui percorso di installazione non può essere risolto (i relativi file sono stati eliminati) viene ignorato, perché l'identità da sola non è una prova di proprietà: due app che impostano #:property WinAppPackageName=counter entrambi registrano la stessa identità da cartelle diverse. Usare --prune per cancellare le registrazioni i cui file non sono più disponibili.
  • Annulla la registrazione dei pacchetti corrispondenti

Pulizia delle registrazioni non recapitabili (--prune):

Una registrazione sopravvive ai relativi file. Eliminare un output di compilazione, un albero del progetto o (per un'app basata su file) consentire Windows pulire %LOCALAPPDATA%\Tempe il pacchetto rimane registrato: Windows mantiene l'identità e la relativa voce di menu Start, ma l'attivazione non esegue alcuna operazione invisibile all'utente. Questi si accumulano invisibilmente.

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

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

Vengono considerate solo le registrazioni in modalità di sviluppo e ognuna viene rimossa dal nome completo del pacchetto, quindi un pacchetto con lo stesso nome ancora installato da una posizione dinamica non viene modificato. Il prompt esiste perché un percorso di installazione mancante è in genere una cartella eliminata, ma descrive anche un pacchetto registrato da una condivisione di rete disconnessa o da un'unità rimovibile, esaminare l'elenco prima di confermare.

Esempi:

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

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

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

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

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

# JSON output for scripting
winapp unregister --json

cert

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 il certificato publisher dal manifesto.Identity/@Publisher Solo l'autore è obbligatorio, quindi un manifesto parzialmente completo funziona ancora. Se il manifesto non dispone di un server di pubblicazione utilizzabile, il comando non riesce invece di sostituire un valore predefinito, in modo che il certificato non possa mai non essere invisibile all'utente corrispondente al manifesto.
  • --publisher <name>- Publisher per il certificato. Quando si genera un certificato, questa opzione ha la precedenza su --manifest. Un valore vuoto in modo esplicito non riesce anziché usare l'autore del manifesto. Accetta un nome distinto X.500 completo (ad esempio, CN=Contoso, O=Contoso Ltd, C=US) o un nome bare che viene eseguito automaticamente come CN=<name>. I componenti devono essere a valore singolo e separati da virgole; RDN multivalore (CN=Foo+OU=Bar) e barre rovesciate non sono supportati perché il server di pubblicazione del manifesto MSIX non può rappresentarli. Un nome distinto in formato non valido (ad esempio CN= , o CN=A,,O=B) viene rifiutato con un'uscita diversa da zero e un errore che denomina il problema, anziché produrre un certificato che non possa mai corrispondere all'autore del manifesto.
  • --output <path> - Percorso del file di certificato di output (supporta percorsi assoluti e relativi)
  • --password <password> - Password del certificato (impostazione predefinita: password, nota pubblicamente, vedere Output JSON e Sicurezza)
  • --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": "..."}).

Output JSON:

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

publisher è il nome visualizzato e subjectName il nome distinto completo a cui è stato rilasciato il certificato. defaultPasswordIsPublic è sempre presente. Quando è true, l'oggetto .pfx è protetto da una password che chiunque può indovinare, quindi il certificato deve firmare solo le build che rimangono nei propri computer, controllarlo prima che uno script mani il certificato a qualsiasi altro elemento. warnings contiene la stessa divulgazione del testo e viene omesso quando non c'è nulla da segnalare. publicCertificatePath viene visualizzato solo con --export-cer.

Informazioni sul certificato

Visualizzare i dettagli del certificato da un file PFX o CER. 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 o CER)

Opzioni:

  • --password <password> - Password per il file PFX, ignorata per un cer pubblico (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> <cert-path> [options]

Argomenti:

  • file-path - Percorso del pacchetto MSIX o del file eseguibile da firmare
  • cert-path - Percorso del certificato di firma (pfx)

Opzioni:

  • --password <password> - Password del certificato (impostazione predefinita: "password")
  • --timestamp <url> - URL del server timestamp RFC 3161

Esempi:

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

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

az-sign

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

Verifica della firma

Gli strumenti di compilazione vengono scaricati da NuGet e quindi eseguiti, quindi winapp controlla ognuno di essi per ottenere una firma valida Microsoft Authenticode immediatamente prima di eseguirla. Il certificato deve denominare Microsoft Corporation come organizzazione di firma. Questo vale per ogni comando che esegue la shell a uno strumento SDK, tra cui tool, packagee sign. Uno strumento che non riesce il controllo non viene eseguito:

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

Un errore indica che il file su disco non è quello che Microsoft pubblicato, spesso un download danneggiato o parziale. Eliminare il pacchetto dalla cache NuGet ed eseguire di nuovo il comando in modo che winapp lo scarica nuovamente.

Winapp mantiene quindi aperto lo strumento finché viene eseguito, quindi il file controllato è il file Windows caricamento. Se non può contenere lo strumento sul posto, non viene eseguito neanche:

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

Chiudere qualsiasi cosa stia usando il file , ovvero un'analisi antivirus o un editor aperto è la causa consueta, ed eseguire di nuovo il comando. Se lo strumento non è più in uso, eliminare il pacchetto dalla cache NuGet in modo che winapp lo scarichi nuovamente.

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:

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

target

Eseguire comandi, copiare file, controllare lo stato o acquisire l'intero desktop guest.

Ogni verbo accetta sandbox come primo argomento. Ad eccezione di snapshot, questi comandi possono preparare o avviare la sandbox. Per informazioni su prerequisiti, autorizzazioni, ciclo di vita e ripristino, vedere Windows esecuzione della sandbox.

exec di destinazione

Eseguire un comando come utente guest.

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

Argomenti dopo -- aver mantenuto i limiti. I flussi standard e il codice di uscita del processo guest vengono inoltrati; questo non è un terminale completo. --json formatta gli errori di winapp in stderr senza modificare il stdout del comando figlio. Usare la struttura per error.code distinguere un errore di destinazione dallo stato di uscita di un'applicazione.

Un'interfaccia utente guest esplicita WINAPP_UI_WORKFLOW_ID raggruppa anche le chiamate dell'interfaccia utente guest effettuate dal comando. Vedere Coordinamento dell'interfaccia utente sandbox.

push di destinazione e pull di destinazione

Copiare un file o una directory nella direzione denominata dal verbo .

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

I percorsi di destinazione sono relativi all'area di lavoro gestita della destinazione; i percorsi di destinazione assoluti, rooted e UNC vengono rifiutati. Una destinazione file include il nome file. Vedere Esecuzione di comandi e copia di file per il layout della directory, la gestione dei collegamenti e l'esecuzione di uno script copiato.

snapshot di destinazione

Segnala idoneità, distribuzioni e finestre guest senza avviare una sandbox.

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

Non riconnette un client o ripristina un agente. Nessuna sandbox in esecuzione è un risultato positivo, non un errore. Vedere Analisi dell'ambiente sandbox per l'interpretazione degli ID di idoneità e processi.

screenshot di destinazione

Acquisire il desktop guest con le dimensioni in pixel native come png host, senza un selettore di app o bordi della finestra host. --json segnala l'origine della coordinata guest.

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

Usare ui screenshot --on sandbox -a <app> invece per una finestra dell'app. Vedere Screenshot e registrazioni per i requisiti del client, le limitazioni dello stato attivo e la gestione dell'output.

record di destinazione

Registrare il desktop guest in H.264 MP4. I file video e frame host arrivano al termine della registrazione; JSON e il manifesto del frame descrivono qualsiasi ridimensionamento o riempimento.

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

Usa le opzioni durata, frame, sovrascrittura e risultato di ui record, ma acquisisce il desktop anziché un'app. Preferisce un positivo --duration-sec per l'uso automatico dell'interfaccia della riga di comando. L'helper npm richiede durationSec. Vedere Acquisizione sandbox per gli errori parziali di prova e preparazione dell'acquisizione.

find-ui

Agent-first. find-ui viene creato principalmente per gli agenti di codifica di intelligenza artificiale, che consente a un agente di estrarre il markup WinUI dalle gallerie di spedizione invece di inventarlo e --json rende leggibile ogni risultato (e ogni errore). Funziona così bene tipizzato a mano.

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 corpora Gallery, Toolkit e Reactor viene fornito all'interno dell'interfaccia della riga di comando, quindi find-ui non funziona con accesso alla rete, incluso in una prima esecuzione in una sandbox agente o dietro un proxy aziendale che blocca raw.githubusercontent.com. Quando GitHub è raggiungibile, l'interfaccia della riga di comando viene aggiornata e memorizza nella cache il risultato per utente in <global .winapp>/cache/find-ui; il corpus predefinito è solo un pavimento, mai un soffitto. I dati memorizzati nella cache vengono aggiornati al massimo ogni 24 ore o su richiesta con --refresh.

Il corpus predefinito viene recuperato da GitHub ogni volta che viene compilata una versione stabile e un aggiornamento che non riesce arresta la build di rilascio anziché spedire tranquillamente i dati meno recenti. Il fornaio recupera attraverso lo stesso percorso --refresh di codice usa, quindi un errore significa che l'aggiornamento in tempo reale è interrotto troppo e vale la pena analizzare prima della spedizione. Una versione può comunque essere tagliata rispetto al corpus precedentemente sottoposto a commit, ma solo come override esplicito. Quando i risultati vengono serviti dalla copia predefinita del corpora Gallery/Toolkit/Reactor, find-ui dice così su stderr e --json output contiene "corpus": "embedded" (altri valori: "network" per un nuovo recupero, "cache" per la cache locale). Una richiesta di base - --source coreo un --id set che è tutti i modelli di base - report "embedded" troppo, perché i modelli di base curati vengono compilati nell'interfaccia della riga di comando e non vengono mai recuperati; non stampa alcun avviso di decadimento, perché --refresh non può modificarli. Il corpus campo viene segnalato ogni volta che i risultati sono stati serviti; è assente solo quando non è possibile caricare alcun corpus.

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

Correlato:find-ui cerca esempi winUI; usare find-api per eseguire ricerche nell'area API (tipi, membri, enumerazioni) di un progetto e winapp ui search per eseguire ricerche nell'albero dell'interfaccia utente di un'app in esecuzione .

find-api

Agent-first. find-api viene creato principalmente per gli agenti di codifica di intelligenza artificiale, perché il codice generato nell'API fa effettivamente riferimento a un progetto invece della raccolta del modello e --json più codici di uscita diversi da zero sui simboli mancanti consentono a un codegen di gate agente sulla risposta. Funziona così bene tipizzato a mano.

Cercare ed esaminare la superficie dell'API Windows/WinRT (tipi, membri, enumerazioni, spazi dei nomi) disponibili per un progetto, risolta dai metadati a cui si fa .winmd/.dll riferimento. Il modulo bare cerca; i verbi secondari analizzano un tipo specifico, uno spazio dei nomi o l'indice stesso.

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

L'indice viene compilato dai pacchetti NuGet/SDK ripristinati del progetto (tramite project.assets.json) al primo uso e aggiornati automaticamente quando il progetto viene ripristinato. Si trova nella cache globale .winapp (cache/find-api/) e viene condivisa tra i progetti. Ripristinare prima il progetto (winapp restore o dotnet restore).

Ogni corrispondenza viene elencata sotto lo spazio dei nomi con il pacchetto fornito e un riepilogo di una riga di ciò che fa, quindi un risultato è utilizzabile senza una seconda members chiamata:

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

Aggiungere --verbose per stampare anche il file della cache su disco che esegue il backup di ogni spazio dei nomi, utile durante la diagnosi di un indice non aggiornato o imprevisto.

L'esecuzione winapp find-api senza query stampa un breve riepilogo dell'utilizzo ed esce 0 . Si tratta di una richiesta di assistenza, non di una ricerca che non ha trovato nulla.

Ambiti. Ogni risposta proviene esattamente da un ambito, segnalato come scope in --json e come nota nell'output di testo:

  • project - il progetto nella directory corrente (o --project / --project-dir). Vengono illustrati gli SDK Windows, i SDK per app di Windows e i pacchetti NuGet del progetto. I metadati SDK per app di Windows sono il rilascio dei riferimenti al progetto: se nel computer è installato un app di Windows Runtime più recente, find-api avvisa e lo esce anziché confermare i tipi in cui il progetto non può essere compilato.
  • sdk: i metadati Windows SDK e SDK per app di Windows a livello di computer, usati automaticamente quando la directory corrente non contiene alcun progetto e nessuna soluzione. In questo modo è find-api possibile esplorare le API prima dell'esistenza di qualsiasi progetto e non richiede l'accesso alla rete. Non include deliberatamente pacchetti NuGet di terze parti, quindi un tipo di (ad esempio) Community Toolkit non verrà trovato in questo ambito.

Una query da una directory senza progetto e nessuna soluzione viene sempre fornita dall'ambito sdk , mai da qualsiasi progetto venga indicizzato nella cache condivisa, quindi i risultati non dipendono mai dallo stato globale non correlato. Passare --project sdk per selezionare l'ambito dell'SDK in modo esplicito dall'interno di un progetto e winapp find-api refresh --project sdk ricompilarlo dopo aver installato un nuovo SDK di Windows.

Directory della soluzione. Da una directory che contiene un .sln/.slnx file senza progetto accanto a esso, i progetti la soluzione compila una risposta anziché l'ambito sdk , ma vengono indicizzati su richiesta, quindi vengono inclusi i pacchetti NuGet. Quando la soluzione compila più di un progetto indicizzato, la query li elenca e richiede --project <name> anziché sceglierne uno.

Comandi:

  • (bare)find-api "<query>" ["<query>"...] - Cercare i nomi dei tipi e dei membri, eseguendo il fallback ai relativi riepiloghi documentati, raggruppati per spazio dei nomi
  • members <type> [<type>...] [--filter <text>] - Elencare le proprietà, gli eventi e i metodi di un tipo (membri dichiarati con firme, membri ereditati riepilogati dichiarando il tipo)
  • check-property <type> <property> [<property>...] - Convalidare l'esistenza di proprietà in un tipo (esce da zero se manca). Una proprietà di sola lettura viene segnalata con ⚠️ e "sola lettura, non può essere assegnata" invece di una normale ✅, quindi una proprietà come ActualWidth non viene scambiata per qualcosa che è possibile impostare. I nomi delle proprietà corrispondono senza distinzione tra maiuscole e minuscole, perché C# e XAML sono: check-property Button background esce da zero e offre Background come corrispondenza vicina anziché segnalare un nome che non è possibile scrivere effettivamente.
  • enums <type> [<type>...] [--filter <text>] - Elencare i valori di un'enumerazione (esce da zero quando il tipo non è un'enumerazione)
  • packages - Elencare i pacchetti di metadati indicizzati, con conteggi di tipo/membro per pacchetto
  • stats - Mostra statistiche sugli indici di aggregazione (pacchetti, spazi dei nomi, tipi, membri, .winmd file)
  • refresh [--scan] - Ricompilare l'indice per un progetto (--scan indicizza ogni progetto nella directory). Con --project <name>, un nome che corrisponde a nessun singolo progetto indicizzato non riesce anziché indicizzare la directory corrente.

Batching.search, members, enumse check-propertyaccettare più soggetti in una chiamata. Per un agente di intelligenza artificiale questa è la singola leva di costo più grande: il costo marginale di una ricerca è dominato dal round trip (ogni chiamata invia nuovamente l'intera conversazione), non dalle dimensioni del payload, quindi una chiamata che risponde a dieci domande è molto più conveniente di dieci chiamate.

  • Un singolo soggetto restituisce esattamente la forma di payload che ha sempre, sia nel testo --jsonche in .
  • Due o più soggetti restituiscono una busta , { "count": N, "results": [ ... ] } in --json, con ogni elemento che rappresenta il normale payload a soggetto singolo; check-property aggiunge missingCount. L'output di testo esegue il rendering di ogni oggetto in sequenza sotto un'intestazione di ambito.
  • check-property batch di proprietà su un tipo: il primo argomento è il tipo, ogni argomento dopo di esso è una proprietà. In modalità batch una proprietà che esiste stampa una singola ✅ riga. Il dettaglio completo della mancata presenza viene stampato solo per quelli che non lo fanno.
  • Un batch viene chiuso 0 solo se ogni soggetto è stato risolto ed è stato trovato, quindi un batch è comunque sicuro per controllare codegen on.

Classificazione della ricerca. Una query che corrisponde esattamente a un nome di tipo viene classificata in anticipo rispetto alle corrispondenze parziali e quando un nome breve viene condiviso da diversi spazi dei nomi solo le collisioni con nome esatto sono elencate come ambigue, una query come NavigationView segnala la manciata di spazi dei nomi che definiscono il tipo esatto anziché ogni spazio dei nomi contenente un simbolo con nome simile. L'elenco di ambiguità rispetta --maxe i risultati normali vengono comunque stampati sotto di esso.

Digitare names.members, check-propertye enums accettare un nome breve (NavigationView) o un nome completo (Microsoft.UI.Xaml.Controls.NavigationView). Quando un nome breve viene condiviso da un tipo moderno Microsoft.* e dal gemello UWP legacyWindows.*, il Microsoft.* tipo risponde, ovvero la proiezione usata da un'app SDK per app di Windows, e viene sempre visualizzato il nome completo risolto. Qualsiasi altra collisione esce da zero e elenca i candidati invece di indovinare.

Firme del metodo. Viene stampata una firma nel modo in cui si scrive la chiamata: un metodo chiamato sul tipo anziché in un'istanza viene visualizzato con statice viene visualizzato un parametro per riferimento con la parola chiave effettivamente necessaria , out, ino ref. Boolean TryGetValue(String key, out String value)Legge TryGetValue quindi , che viene compilato come scritto.

Opzioni:

  • --max <n> - Numero massimo di risultati della ricerca raggruppati in spazi dei nomi (impostazione predefinita 5; solo ricerca). Inoltre, l'elenco di ambiguità viene delimitato, quindi una breve query che si scontra in molti spazi dei nomi rimane leggibile.
  • --filter <text> - Restringere un elenco su members e enums: una corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole sul nome membro/valore. Ideale per i tipi con centinaia di membri. La maggior parte delle enumerazioni è abbastanza piccola da eseguire il dump dell'intero (anche Symbol, il più grande in WinUI a 197 valori), quindi filtrarli in genere costa più di quanto si risparmia una volta che si fattore in una seconda ipotesi. Non eseguire mai di nuovo lo stesso comando con testo di filtro diverso: eseguire il dump una volta e leggerlo.
  • --all - In memberselencare la superficie completa: firme complete per i membri ereditati, oltre a statici identificatori di proprietà di dipendenza e descrizioni per membro, che un elenco non filtrato omette (vedi Dimensioni elenco di seguito). --verbose implica; usare --all quando si desidera --jsonanche , che non può essere combinato con --verbose.
  • --scan - Individuazione ricorsiva e indicizzazione di ogni progetto nella directory (refresh solo)
  • --project <name>- Project eseguire una query (corrisponde al .csproj/.vcxproj nome) o sdk per eseguire una query sull'ambito Windows SDK a livello di computer
  • --project-dir <path>- Project directory su cui eseguire una query (per impostazione predefinita è la directory corrente). Un percorso che non esiste è un errore: non viene mai risposto in modo invisibile all'utente dall'ambito sdk .
  • --json - Generare un payload leggibile dal computer in stdout (supportato da ogni verbo). I payload di query identificano l'indice che ha risposto tramite scope (project o sdk), projectNamee projectDir (assente per l'ambito sdk): i nomi dei progetti non sono univoci tra le directory, quindi projectDir è l'identità affidabile. 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.

Esempi:

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

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

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

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

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

# Manage the index
winapp find-api refresh

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

Quando --filter viene applicato, l'output segnala comunque il totale non filtrato (totalValueso totalProperties/totalMethods/totalEventsin --json), quindi una visualizzazione ridotta non viene mai scambiata per una piccola API. Un filtro che non corrisponde a nulla viene ancora chiuso 0 e dice così in modo esplicito, ovvero "nessuna corrispondenza con il filtro", non "nessun tipo di questo tipo".

Dimensioni elenco. Un elenco non filtrato members è l'unica forma costosa, members Button che copre 288 membri, di cui 280 vengono ereditati da 6 tipi di base. Una chiamata non filtrata è una query di orientamento ("che cos'è questo tipo, approssimativamente cosa può fare?"), quindi risponde e omette le parti da cui non viene scritto nulla:

  • Firme dei membri ereditate : i membri ereditati vengono raggruppati dichiarando il tipo e elencati solo per nome, pertanto la forma della superficie ereditata è ancora visibile senza 280 firme complete.
  • Statici dell'identificatore di proprietà di dipendenza (BackgroundProperty): 28% delle proprietà di un tipico controllo WinUI. Esistono da passare a GetValue/SetValue, non assegnati.
  • Descrizioni per membro : prosa XML-doc, circa 16% del payload.
  • Campi impliciti dall'ambiente circostante in --json: kind (implicito dalla matrice contenitore/eventsproperties/methods), returnType (token iniziale di signature) e inherited quando false (implicito da ).declaringType

Ciò che è stato omesso viene sempre segnalato (hiddenDependencyProperties, descriptionsOmittede in --jsonhint , una riga "Omitted:" nel testo) e i totali descrivono ancora l'intero tipo. Sia --filter che --all vedere la superficie completa con firme e descrizioni complete, quindi members Button --filter BackgroundProperty trova ancora l'identificatore e members Button --filter Click restituisce Clickcomunque la firma ereditata. Misurata su samples/winui-app, questa operazione richiede members Button --json da 91.954 a 10.567 caratteri (−88,5%) lasciando e --all byte --filter identici.

Corrispondenza di una query. winapp find-api "language model" viene classificato LanguageModel sopra le corrispondenze le cui parole vengono distribuite tra spazi dei nomi e membri, incluso all'esterno di un progetto quando il tipo viene indicizzato. La ricerca è lessicale, non semantica: corrisponde a parole identificatori intere anziché a qualsiasi esecuzione di lettere, quindi llm trova IImageLLMAdapterSession ma non ScrollMode. Quando una query non corrisponde a un nome, viene tentata in base ai riepiloghi documentati di tipi e membri, ovvero ciò che consente di "random-access stream" trovare IRandomAccessStream. Le descrizioni vengono classificate al di sotto di ogni corrispondenza del nome e solo i riepiloghi dei pacchetti effettivamente spediti sono ricercabili. Un pacchetto senza documentazione XML non contribuisce a testo di descrizione.

Progetti senza un file di progetto MSBuild. Un'app Electron (o qualsiasi altra app non .NET guidata da winapp.yaml) non ha e quindi nessuna .csprojproject.assets.json. find-api lo indicizza dall'oggetto .winapp/winmds.lock.json che winapp restore scrive, che registra la stessa cosa: ogni pacchetto risolto, la sua versione e i .winmd file che contribuisce. Un progetto di questo tipo è denominato dopo la directory e il relativo indice diventa obsoleto quando il file di blocco viene riscritto. Una directory che contiene sia un .csproj oggetto che un winapp.yaml oggetto viene indicizzato da .csproj, ovvero la descrizione più precisa di ciò che il progetto compila in base a .

Le risposte negative sono qualificate quando l'indice è incompleto. Se non è stato possibile leggere i metadati di un pacchetto, "nessun tipo di questo tipo" e "il pacchetto non è mai stato indicizzato" è identico e agisce sul primo quando è realmente il secondo genera codice su un'API in cui è stato detto che non esiste. Ogni risposta negativa, inclusa una classe search che restituisce zero risultati, restituisce quindi una nota che l'indice è parziale e punta a winapp find-api refresh. Le risposte positive non sono interessate.

Nomi di tipi generici. I metadati archivia i tipi generici con un suffisso arity (IAsyncOperation`1), che non è il modo in cui gli utenti li scrivono. members, enumse check-property accettano ogni formato: IAsyncOperation, IAsyncOperation<StorageFile>e IAsyncOperation`1 tutti si risolvono nello stesso tipo. Un nome bare corrisponde a qualsiasi arità; un'arità dichiarata (in entrambe le notazioni) deve corrispondere, pertanto Holder<A, B> non verrà risolta in un singolo parametro Holder<T>.

--json payload omettere la diagnostica. I percorsi dei file della cache vengono visualizzati solo in --verbose (output di testo corrispondente, in cui erano già dettagliati) e matrici di suggerimenti vuoti vengono omessi anziché serializzati come [].

Codici di uscita:search senza riscontri, check-property su una proprietà mancante e enums su un tipo non enum, tutti i controlli di uscita non zero, ovvero la generazione del codice gate e i controlli CI. Una chiamata in batch esce senza zero se un oggetto non riesce. Una proprietà di sola lettura non è un errore, check-property pertanto viene chiusa 0 e contrassegnata nell'output (writable: false in --json). Una init proprietà segnala writable: false lo stesso motivo: può essere impostata in un inizializzatore di oggetto e la relativa firma indica { get; init; }, ma l'assegnazione successiva non viene compilata.

Correlato:find-api risponde "questa API esiste e quali sono i suoi membri?"; usare find-ui per trovare un esempio winUI funzionante per un controllo.

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

Annotazioni

Le associazioni sono solo npm : richiedono la chiamata tramite npx winapp (pacchetto @microsoft/winappcli npm). L'interfaccia della riga di comando winget autonoma non li visualizza. Eseguire winapp init in modo interattivo e acconsentire esplicitamente oppure usare , prima di usare winapp init . --use-defaults --add-js-bindingsquesto comando per rigenerare le associazioni. Se si modifica winapp.yaml, eseguire npx winapp restore per aggiornare Windows dipendenze prima della rigenerazione.

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

Importante

Si è verificato un problema noto relativo alla creazione di pacchetti sparse di applicazioni Electron che causano l'arresto anomalo dell'app all'avvio o al rendering del contenuto Web. Il problema è stato risolto in Windows, ma non è ancora stato propagato ai dispositivi esterni Windows. Se questo problema viene visualizzato dopo aver chiamato add-electron-debug-identity, è possibile disabilitare il sandboxing nell'app Electron a scopo di debug con il --no-sandbox flag . Questo problema non influisce sulla creazione di pacchetti MSIX completi.

Per annullare l'identità di debug Electron, usare winapp node clear-electron-debug-identity.

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

Opzioni:

Opzione Descrizione
--manifest <path> Percorso di Package.appxmanifest personalizzato (impostazione predefinita: Package.appxmanifest nella directory corrente)
--no-install Non installare o modificare le dipendenze; configurare solo l'identità di debug di Electron
--keep-identity Mantenere l'identità del manifesto così com'è, senza aggiungere .debug al nome del pacchetto e all'ID dell'applicazione
--verbose Abilitare l'output dettagliato

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:

Opzione Descrizione
--verbose Abilitare l'output dettagliato

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

Identità del flusso di lavoro dell'interfaccia utente

winapp ui i comandi che guidano il desktop fisico prendono sempre turni cooperativi, quindi due flussi di lavoro in esecuzione contemporaneamente non possono rubare lo stato attivo dell'altro o ignorare i menu dell'altro. L'arbitrato non ha bisogno di alcuna configurazione e non può essere disattivato.

Ciò che è facoltativo è la continuità. Per impostazione predefinita, ogni comando è uno scatto autonomo che rilascia il desktop non appena termina. Per mantenere il desktop in più comandi, assegnargli tutti gli stessi ID del flusso di lavoro:

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

Usare lo stesso valore per i processi di collaborazione (ad esempio una registrazione e i clic che deve acquisire) e valori diversi per i flussi di lavoro indipendenti. Ogni comando senza UN ID è un flusso di lavoro singolo, anche quando vengono avviati diversi da una shell, quindi gli host che avviano una nuova shell per ogni comando devono inserire lo stesso valore esplicito in ognuno di essi. Il valore è opaco, non viene mai considerato come credenziale e viene mantenuto solo come hash SHA-256. Vedere Automazione interfaccia utente → Coordinamento dei flussi di lavoro simultanei dell'interfaccia utente.

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 - Capture window/element as PNG (multiple windows form one labeled composite PNG; see capture scope)
  • 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
  • yield - Rilasciare il turno dell'interfaccia utente del flusso di lavoro corrente; richiede WINAPP_UI_WORKFLOW_ID

Opzioni:

  • -a, --app <app> - App di destinazione (nome, titolo o PID)
  • -w, --window <hwnd> - Finestra di destinazione di HWND (stabile)
  • --on <target> - Eseguire qualsiasi ui verbo in sandbox; nomi, PID e handle di finestra fanno riferimento al guest. Gli output vengono recapitati all'host. Vedere Automazione interfaccia utente sandbox per i requisiti di configurazione, coordinamento del flusso di lavoro e client.

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 evidence.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).
  • --overwrite - Sostituire gli output di registrazione esistenti al termine della nuova operazione; gli output esistenti vengono rifiutati per impostazione predefinita. I bundle di frame precedenti vengono mantenuti. Vedere Registrazione del ripristino dell'output.
  • --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 seguire il flusso di lavoro di sovrimpressione screenshot per i popup. Rilevato nel numero 646.

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

  • Last updated on