Winapp CLI gebruiken met WinUI

Deze handleiding laat zien hoe u winapp CLI gebruikt in de volledige binnenste lus van een WinUI 3-app: een project maken op basis van een officiële sjabloon, bouwen en starten met pakketidentiteit, crashes opsporen, besturingselementen en API's zoeken, de gebruikersinterface automatiseren en een ondertekend MSIX-pakket produceren. Elke stap wordt uitgevoerd vanaf de opdrachtregel, zodat deze werkt in elke editor, in CI en met AI-coderingsagents.

WinUI-projectsjablonen bevatten al een Package.appxmanifest, dus u hoeft winapp init niet uit te voeren voor een WinUI-app. Als u pakketidentiteit toevoegt aan een bestaande .NET-app die geen WinUI gebruikt, raadpleegt u in plaats daarvan Winapp CLI gebruiken met .NET.

Prerequisites

  • Windows 10 versie 1809 of hoger of Windows 11.

  • De .NET SDK, versie 8.0.100 of hoger. Voor de experimentele Reactor-sjablonen is de .NET 10 SDK vereist. winapp CLI installeert geen toolchains, dus winapp new en winapp run stoppen met richtlijnen als de .NET SDK ontbreekt.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Ontwikkelaarsmodus, die Windows vereist om de app te registreren uit uw build-uitvoer. Schakel het in via Instellingen > Systeem > Voor ontwikkelaars. Zie Beveiliging voor wat dit op uw computer verandert.

Een WinUI-app maken

winapp new genereert een WinUI-app vanuit het officiële Microsoft.WindowsAppSDK.WinUI.CSharp.Templates-pakket. Het sjabloonpakket wordt op aanvraag geïnstalleerd of bijgewerkt en roept vervolgens dotnet new voor u aan.

# 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

Voer deze opdracht uit winapp new --list om de sjablonen in het geïnstalleerde pakket weer te geven. Het pakket bevat de volgende sjablonen:

Template Description
winui Minimale lege XAML-app (standaard). Zie schermafbeelding
winui-navview XAML-app met een NavigationView-shell. Zie schermafbeelding
winui-tabview XAML-app met een TabView-shell. Schermafbeelding bekijken
winui-mvvm XAML-app die gebruikmaakt van het MVVM-patroon met CommunityToolkit.Mvvm. Zie schermafbeelding
winui-lib WinUI-klassebibliotheek
winui-unittest Verpakt MSTest-project voor WinUI-eenheidstests
reactor,reactor-mvu,reactor-navview,reactor-tabview Experimenteel. WinUI-apps die alleen in C# zijn geschreven, zonder XAML

Note

De Reactor-sjablonen verwijzen naar prereleasepakketten Microsoft.UI.Reactor . Hun API's kunnen in een toekomstige release worden gewijzigd of verwijderd.

Zie de new opdrachtreferentie voor elke optie.

Builden en uitvoeren met identiteit

Vanuit de projectmap compileert winapp run het project, installeert de Windows App SDK-runtime die overeenkomt met uw architectuur als deze ontbreekt, registreert de app met pakketidentiteit en start deze.

cd MyApp
winapp run

winapp run accepteert een projectbestand, een solutionbestand, een map met een van deze bestanden of een map met build-uitvoer:

# 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

winapp CLI leest de WindowsPackageType-eigenschap van het project om te bepalen hoe het moet worden gestart. Een verpakt project wordt uitgevoerd met pakketidentiteit. Een project dat WindowsPackageType instelt op None, wordt uitgevoerd als een uitgepakte app zonder identiteit. Als u een verpakt project wilt uitvoeren als niet-verpakt, geeft u de eigenschap door op de opdrachtregel:

winapp run -p WindowsPackageType=None

Andere handige opties zijn --clean om de vorige registratie en de opgeslagen gegevens van de app (LocalState en instellingen) te verwijderen voor een nieuwe eerste uitvoering, --no-launch om te registreren zonder de app te starten en --detach --json de proces-id te retourneren en af te sluiten, zodat scripts en agents kunnen blijven werken terwijl de app wordt uitgevoerd. Zie Project-modus (.NET SDK-projecten) voor de volledige lijst.

Gebruik in plaats daarvan dotnet run

Als u de voorkeur geeft aan dotnet run, gebruik dan het Microsoft.Windows.SDK.BuildTools.WinApp NuGet-pakket. Het pakket haakt in op dotnet run, zodat het winapp run aanroept en de app met identiteit start. Projecten die u maakt met winapp new verwijzen al naar het pakket, dus dotnet run werkt zonder extra installatie. Voor andere projecten voegt u eerst het pakket toe:

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

U kunt winapp run-opties doorgeven als WinAppRun* MSBuild-eigenschappen, bijvoorbeeld dotnet run -p:WinAppRunDebugOutput=true. Als u de integratie wilt uitschakelen, stelt u EnableWinAppRunSupport in op false in het projectbestand. Zie dotnet run support voor meer informatie.

Crashproblemen debuggen

