A WinApp CLI használata a WinUI-val

Ez az útmutató bemutatja, hogyan használhatja a Winapp CLI-t egy WinUI 3-alkalmazás teljes fejlesztési ciklusában: hogyan hozhat létre egy projektet egy hivatalos sablonból, hogyan fordíthatja le és indíthatja el csomagazonossággal, összeomlások hibakeresése, vezérlők és API-k keresése, a felhasználói felület automatizálása és aláírt MSIX-csomag létrehozása. Minden lépés a parancssorból fut, így bármely szerkesztőben, CI-ben és AI-alapú kódolóügynökökkel is működik.

A WinUI-projektsablonok már tartalmaznak egy Package.appxmanifest elemet, így WinUI-alkalmazáshoz nem kell futtatnia a(z) winapp init parancsot. Ha olyan meglévő .NET alkalmazáshoz ad hozzá csomagidentitást, amely nem használja a WinUI-t, olvassa el helyette a Winapp CLI használata .NET című témakört.

Prerequisites

  • Windows 10 1809-es vagy újabb verziója, illetve Windows 11.

  • A .NET SDK 8.0.100-es vagy újabb verziója. A kísérleti Reactor-sablonokhoz a .NET 10 SDK szükséges. A Winapp CLI nem telepíti az eszközláncokat, ezért a winapp new és winapp run leáll, és útmutatást ad, ha hiányzik a .NET SDK.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Fejlesztői mód, amelyet a Windows megkövetel az alkalmazás buildkimenetből való regisztrálásához. Kapcsolja be a(z) Beállítások > Rendszer > Fejlesztőknek menüben. Hogy ez mit változtat a számítógépén, lásd: Biztonság.

WinUI-alkalmazás létrehozása

winapp new a egy WinUI-alkalmazást hoz létre a hivatalos Microsoft.WindowsAppSDK.WinUI.CSharp.Templates csomagból. Igény szerint telepíti vagy frissíti a sabloncsomagot, majd meghívja dotnet new Önt.

# 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

Futtassa a winapp new --list parancsot a telepített csomag sablonjainak megtekintéséhez. A csomag az alábbi sablonokat tartalmazza:

Template Description
winui Minimális üres XAML-alkalmazás (alapértelmezett). Lásd a képernyőképet
winui-navview XAML-alkalmazás NavigationView-felülettel. Lásd a képernyőképet
winui-tabview XAML-alkalmazás TabView-felülettel. Lásd a képernyőképet
winui-mvvm XAML-alkalmazás, amely az MVVM-mintát használja a CommunityToolkit.Mvvm használatával. Lásd a képernyőképet
winui-lib WinUI osztálykódtár
winui-unittest Csomagolt MSTest-projekt WinUI-egységtesztekhez
reactor, reactor-mvu, reactor-navview, reactor-tabview Kísérleti. Csak C# nyelven írt WinUI-alkalmazások XAML nélkül

Note

A Reactor-sablonok előzetes Microsoft.UI.Reactor csomagokra hivatkoznak. Az API-k egy későbbi kiadásban módosíthatók vagy eltávolíthatók.

Minden beállításhoz tekintse meg a newparancshivatkozást.

Fordítás és futtatás identitással

A projektmappából winapp run felépíti a projektet, telepíti az architektúrának megfelelő Windows App SDK futtatókörnyezetet, ha az hiányzik, regisztrálja az alkalmazást a csomag identitásával, és elindítja azt.

cd MyApp
winapp run

winapp run Elfogadja a projektfájlt, a solutionfájlt, az egyiket tartalmazó mappát vagy a buildkimenet mappáját:

# 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

A winapp CLI felolvassa a projekt WindowsPackageType tulajdonságát, hogy eldöntse, hogyan kell elindítani. A csomagolt projekt csomagidentitással fut. Az a projekt, amely a(z) WindowsPackageType értékét None értékre állítja, kicsomagolatlan alkalmazásként, identitás nélkül fut. Csomagolt projekt csomagolatlanként való futtatásához adja át a tulajdonságot a parancssorban:

winapp run -p WindowsPackageType=None

További hasznos lehetőségek közé tartozik --clean az előző regisztráció és az alkalmazás mentett adatainak (LocalState és beállítások) eltávolítása egy tiszta első futtatáshoz, --no-launch a regisztráció az alkalmazás indítása nélkül, valamint --detach --json a folyamatazonosító visszaadása és kilépés, hogy a szkriptek és ügynökök továbbra is működhessenek, miközben az alkalmazás fut. A teljes listát lásd: Project mode (.NET SDK projects).

Használd inkább a dotnet run parancsot.

Ha inkább a(z) dotnet run megoldást részesíti előnyben, használja a Microsoft.Windows.SDK.BuildTools.WinApp NuGet-csomagot. A csomag úgy csatlakozik be a folyamatba, hogy meghívja a(z) winapp run elemet, és identitással indítja el az alkalmazást a(z) dotnet run használatával. Az Ön által winapp new létrehozott projektek már hivatkoznak a csomagra, ezért dotnet run további beállítás nélkül működik. Más projektek esetében először adja hozzá a csomagot:

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

Az opciókat dotnet run -p:WinAppRunDebugOutput=trueWinAppRun* MSBuild-tulajdonságként is átadhatja, például winapp run. Az integráció kikapcsolásához állítsa a projektfájlban a(z) EnableWinAppRunSupport elemet false értékre. További információ: dotnet run support.

Összeomlások hibakeresése

