Uso di winapp CLI con WinUI

Questa guida illustra come usare winapp CLI nel ciclo interno completo di un'app WinUI 3: creare un progetto da un modello ufficiale, compilarlo e avviarlo con l'identità del pacchetto, eseguire il debug degli arresti anomali, trovare controlli e API, automatizzare l'interfaccia utente e produrre un pacchetto MSIX firmato. Ogni passaggio viene eseguito dalla riga di comando, quindi funziona in qualsiasi editor, in CI e con agenti di codifica AI.

I modelli di progetto WinUI includono già Package.appxmanifest, quindi non è necessario eseguire winapp init per un'app WinUI. Se si aggiunge l'identità del pacchetto a un'app .NET esistente che non usa WinUI, vedere invece Uso di winapp CLI con .NET.

Prerequisites

• Windows 10 versione 1809 o successiva o Windows 11.

• .NET SDK, versione 8.0.100 o successiva. I modelli sperimentali di Reactor richiedono l'SDK .NET 10. L'interfaccia della riga di comando di winapp non installa toolchain, quindi winapp new e winapp run si arrestano con un messaggio con istruzioni se manca .NET SDK.

• winapp CLI:

  winget install Microsoft.winappcli --source winget
  

• Modalità sviluppatore, che Windows richiede per registrare l'app dall'output di compilazione. Attivarlo in Impostazioni > sistema > per sviluppatori. Per sapere cosa cambia sul tuo computer, vedere Sicurezza.

Creare un'app WinUI

winapp new crea la struttura di un'app WinUI dal pacchetto ufficiale Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Installa o aggiorna il pacchetto di modelli su richiesta e quindi chiama dotnet new per te.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Eseguire winapp new --list per visualizzare i modelli nel pacchetto installato. Il pacchetto include questi modelli:

Per ogni opzione, vedere il newriferimento dei comandi.

Compila ed esegui usando l'identità

Dalla cartella del progetto, winapp run compila il progetto, installa il runtime di SDK per app di Windows corrispondente alla tua architettura se manca, registra l'app con l'identità del pacchetto e la avvia.

cd MyApp
winapp run

winapp run accetta un file di progetto, un file di soluzione, una cartella contenente una di esse o una cartella di output di compilazione:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

L'interfaccia della riga di comando di winapp legge la proprietà del progetto WindowsPackageType per decidere come avviarlo. Un progetto in pacchetto viene eseguito con l'identità del pacchetto. Progetto che imposta WindowsPackageType su None viene eseguito come app non in pacchetto senza identità. Per eseguire un progetto pacchettizzato come non pacchettizzato, passare la proprietà nella riga di comando:

winapp run -p WindowsPackageType=None

Altre opzioni utili includono --clean per rimuovere la registrazione precedente e i dati salvati dell'app (LocalState e impostazioni) per una nuova prima esecuzione, --no-launch per eseguire la registrazione senza avviare l'app e --detach --json per restituire l'ID processo e uscire in modo che gli script e gli agenti possano continuare a funzionare durante l'esecuzione dell'app. Per l'elenco completo, vedere modalità progetto (progetti SDK .NET).

Usare invece dotnet run

Se si preferisce dotnet run, usare il Microsoft.Windows.SDK.BuildTools.WinApp pacchetto NuGet. Il pacchetto aggancia dotnet run in modo che chiami winapp run e avvii l'app con identità. I progetti creati con winapp new fanno già riferimento al pacchetto, quindi dotnet run funziona senza alcuna configurazione aggiuntiva. Per altri progetti, aggiungere prima il pacchetto:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

È possibile passare winapp run le opzioni come WinAppRun* proprietà di MSBuild, ad esempio dotnet run -p:WinAppRunDebugOutput=true. Per disattivare l'integrazione, impostare EnableWinAppRunSupport su false nel file di progetto. Per informazioni dettagliate, vedere dotnet run support.

Esegui il debug degli arresti anomali

Aggiungere --debug-output per acquisire OutputDebugString messaggi ed eccezioni first-chance durante l'esecuzione dell'app. Quando un'app WinUI non riesce a causa di un'eccezione stowed, winapp CLI analizza il dump di arresto anomalo e stampa l'errore originale e lo stack di chiamate anziché un codice di errore generico.

winapp run --debug-output

