Använda winapp CLI med WinUI

Den här guiden visar hur du använder winapp CLI i den fullständiga inre loopen i en WinUI 3-app: skapa ett projekt från en officiell mall, skapa och starta det med paketidentitet, felsöka krascher, hitta kontroller och API:er, automatisera användargränssnittet och skapa ett signerat MSIX-paket. Varje steg körs från kommandoraden, så det fungerar i alla redigeringsprogram, i CI och med AI-kodningsagenter.

WinUI-projektmallar innehåller redan en Package.appxmanifest, så du behöver inte köra winapp init för en WinUI-app. Om du lägger till paketidentitet i en befintlig .NET-app som inte använder WinUI, se Använda winapp CLI med .NET i stället.

Prerequisites

  • Windows 10 version 1809 eller senare eller Windows 11.

  • .NET SDK, version 8.0.100 eller senare. De experimentella Reactor-mallarna kräver .NET 10 SDK. winapp CLI installerar inte verktygskedjor, så winapp new och winapp run slutar med vägledning om .NET SDK saknas.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Utvecklarläge, som Windows kräver för att registrera appen från dina byggutdata. Aktivera det i Inställningar > System > För utvecklare. För information om vad detta ändrar på datorn, se Säkerhet.

Skapa en WinUI-app

winapp new skapar stommen till en WinUI-app från det officiella Microsoft.WindowsAppSDK.WinUI.CSharp.Templates paketet. Den installerar eller uppdaterar mallpaketet på begäran och anropar dotnet new åt dig.

# 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

Kör winapp new --list för att se mallarna i det installerade paketet. Paketet innehåller följande mallar:

Template Description
winui Minimal tom app i XAML (standardinställning). Se skärmbild
winui-navview XAML-app med ett NavigationView-skal. Se skärmdump
winui-tabview XAML-app med ett TabView-gränssnitt. Se skärmbild
winui-mvvm XAML-app som använder MVVM-mönstret med CommunityToolkit.Mvvm. Se skärmbild
winui-lib WinUI-klassbibliotek
winui-unittest Paketerat MSTest-projekt för WinUI-enhetstester
reactor, reactor-mvu, reactor-navview, reactor-tabview Experimentell. WinUI-appar skrivna endast i C#, utan XAML

Note

Reaktormallarna innehåller referenser till förhandsversionspaket Microsoft.UI.Reactor. Deras API:er kan ändras eller tas bort i en framtida version.

För varje alternativ, se newkommandoreferensen.

Bygga och köra med identitet

Från projektmappen bygger winapp run projektet, installerar den Windows App SDK-runtime som matchar din arkitektur om den saknas, registrerar appen med paketidentitet och startar den.

cd MyApp
winapp run

winapp run accepterar en projektfil, en lösningsfil, en mapp som innehåller en av dem eller en mapp med byggutdata:

# 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 läser projektets WindowsPackageType egenskap för att bestämma hur det ska startas. Ett paketerat projekt körs med paketidentitet. Ett projekt som ställer in WindowsPackageType till None körs som en opaketerad app utan identitet. Om du vill köra ett paketerat projekt som opaketerat anger du egenskapen på kommandoraden:

winapp run -p WindowsPackageType=None

Andra användbara alternativ är --clean att ta bort den tidigare registreringen och appens sparade data (LocalState och inställningar) för en ny första körning, --no-launch att registrera utan att starta appen och --detach --json att returnera process-ID:t och avsluta så att skript och agenter kan fortsätta fungera medan appen körs. För den fullständiga listan, se projektläge (.NET SDK-projekt).

Använd dotnet run i stället

Om du föredrar dotnet run, använd NuGet-paketet Microsoft.Windows.SDK.BuildTools.WinApp. Paketet hookar in dotnet run så att det anropar winapp run och startar appen med identitet. Projekt som du skapar med winapp new refererar redan till paketet, så dotnet run fungerar utan extra installation. För andra projekt lägger du till paketet först:

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

Du kan skicka winapp run alternativ som WinAppRun* MSBuild-egenskaper, till exempel dotnet run -p:WinAppRunDebugOutput=true. Om du vill inaktivera integreringen ställer du in EnableWinAppRunSupport på false i projektfilen. Se stöd för dotnet run.

Felsökning av krascher

