Korzystanie z interfejsu wiersza polecenia winapp z platformą WinUI

W tym przewodniku pokazano, jak używać interfejsu wiersza polecenia winapp w całym cyklu wewnętrznym tworzenia aplikacji WinUI 3: tworzenia projektu na podstawie oficjalnego szablonu, kompilowania i uruchamiania go przy użyciu tożsamości pakietu aplikacji, debugowania awarii, znajdowania kontrolek i interfejsów API, automatyzowania interfejsu użytkownika i tworzenia podpisanego pakietu MSIX. Każdy krok jest uruchamiany z poziomu wiersza polecenia, więc działa w dowolnym edytorze, w ciągłej integracji i z agentami kodowania sztucznej inteligencji.

Szablony projektów WinUI zawierają już Package.appxmanifest, więc nie musisz uruchamiać winapp init dla aplikacji WinUI. Jeśli dodajesz tożsamość pakietu do istniejącej aplikacji .NET, która nie korzysta z interfejsu WinUI, zobacz Using winapp CLI with .NET.

Prerequisites

  • Windows 10 w wersji 1809 lub nowszej lub Windows 11.

  • Zestaw SDK .NET w wersji 8.0.100 lub nowszej. Eksperymentalne szablony Reactor wymagają zestawu SDK .NET 10. Interfejs wiersza polecenia winapp nie instaluje łańcuchów narzędzi, dlatego winapp new i winapp run zatrzymują się z instrukcjami, jeśli brakuje zestawu SDK .NET.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Tryb dewelopera, którego system Windows wymaga do zarejestrowania aplikacji z wyników kompilacji. Włącz to w Ustawienia > System > Dla deweloperów. Aby dowiedzieć się, co to zmienia na Twoim komputerze, zobacz Zabezpieczenia.

Tworzenie aplikacji WinUI

winapp new tworzy szkielet aplikacji WinUI z oficjalnego pakietu Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Instaluje lub aktualizuje pakiet szablonów na żądanie, a następnie wywołuje za Ciebie 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

Uruchom polecenie winapp new --list , aby wyświetlić szablony w zainstalowanym pakiecie. Pakiet zawiera następujące szablony:

Template Description
winui Minimalna pusta aplikacja XAML (domyślna). Zobacz zrzut ekranu
winui-navview Aplikacja XAML z powłoką NavigationView. Zobacz zrzut ekranu
winui-tabview Aplikacja XAML z powłoką TabView. Zobacz zrzut ekranu
winui-mvvm Aplikacja XAML, która używa wzorca MVVM z biblioteką CommunityToolkit.Mvvm. Zobacz zrzut ekranu
winui-lib Biblioteka klas WinUI
winui-unittest Spakowany projekt MSTest dla testów jednostkowych WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Eksperymentalny. Aplikacje WinUI napisane tylko w języku C# bez języka XAML

Note

Szablony Reactor odwołują się do pakietów w wersji wstępnej Microsoft.UI.Reactor. Ich interfejsy API mogą ulec zmianie lub zostać usunięte w przyszłej wersji.

Dla każdej opcji zobacz opisnew poleceń.

Kompilowanie i uruchamianie przy użyciu poświadczeń

Z folderu projektu polecenie winapp run kompiluje projekt, instaluje środowisko uruchomieniowe Zestaw SDK do aplikacji systemu Windows zgodne z architekturą, jeśli go brakuje, rejestruje aplikację z tożsamością pakietu i uruchamia ją.

cd MyApp
winapp run

winapp run akceptuje plik projektu, plik solucji, folder zawierający jeden z nich lub folder danych wyjściowych kompilacji:

# 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 odczytuje właściwość projektu WindowsPackageType, aby zdecydować, jak go uruchomić. Projekt w pakiecie jest uruchamiany z tożsamością pakietową. Projekt, który ustawia WindowsPackageType na None, działa jako rozpakowana aplikacja bez tożsamości. Aby uruchomić spakietowany projekt jako niepakietowany, przekaż właściwość w wierszu polecenia:

winapp run -p WindowsPackageType=None

Inne przydatne opcje obejmują --clean wyrejestrowanie poprzedniej rejestracji i zapisanych danych aplikacji (LocalState i ustawienia), aby uzyskać czyste pierwsze uruchomienie, --no-launch zarejestrowanie bez uruchamiania aplikacji oraz --detach --json zwrócenie identyfikatora procesu i zakończyć działanie, aby skrypty i agenci mogli kontynuować pracę podczas uruchamiania aplikacji. Aby uzyskać pełną listę, zobacz tryb projektu (projekty zestawu SDK .NET).

Zamiast tego użyj polecenia dotnet run

Jeśli wolisz dotnet run, użyj Microsoft.Windows.SDK.BuildTools.WinApp pakietu NuGet. Pakiet jest podłączany dotnet run tak, aby wywoływać winapp run i uruchamiać aplikację z tożsamością. Projekty utworzone przy użyciu winapp new już odwołują się do pakietu, więc dotnet run działa bez dodatkowej konfiguracji. W przypadku innych projektów najpierw dodaj pakiet:

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

Możesz przekazać opcje winapp run jako WinAppRun* właściwości programu MSBuild, na przykład dotnet run -p:WinAppRunDebugOutput=true. Aby wyłączyć integrację, ustaw wartość EnableWinAppRunSupport na false w pliku projektu. Aby uzyskać szczegółowe informacje, zobacz dotnet run support.

Debuguj awarie

Dodaj --debug-output do przechwytywania OutputDebugString komunikatów i wyjątków pierwszej szansy podczas działania aplikacji. Gdy aplikacja WinUI zakończy się niepowodzeniem z powodu wyjątku „stowed exception”, interfejs wiersza polecenia winapp analizuje zrzut awaryjny i wyświetla oryginalny błąd i stos wywołań zamiast ogólnego kodu błędu.