Aggiungi --symbols per scaricare i simboli per i nomi completi delle funzioni native. Poiché --debug-output usa winapp CLI come debugger, non è possibile collegare Visual Studio o un altro debugger allo stesso processo. Per eseguire il debug con l'IDE invece, vedere Debugging con winapp CLI. Per informazioni dettagliate sull'analisi delle eccezioni stowed, vedere triage delle stowed-exception di WinUI.

Trovare controlli e API

winapp find-uicerca esempi XAML e C# da WinUI Gallery e Windows Community Toolkit per finalità e restituisce il codice per uno scenario selezionato. winapp find-apicerca nel set di API di Windows e WinRT a cui fa riferimento il progetto, ad esempio tipi, membri ed enumerazioni di SDK per app di Windows e Windows SDK.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Entrambi i comandi supportano --json, in modo che gli agenti di codifica di intelligenza artificiale possano usarli per scegliere i controlli e verificare i nomi delle API. Per altre informazioni, vedere i riferimenti find-ui e find-api.

Automatizzare e verificare l'interfaccia utente

winapp uicontrolla un'app in esecuzione tramite Microsoft Automazione interfaccia utente. Usalo per esaminare l'albero degli elementi, richiamare i controlli, attendere le modifiche dello stato e acquisire screenshot. Gli agenti possono usare gli stessi comandi per controllare le proprie modifiche.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

Il PART_PaneToggleButton selettore è destinato al pulsante di menu nel winui-navview modello. Per i controlli personalizzati, copiare un selettore dall'output di winapp ui inspect o winapp ui search.

Per eseguire l'app in Windows Sandbox anziché sul desktop, aggiungere --on sandbox a winapp run e a winapp ui. Per altre informazioni, vedere Automazione interfaccia utente ed esecuzione sandbox.

Crea pacchetto e firma

Quando si è pronti per testare un pacchetto in locale, generare un certificato di sviluppo il cui publisher corrisponde al manifest e quindi compilare e creare il pacchetto del progetto in un unico passaggio:

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack compila il progetto e produce un .msix firmato. Per combinare le compilazioni per diverse architetture in un'unica .msixbundle, vedere Bundle multi-architettura. Il progetto deve essere pacchettizzato, quindi un progetto che imposta WindowsPackageType su None non può essere pacchettizzato. Per i progetti WinUI, la build di SDK per app di Windows gestisce il manifesto, il punto di ingresso e la generazione di risorse, quindi --manifest, --executable e --skip-pri non vengono accettati.

Il certificato di sviluppo è solo per i test locali e usa una password predefinita. Prima di distribuire l'app, firmala con un certificato attendibile, ad esempio con winapp az-sign e Firma attendibile di Azure. Per altre informazioni, vedere Creazione di pacchetti di un progetto direttamente e Sicurezza.

Progetti WinUI esistenti

L'interfaccia della riga di comando di winapp funziona con i progetti WinUI creati in Visual Studio. Puntare winapp run al file di progetto, al file della soluzione o alla cartella che ne contiene uno. Per winapp pack, passa il .csproj. È possibile continuare a compilare e eseguire il debug in Visual Studio e usare l'interfaccia della riga di comando winapp per gli script, l'integrazione continua e i flussi di lavoro dell'agente.

WinUI con C++

winapp runcompila e avvia anche progetti WinUI C++/WinRT (.vcxproj) che hai creato dal modello App vuota WinUI (in pacchetto) di Visual Studio. Compila il progetto con MSBuild di Visual Studio, registra l'app con l'identità del pacchetto e la avvia:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

I progetti C++ necessitano di Visual Studio o strumenti di compilazione per Visual Studio con il carico di lavoro Sviluppo di applicazioni desktop con C++ e gli strumenti di sviluppo di app WinUI C++. winapp packnon compila .vcxproj progetti, quindi crea il pacchetto MSIX in Visual Studio. Per i prerequisiti e le opzioni, vedere Progetti C++ (.vcxproj). Per le app C++ che non usano WinUI, vedere Uso di winapp CLI con C++.

Samples

• winui-app: un'app WinUI in pacchetto con controlli configurati per winapp ui l'automazione
• winui-unpackaged-app: un'app WinUI che viene eseguita senza identità del pacchetto
• winui-solution: una soluzione multiprogetto che mostra come winapp run seleziona il progetto dell'app
• cpp-winui-app: un'app WinUI C++/WinRT in pacchetto (Visual Studio .vcxproj con XAML) eseguita conwinapp run

Passaggi successivi

• Introduzione a WinUI
• Riferimento del comando winapp CLI
• Eseguire il debug con winapp CLI
• Automazione interfaccia utente