Lägg till --debug-output för att samla in OutputDebugString-meddelanden och förstachansundantag medan appen körs. När en WinUI-app misslyckas med en stowed exception analyserar winapp CLI kraschdumpen och skriver ut det ursprungliga felet och anropsstacken i stället för en allmän felkod.

winapp run --debug-output

Lägg till --symbols för att ladda ned symboler för fullständiga inbyggda funktionsnamn. Eftersom --debug-output bifogar winapp CLI som felsökningsprogram kan du inte koppla Visual Studio eller något annat felsökningsprogram till samma process. Om du vill felsöka med din IDE i stället, se Felsökning med winapp CLI. Mer information om stowed-exception-analysen finns i WinUI stowed-exception triage.

Hitta kontroller och API:er

winapp find-uisöker efter XAML- och C#-exempel från WinUI-galleriet och Windows Community Toolkit utifrån avsikt och returnerar koden för ett scenario som du väljer. winapp find-api söker i Windows- och WinRT API-ytan som ditt projekt refererar till, till exempel Windows App SDK och Windows SDK-typer, medlemmar och uppräkningar.

# 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

Båda kommandona stöder --json, så AI-kodningsagenter kan använda dem för att välja kontroller och verifiera API-namn. Mer information finns i referenserna find-ui och find-api .

Automatisera och verifiera användargränssnittet

winapp ui kör en app som körs via Microsoft UI Automation. Använd det för att inspektera elementträdet, anropa kontroller, vänta på tillståndsändringar och ta skärmbilder. Agenter kan använda samma kommandon för att kontrollera sina egna ändringar.

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

Väljaren PART_PaneToggleButton riktar in sig på menyknappen i mallen winui-navview . För dina egna kontroller kopierar du en väljare från utdata från winapp ui inspect eller winapp ui search.

Om du vill köra appen i Windows Sandbox i stället för på skrivbordet lägger du till --on sandbox i winapp run och winapp ui. Läs mer i UI-automatisering och sandboxkörning.

Paketera och signera

När du är redo att testa ett paket lokalt genererar du ett utvecklingscertifikat vars utgivare matchar manifestet och skapar och paketar sedan projektet i ett steg:

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

winapp pack bygger projektet och skapar en signerad .msix. Information om hur du kombinerar byggen för flera arkitekturer till en .msixbundlefinns i Paket med flera arkitekturer. Projektet måste paketeras, så ett projekt som ställer in WindowsPackageType till None inte kan packas. För WinUI-projekt äger Windows App SDK-bygget manifestet, startpunkten och resursgenereringen, så --manifest, --executable och --skip-pri accepteras inte.

Utvecklingscertifikatet är endast avsett för lokal testning och använder ett standardlösenord. Innan du distribuerar din app signerar du den med ett betrott certifikat, till exempel med winapp az-sign och Betrodd Azure-signering. Mer information finns i Paketera ett projekt direkt och Säkerhet.

Befintliga WinUI-projekt

winapp CLI fungerar med WinUI-projekt som du skapade i Visual Studio. Peka ut winapp run projektfilen, lösningsfilen eller mappen som innehåller någon av dem. För winapp pack, ange .csproj. Du kan fortsätta att bygga och felsöka i Visual Studio och använda winapp CLI för skript, CI och agentarbetsflöden.

WinUI med C++

winapp runbygger och startar även C++/WinRT WinUI-projekt (.vcxproj) som du skapade från Visual Studio-mallen Tom WinUI-app (paketerad). Det bygger projektet med Visual Studio MSBuild, registrerar appen med paketidentitet och startar den:

winapp run .\MyApp.vcxproj

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

C++-projekt kräver Visual Studio eller Build Tools för Visual Studio med arbetsbelastningen Skrivbordsutveckling med C++ och C++ WinUI-apputvecklingsverktyg. winapp pack bygger inte .vcxproj-projekt, så skapa MSIX-paketet i Visual Studio. Förutsättningar och alternativ finns i C++-projekt (.vcxproj). Information om C++-appar som inte använder WinUI finns i Använda winapp CLI med C++.

Samples

  • winui-app: en paketerad WinUI-app med kontroller som konfigurerats för winapp ui automatisering
  • winui-unpackaged-app: en WinUI-app som körs utan paketidentitet
  • winui-solution: en lösning för flera projekt som visar hur winapp run väljer appprojektet
  • cpp-winui-app: en paketerad C++/WinRT WinUI-app (Visual Studio .vcxproj med XAML) som körs medwinapp run

Nästa steg

  • Uppdaterades senast