winapp run --debug-output

Dodaj --symbols, aby pobrać symbole dla pełnych nazw funkcji natywnych. Ponieważ --debug-output dołącza interfejs wiersza polecenia winapp jako debuger, nie można dołączyć Visual Studio ani innego debugera do tego samego procesu. Aby zamiast tego debugować przy użyciu środowiska IDE, zobacz Debugowanie przy użyciu winapp CLI. Aby uzyskać szczegółowe informacje na temat analizy wyjątków stowed-exception, zobacz WinUI triage wyjątków stowed-exception.

Znajdź kontrolki i interfejsy API

winapp find-uiwyszukuje przykłady XAML i C# z galerii WinUI oraz zestawu narzędzi Windows Community Toolkit według intencji i zwraca kod dla wybranego scenariusza. winapp find-apiwyszukuje obszar interfejsu API Windows i WinRT, do którego odwołuje się projekt, na przykład typy, składowe i wyliczenia zestawu Zestaw SDK do aplikacji systemu Windows i 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

Oba polecenia obsługują --json, więc agenci kodowania sztucznej inteligencji mogą ich używać do wybierania kontrolek i weryfikowania nazw interfejsów API. Aby uzyskać więcej informacji, zobacz odnośniki find-ui i find-api.

Automatyzowanie i weryfikowanie interfejsu użytkownika

winapp ui steruje uruchomioną aplikacją za pośrednictwem Microsoft automatyzacja interfejsu użytkownika. Służy do inspekcji drzewa elementów, wywoływania kontrolek, oczekiwania na zmiany stanu i tworzenia zrzutów ekranu. Agenci mogą używać tych samych poleceń, aby sprawdzić własne zmiany.

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 jest przeznaczony dla przycisku menu w szablonie winui-navview . W przypadku własnych kontrolek skopiuj selektor z danych wyjściowych winapp ui inspect lub winapp ui search.

Aby uruchomić aplikację w piaskownicy Windows zamiast na pulpicie, dodaj --on sandbox do winapp run i winapp ui. Aby uzyskać więcej informacji, zobacz Automatyzacja interfejsu użytkownika i wykonywanie w piaskownicy.

Spakuj i podpisz

Gdy wszystko będzie gotowe do przetestowania pakietu lokalnie, wygeneruj certyfikat dewelopera, którego wydawca pasuje do manifestu, a następnie skompiluj i spakuj projekt w jednym kroku:

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

winapp pack buduje projekt i tworzy podpisany .msix. Aby połączyć kompilacje dla kilku architektur w jeden .msixbundle, zobacz Pakiety z wieloma architekturami. Projekt musi być spakowany, więc nie można spakować projektu, który ma wartość WindowsPackageType ustawioną na None. W przypadku projektów WinUI to kompilacja Zestaw SDK do aplikacji systemu Windows zarządza manifestem, punktem wejścia i generowaniem zasobów, więc --manifest, --executable i --skip-pri nie są akceptowane.

Certyfikat deweloperski jest przeznaczony tylko do testowania lokalnego i używa domyślnego hasła. Przed dystrybucją aplikacji podpisz ją za pomocą zaufanego certyfikatu, na przykład za pomocą winapp az-sign i Azure Trusted Signing. Aby uzyskać więcej informacji, zobacz Tworzenie pakietów projektu bezpośrednio i Zabezpieczenia.

Istniejące projekty WinUI

Interfejs wiersza polecenia winapp współpracuje z projektami WinUI utworzonymi w Visual Studio. Wskaż za pomocą winapp run plik projektu, plik rozwiązania lub folder zawierający jeden z nich. Dla winapp pack, przekaż .csproj. Możesz kontynuować tworzenie i debugowanie w Visual Studio i używać interfejsu wiersza polecenia winapp do obsługi skryptów, ciągłej integracji i przepływów pracy agenta.

WinUI z językiem C++

winapp runPonadto kompiluje i uruchamia projekty WinUI języka C++/WinRT (.vcxproj), które zostały utworzone na podstawie szablonu programu Visual Studio WinUI Blank App (Packaged). Kompiluje projekt za pomocą programu MSBuild Visual Studio, rejestruje aplikację przy użyciu tożsamości pakietu i uruchamia ją:

winapp run .\MyApp.vcxproj

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

Projekty języka C++ wymagają programu Visual Studio lub narzędzi Build Tools for Visual Studio z obciążeniem Programowanie aplikacji klasycznych w języku C++ oraz narzędziami do tworzenia aplikacji WinUI w języku C++. winapp packnie kompiluje .vcxproj projektów, więc utwórz pakiet MSIX w Visual Studio. Informacje o wymaganiach wstępnych i opcjach znajdziesz w projektach języka C++ (.vcxproj). W przypadku aplikacji języka C++, które nie korzystają z interfejsu WinUI, zobacz Używanie interfejsu wiersza polecenia winapp z językiem C++.

Samples

  • winui-app: spakowana aplikacja WinUI z kontrolkami skonfigurowanymi do automatyzacji winapp ui
  • winui-unpackaged-app: aplikacja WinUI, która działa bez tożsamości pakietu
  • winui-solution: rozwiązanie wieloprojektowe pokazujące, jak winapp run wybiera projekt aplikacji
  • cpp-winui-app: aplikacja pakietowa C++/WinRT WinUI (Visual Studio .vcxproj z językiem XAML) uruchamiana za pomocą winapp run

Następne kroki

  • Ostatnia aktualizacja o