Voeg --debug-output toe om OutputDebugString berichten en first-chance exceptions vast te leggen terwijl de app wordt uitgevoerd. Wanneer een WinUI-app faalt met een stowed exception, analyseert winapp CLI de crashdump en toont de oorspronkelijke fout en de aanroepstack in plaats van een algemene foutcode.

winapp run --debug-output

Voeg --symbols toe om symbolen te downloaden voor volledige native functienamen. Omdat --debug-output winapp CLI als foutopsporingsprogramma koppelt, kunt u Visual Studio of een ander foutopsporingsprogramma niet aan hetzelfde proces koppelen. Als u in plaats daarvan fouten wilt opsporen met uw IDE, raadpleegt u Foutopsporing met winapp CLI. Zie WinUI stowed-exception triage voor meer informatie over de analyse van stowed-exception.

Zoek besturingselementen en API's

winapp find-uizoekt op basis van intentie naar XAML- en C#-voorbeelden uit de WinUI-galerie en de Windows Community Toolkit en retourneert de code voor een scenario dat u kiest. winapp find-api doorzoekt het Windows- en WinRT-API-oppervlak waarnaar uw project verwijst, zoals Windows App SDK- en Windows SDK-typen, leden en opsommingen.

# 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

Beide commando’s ondersteunen --json, zodat AI-coderingsagenten deze kunnen gebruiken om controls te kiezen en API-namen te verifiëren. Zie de find-ui en find-api verwijzingen voor meer informatie.

Gebruikersinterface automatiseren en controleren

winapp ui stuurt een actieve app via Microsoft UI Automation. Gebruik deze om de elementstructuur te inspecteren, besturingselementen aan te roepen, te wachten op statuswijzigingen en schermopnamen te maken. Agents kunnen dezelfde opdrachten gebruiken om hun eigen wijzigingen te controleren.

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

De PART_PaneToggleButton selector is gericht op de menuknop in de winui-navview sjabloon. Voor uw eigen besturingselementen kopieert u een selector uit de uitvoer van winapp ui inspect of winapp ui search.

Als u de app wilt uitvoeren in Windows Sandbox in plaats van op uw bureaublad, voegt u --on sandbox toe aan winapp run en winapp ui. Zie ui-automatisering en sandbox-uitvoering voor meer informatie.

Verpak en onderteken

Wanneer u klaar bent om een pakket lokaal te testen, genereert u een ontwikkelingscertificaat waarvan de uitgever overeenkomt met uw manifest en bouwt en verpakt u het project vervolgens in één stap:

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

winapp pack bouwt het project en produceert een gesigneerde .msix. Als u builds voor verschillende architecturen in één .msixbundle wilt combineren, raadpleegt u bundels met meerdere architecturen. Het project moet worden verpakt, dus een project dat WindowsPackageType op None instelt, kan niet worden verpakt. Voor WinUI-projecten is de Windows App SDK-build eigenaar van het manifest, het instappunt en het genereren van resources, dus --manifest, --executable en --skip-pri worden niet geaccepteerd.

Het ontwikkelingscertificaat is alleen bedoeld voor lokaal testen en gebruikt een standaardwachtwoord. Voordat u uw app distribueert, moet u deze ondertekenen met een vertrouwd certificaat, bijvoorbeeld met winapp az-sign en Vertrouwde ondertekening van Azure. Zie Een project rechtstreeks verpakken en Beveiliging voor meer informatie.

Bestaande WinUI-projecten

winapp CLI werkt met WinUI-projecten die u hebt gemaakt in Visual Studio. Wijs winapp run naar het projectbestand, het solutionbestand of de map die er een bevat. Geef voor winapp pack de .csproj door. U kunt blijven bouwen en fouten opsporen in Visual Studio en winapp CLI gebruiken voor scripts, CI en agentwerkstromen.

WinUI met C++

winapp run bouwt en start ook C++/WinRT WinUI-projecten (.vcxproj) die u hebt gemaakt op basis van de Visual Studio-sjabloon WinUI Blank App (Packaged). Hiermee wordt het project gebouwd met MSBuild van Visual Studio, wordt de app geregistreerd met pakketidentiteit en gestart:

winapp run .\MyApp.vcxproj

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

C++-projecten hebben Visual Studio of Build Tools nodig voor Visual Studio met de desktopontwikkeling met C++-workload en C++ WinUI-app-ontwikkelhulpprogramma's. winapp pack bouwt geen .vcxproj-projecten, dus maak het MSIX-pakket in Visual Studio. Zie C++-projecten (.vcxproj) voor vereisten en opties. Voor C++-apps die geen WinUI gebruiken, zie WinAPP CLI gebruiken met C++.

Samples

  • winui-app: een verpakte WinUI-app met besturingselementen die zijn ingesteld voor winapp ui automatisering
  • winui-unpackaged-app: een WinUI-app die wordt uitgevoerd zonder pakketidentiteit
  • winui-solution: een oplossing voor meerdere projecten die laat zien hoe winapp run het app-project kiest
  • cpp-winui-app: een verpakte C++/WinRT WinUI-app (Visual Studio .vcxproj met XAML) die wordt uitgevoerd metwinapp run

Volgende stappen 

  • Laatst bijgewerkt om