Az alkalmazás futása közben adja hozzá a(z) OutputDebugString--debug-output üzeneteket és az első esélyként kezelt kivételeket rögzítéséhez. Ha egy WinUI-alkalmazás stowed exceptionnel meghiúsul, a Winapp CLI elemzi az összeomlási memóriaképet, és általános hibakód helyett kinyomtatja az eredeti hibát és hívási vermet.

winapp run --debug-output

Adja hozzá --symbols-t a teljes natív függvénynevek szimbólumainak letöltéséhez. Mivel --debug-output a winapp parancssori felületét hibakeresőként csatolja, nem csatolhatja a Visual Studiót vagy egy másik hibakeresőt ugyanahhoz a folyamathoz. Ha inkább az IDE-vel szeretne hibakeresést végezni, tekintse meg a Hibakeresés a winapp CLI-val. A stowed-exception elemzésével kapcsolatos részletekért lásd: WinUI stowed-exception triage.

Vezérlők és API-k keresése

winapp find-uiXAML- és C#-mintákat keres a WinUI-katalógusból és a Windows közösségi eszközkészletből szándék szerint, és az Ön által kiválasztott forgatókönyv kódját adja vissza. winapp find-apiMegkeresi a projekt által hivatkozott Windows és WinRT API-felületet, például Windows App SDK- és Windows SDK-típusokat, tagokat és enumerációkat.

# 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

Mindkét parancs támogatja --json, így az AI kódolási ügynökei vezérlők kiválasztására és API-nevek ellenőrzésére használhatják őket. További információkért tekintse meg a find-api és find-ui hivatkozásokat.

Automatizálja és ellenőrizze a felhasználói felületet

winapp ui egy futó alkalmazást vezérel a Microsoft UI-automatizálás segítségével. Segítségével megvizsgálhatja az elemfát, vezérlőket hívhat meg, várhatja az állapotváltozásokat, és képernyőképeket készíthet. Az ügynökök ugyanezekkel a parancsokkal ellenőrizhetik saját módosításaikat.

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

A PART_PaneToggleButton választó a winui-navview sablon menügombját célozza meg. A saját vezérlőihez másolja ki a szelektort a winapp ui inspect vagy a winapp ui search kimenetéből.

Ha az alkalmazást nem az asztalon, hanem Windows Sandboxban szeretné futtatni, adja hozzá a(z) --on sandbox elemet a winapp run és winapp ui elemhez. További információ: UI-automatizálás és homokozó-végrehajtás.

Csomagolás és aláírás

Ha készen áll egy csomag helyi tesztelésére, hozzon létre egy fejlesztési tanúsítványt, amelynek kiadója megfelel a jegyzékfájljának, majd egy lépésben hozza létre és csomagolja be a projektet:

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

winapp pack lefordítja a projektet, és létrehoz egy aláírt .msix. Ha több architektúrához készült buildeket szeretne egybe .msixbundleegyesíteni, tekintse meg a többarchitektúra-csomagokat. A projektet csomagolni kell, így az a projekt, amelyben a(z) WindowsPackageType értéke None, nem csomagolható. WinUI-projektek esetén a Windows App SDK build kezeli a manifestet, a belépési pontot és az erőforrások létrehozását, ezért a --manifest, a --executable és a --skip-pri nem elfogadott.

A fejlesztési tanúsítvány csak helyi teszteléshez használható, és alapértelmezett jelszót használ. Az alkalmazás terjesztése előtt írja alá egy megbízható tanúsítvánnyal, például a winapp az-sign és az Megbízható Azure-aláírás használatával. További információ: Projekt közvetlen csomagolása és Biztonság.

Meglévő WinUI-projektek

A Winapp CLI az Ön által a Visual Studióban létrehozott WinUI-projektekkel működik. Mutasson winapp run a projektfájlra, a megoldásfájlra vagy arra a mappára, amely ezek egyikét tartalmazza. A(z) winapp pack esetén adja át a(z) .csproj-t. Továbbra is folytathatja a fejlesztést és hibakeresést végezhet a Visual Studióban, és használhatja a Winapp CLI-t szkriptekhez, CI-hez és ügynök-munkafolyamatokhoz.

WinUI a C++ használatával

winapp runEmellett létrehozza és elindítja azokat a C++/WinRT WinUI-projekteket is (), amelyeket a Visual Studio .vcxproj sablonnal hozott létre. Létrehozza a projektet Visual Studio MSBuildjével, regisztrálja az alkalmazást a csomag identitásával, és elindítja azt:

winapp run .\MyApp.vcxproj

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

A C++ projektekhez Visual Studio vagy Build Tools for Visual Studio szükséges a(z) Asztali fejlesztés C++ használatával számítási feladattal és a(z) C++ WinUI alkalmazásfejlesztő eszközökkel. winapp pack nem fordítja le a .vcxproj projekteket, ezért hozza létre az MSIX-csomagot a Visual Studióban. Az előfeltételekről és lehetőségekről a C++ projektek (.vcxproj) című témakörben olvashat. A WinUI-t nem használó C++ alkalmazások esetén lásd: A winapp CLI használata C++-szal.

Samples

  • winui-app: egy csomagolt WinUI-alkalmazás, amely winapp ui-automatizálásra beállított vezérlőkkel rendelkezik
  • winui-unpackaged-app: egy WinUI-alkalmazás, amely csomagidentitás nélkül fut
  • winui-solution: többprojektes megoldás, amely bemutatja, hogyan történik az alkalmazásprojekt kiválasztása a(z) winapp run által
  • cpp-winui-app: egy csomagolt C++/WinRT WinUI-alkalmazás (Visual Studio .vcxproj-ban, XAML-lel), amely a következővel fut: winapp run

További lépések

  • Utolsó frissítés időpontja: