Použití rozhraní příkazového řádku winapp s WinUI

Tento průvodce ukazuje, jak používat rozhraní příkazového řádku winapp v celé vnitřní smyčce aplikace WinUI 3: vytvořit projekt z oficiální šablony, sestavit a spustit ho pomocí identity balíčku, ladit pády aplikace, vyhledat ovládací prvky a rozhraní API, automatizovat uživatelské rozhraní a vytvořit podepsaný balíček MSIX. Každý krok se spustí z příkazového řádku, takže funguje v libovolném editoru, v CI a s AI agenty pro kódování.

Šablony projektů WinUI už obsahují Package.appxmanifest, takže pro aplikaci WinUI nemusíte spouštět winapp init. Pokud přidáváte identitu balíčku do existující aplikace .NET, která nepoužívá WinUI, přečtěte si místo toho téma Použití rozhraní příkazového řádku winapp s .NET.

Prerequisites

  • Windows 10 verze 1809 nebo novější nebo Windows 11.

  • Sada .NET SDK verze 8.0.100 nebo novější. Experimentální šablony Reactor vyžadují sadu .NET 10 SDK. Rozhraní příkazového řádku winapp neinstaluje sady nástrojů, takže se winapp new a winapp run zastaví s pokyny, pokud chybí sada .NET SDK.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Vývojářský režim, který Windows vyžaduje k registraci aplikace z výstupu sestavení. Zapněte ho v nastavení > systému > pro vývojáře. Informace o těchto změnách na vašem počítači najdete v tématu Zabezpečení.

Vytvoření aplikace WinUI

winapp new Vygeneruje kostru aplikace WinUI z oficiálního Microsoft.WindowsAppSDK.WinUI.CSharp.Templates balíčku. Nainstaluje nebo aktualizuje balíček šablony na vyžádání a pak za vás zavolá dotnet new .

# 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

Spuštěním winapp new --list zobrazíte šablony v nainstalovaném balíčku. Balíček obsahuje tyto šablony:

Template Description
winui Minimální prázdná aplikace XAML (výchozí). Viz snímek obrazovky
winui-navview Aplikace XAML se skořepinou NavigationView Viz snímek obrazovky
winui-tabview Aplikace XAML se shellem TabView Viz snímek obrazovky
winui-mvvm Aplikace XAML, která používá model MVVM s CommunityToolkit.Mvvm. Viz snímek obrazovky
winui-lib Knihovna tříd WinUI
winui-unittest Balíček projektu MSTest pro jednotkové testy WinUI
reactor, reactor-mvu, , reactor-navviewreactor-tabview Pokusný. Aplikace WinUI napsané jenom v jazyce C# bez XAML

Note

Šablony Reactor odkazují na předběžné verze Microsoft.UI.Reactor balíčků. Jejich rozhraní API se mohou v budoucí verzi změnit nebo být odebrána.

Pro každou možnost se podívejte na new reference příkazů.

Sestavení a spuštění s využitím identity

Ve složce projektu příkaz winapp run sestaví projekt, nainstaluje modul runtime Windows App SDK, který odpovídá vaší architektuře, pokud chybí, zaregistruje aplikaci s identitou balíčku a spustí ji.

cd MyApp
winapp run

winapp run přijímá soubor projektu, soubor řešení, složku, která obsahuje jeden z nich, nebo složku výstupu sestavení:

# 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

Rozhraní příkazového řádku winapp přečte vlastnost projektu WindowsPackageType a rozhodne, jak projekt spustit. Projekt v balíčku běží s identitou balíčku. Projekt, který má nastaveno WindowsPackageType na None, se spustí jako rozbalená aplikace bez identity. Pokud chcete spustit zabalený projekt jako nebalený, předejte vlastnost na příkazovém řádku:

winapp run -p WindowsPackageType=None

Mezi další užitečné možnosti patří --clean odebrání předchozí registrace a uložených dat aplikace (LocalState a nastavení) pro nové první spuštění, --no-launch registraci bez spuštění aplikace a --detach --json pro vrácení ID procesu a ukončení, aby skripty a agenti mohli dál pracovat, zatímco aplikace běží. Úplný seznam najdete v části režim Project (projekty .NET SDK).

Místo toho použijte dotnet run.

Pokud chcete dotnet run, použijte Microsoft.Windows.SDK.BuildTools.WinApp balíček NuGet. Balíček se zavěsí na dotnet run, aby volal winapp run a spustil aplikaci s identitou. Projekty, které vytvoříte pomocí winapp new, už na balíček odkazují, takže dotnet run funguje bez dalšího nastavení. V případě jiných projektů nejprve přidejte balíček:

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

Můžete předat winapp run možnosti jako WinAppRun* vlastnosti MSBuild, například dotnet run -p:WinAppRunDebugOutput=true. Pokud chcete integraci vypnout, nastavte EnableWinAppRunSupport na false v souboru projektu. Podrobnosti najdete v tématu podpora spuštění dotnet.

Ladění pádů

Přidejte --debug-output k zachycení OutputDebugString zpráv a výjimek s první šancí během běhu aplikace. Když aplikace WinUI selže se zaznamenanou výjimkou, rozhraní příkazového řádku winapp analyzuje výpis paměti po pádu a místo obecného kódu selhání vytiskne původní chybu a zásobník volání.

winapp run --debug-output

Přidejte --symbols, aby se stáhly symboly pro úplné názvy nativních funkcí. Vzhledem k tomu, že --debug-output připojí rozhraní příkazového řádku winapp jako ladicí program, nemůžete ke stejnému procesu připojit Visual Studio ani jiný ladicí program. Pokud chcete místo toho ladit integrované vývojové prostředí (IDE), přečtěte si téma Ladění pomocí rozhraní příkazového řádku winapp. Podrobnosti o analýze stowed-exception naleznete v tématu WinUI stowed-exception triage.

Najít ovládací prvky a rozhraní API

winapp find-uivyhledá ukázky XAML a C# z galerie WinUI a sady Windows Community Toolkit podle záměru a vrátí kód pro scénář, který vyberete. winapp find-apivyhledá v rozhraní API systémů Windows a WinRT, na která váš projekt odkazuje, jako jsou Windows App SDK a typy sady Windows SDK, členy a výčty.

# 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

Oba příkazy podporují --json, takže agenti pro kódování AI je můžou použít k výběru ovládacích prvků a ověření názvů rozhraní API. Další informace viz odkazy find-ui a find-api.

Automatizujte a ověřte uživatelské rozhraní

winapp ui řídí spuštěnou aplikaci prostřednictvím Microsoft model UI Automation. Slouží ke kontrole stromu elementů, vyvolání ovládacích prvků, čekání na změny stavu a pořizování snímků obrazovky. Agenti můžou ke kontrole vlastních změn použít stejné příkazy.

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

Selektor PART_PaneToggleButton cílí na tlačítko nabídky v šabloně winui-navview . Pro vlastní ovládací prvky zkopírujte selektor z výstupu winapp ui inspect nebo winapp ui search.

Pokud chcete aplikaci spustit v Windows Sandboxu místo na ploše, přidejte --on sandbox do winapp run a winapp ui. Další informace najdete v tématu Automatizace uživatelského rozhraní a spouštění sandboxu.

Zabalit a podepsat

Až budete připravení balíček otestovat místně, vygenerujte vývojový certifikát, jehož vydavatel odpovídá vašemu manifestu, a pak projekt sestavte a zabalte v jednom kroku:

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

winapp pack sestaví projekt a vytvoří podepsanou .msix. Pokud chcete zkombinovat sestavení pro několik architektur do jedné .msixbundle, podívejte se na balíčky s více architekturami. Projekt musí být zabalený, takže projekt, který nastavuje None na WindowsPackageType, nejde zabalit. U projektů WinUI sestavení Windows App SDK spravuje manifest, vstupní bod a generování prostředků, takže --manifest, --executable a --skip-pri nejsou podporovány.

Vývojový certifikát je určený jenom pro místní testování a používá výchozí heslo. Před distribucí aplikace ji podepište pomocí důvěryhodného certifikátu, například pomocí winapp az-sign a Důvěryhodné podepisování Azure. Další informace naleznete v tématu Balení projektu přímo a zabezpečení.

Existující projekty WinUI

Rozhraní příkazového řádku winapp funguje s projekty WinUI, které jste vytvořili v Visual Studio. Vyberte pomocí winapp run soubor projektu, soubor řešení nebo složku, která některý z nich obsahuje. Pro winapp pack předejte .csproj. V Visual Studio můžete pokračovat v sestavování a ladění a používat rozhraní příkazového řádku winapp pro skripty, CI a pracovní postupy agenta.

WinUI s C++

winapp run také sestaví a spustí projekty C++/WinRT WinUI (.vcxproj), které jste vytvořili ze šablony Visual Studio WinUI Blank App (Packaged). Sestaví projekt pomocí nástroje MSBuild Visual Studio, zaregistruje aplikaci s identitou balíčku a spustí ji:

winapp run .\MyApp.vcxproj

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

Projekty C++ potřebují Visual Studio nebo nástroje sestavení pro Visual Studio s úlohou Desktop development with C++ a nástroji pro vývoj aplikací C++ WinUI. winapp pack nesestaví projekty .vcxproj, takže vytvořte balíček MSIX v Visual Studiu. Informace o požadavcích a možnostech najdete v tématu Projekty C++ (.vcxproj). Informace o aplikacích C++, které nepoužívají WinUI, najdete v tématu Použití rozhraní příkazového řádku winapp s C++.

Samples

  • winui-app: Zabalená aplikace WinUI s ovládacími prvky nastavenými pro winapp ui automatizaci
  • winui-unpackaged-app: aplikace WinUI, která běží bez identity balíčku
  • winui-solution: Víceprojektové řešení, které ukazuje, jak winapp run vybírá projekt aplikace.
  • cpp-winui-app: zabalená aplikace C++/WinRT WinUI (Visual Studio .vcxproj s XAML), která běží swinapp run

Další kroky

  • Poslední aktualizace v