Menggunakan winapp CLI dengan WinUI

Panduan ini menunjukkan cara menggunakan CLI winapp di seluruh siklus inner loop aplikasi WinUI 3: membuat proyek dari templat resmi, membangun dan meluncurkannya dengan identitas paket, men-debug crash, menemukan kontrol dan API, mengotomatiskan UI, dan menghasilkan paket MSIX yang ditandatangani. Setiap langkah dijalankan melalui baris perintah, sehingga berfungsi di editor apa pun, di CI, dan dengan agen pengkodian AI.

Templat proyek WinUI sudah menyertakan Package.appxmanifest, sehingga Anda tidak perlu menjalankan winapp init untuk aplikasi WinUI. Jika Anda menambahkan identitas paket ke aplikasi .NET yang sudah ada yang tidak menggunakan WinUI, lihat Menggunakan CLI winapp dengan .NET sebagai gantinya.

Prerequisites

  • Windows 10 versi 1809 atau yang lebih baru, atau Windows 11.

  • SDK .NET, versi 8.0.100 atau yang lebih baru. Templat Reaktor eksperimental memerlukan .NET 10 SDK. winapp CLI tidak menginstal toolchain, jadi winapp new dan winapp run berhenti dengan panduan jika SDK .NET hilang.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Mode Pengembang, yang diperlukan Windows untuk mendaftarkan aplikasi dari hasil build Anda. Aktifkan di Pengaturan > Sistem > Untuk pengembang. Untuk mengetahui perubahan yang dilakukan ini pada komputer Anda, lihat Keamanan.

Membuat aplikasi WinUI

winapp new membuat kerangka aplikasi WinUI dari paket resmi Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Ini menginstal atau memperbarui paket templat sesuai permintaan dan kemudian memanggil dotnet new untuk Anda.

# 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

Jalankan winapp new --list untuk melihat templat dalam paket yang diinstal. Paket ini mencakup templat-templat berikut:

Template Description
winui Aplikasi XAML kosong minimal (default). Lihat cuplikan layar
winui-navview Aplikasi XAML dengan shell NavigationView. Lihat cuplikan layar
winui-tabview Aplikasi XAML dengan shell TabView. Lihat cuplikan layar
winui-mvvm Aplikasi XAML yang menggunakan pola MVVM dengan CommunityToolkit.Mvvm. Lihat cuplikan layar
winui-lib Pustaka kelas WinUI
winui-unittest Proyek MSTest paket untuk pengujian unit WinUI
reactor,reactor-mvu,reactor-navview,reactor-tabview Eksperimen. Hanya aplikasi WinUI yang ditulis dalam C#, tanpa XAML

Note

Templat Reactor mereferensikan Microsoft.UI.Reactor paket prarilis. API mereka dapat berubah atau dihapus dalam rilis mendatang.

Untuk setiap opsi, lihat new referensi perintah.

Build dan jalankan dengan identitas

Dari folder proyek, perintah winapp run membangun proyek, menginstal runtime SDK Aplikasi Windows yang cocok dengan arsitektur Anda jika belum terpasang, mendaftarkan aplikasi dengan identitas paket, dan meluncurkannya.

cd MyApp
winapp run

winapp run menerima file proyek, file solusi, folder yang berisi salah satunya, atau folder output build:

# 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 membaca properti proyek WindowsPackageType untuk memutuskan cara meluncurkannya. Proyek paket berjalan dengan package identity. Proyek yang menetapkan WindowsPackageType ke None berjalan sebagai aplikasi yang tidak dikemas tanpa identitas. Untuk menjalankan proyek yang dikemas sebagai proyek tanpa paket, teruskan properti pada baris perintah:

winapp run -p WindowsPackageType=None

Opsi berguna lainnya termasuk --clean untuk menghapus pendaftaran sebelumnya dan data tersimpan aplikasi (LocalState dan pengaturan) agar aplikasi berjalan pertama kali dari awal, --no-launch untuk mendaftar tanpa memulai aplikasi, dan --detach --json untuk mengembalikan ID proses dan keluar sehingga skrip dan agen dapat tetap berfungsi saat aplikasi berjalan. Untuk daftar lengkapnya, lihat mode Proyek (proyek .NET SDK).

Gunakan dotnet run sebagai gantinya

Jika Anda lebih suka dotnet run, gunakan paket NuGet Microsoft.Windows.SDK.BuildTools.WinApp. Paket memasang hook pada dotnet run sehingga memanggil winapp run dan meluncurkan aplikasi dengan identitas. Proyek yang Anda buat dengan winapp new sudah mereferensikan paket, jadi dotnet run berfungsi tanpa penyiapan tambahan. Untuk proyek lain, tambahkan paket terlebih dahulu:

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

Anda dapat meneruskan winapp run opsi sebagai WinAppRun* properti MSBuild, misalnya dotnet run -p:WinAppRunDebugOutput=true. Untuk menonaktifkan integrasi, atur EnableWinAppRunSupport ke false dalam file proyek. Untuk detailnya, lihat dukungan dotnet run.

Debug kerusakan aplikasi

Tambahkan --debug-output untuk merekam pesan OutputDebugString dan pengecualian kesempatan pertama saat aplikasi berjalan. Ketika aplikasi WinUI gagal dengan pengecualian tersimpan, winapp CLI menganalisis crash dump dan mencetak kesalahan asli dan tumpukan panggilan alih-alih kode kegagalan generik.

winapp run --debug-output

Tambahkan --symbols untuk mengunduh simbol untuk nama fungsi native lengkap. Karena --debug-output melampirkan winapp CLI sebagai debugger, Anda tidak dapat melampirkan Visual Studio atau debugger lain ke proses yang sama. Untuk men-debug dengan IDE Anda, lihat Penelusuran kesalahan dengan CLI winapp. Untuk detail tentang analisis stowed-exception, lihat Triase stowed-exception WinUI.

Menemukan kontrol dan API

winapp find-uimencari sampel XAML dan C# dari Galeri WinUI dan Windows Community Toolkit berdasarkan tujuan pencarian, dan mengembalikan kode untuk skenario yang Anda pilih. winapp find-apimenelusuri permukaan API Windows dan WinRT yang dirujuk proyek Anda, seperti jenis, anggota, dan enum SDK Aplikasi Windows dan 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

Kedua perintah mendukung --json, sehingga agen pengkodian AI dapat menggunakannya untuk memilih kontrol dan memverifikasi nama API. Untuk informasi selengkapnya, lihat referensi find-ui dan find-api.

Mengotomatisasi dan memverifikasi UI

winapp ui mengontrol aplikasi yang sedang berjalan melalui Microsoft UI Automation. Gunakan untuk memeriksa pohon elemen, memanggil kontrol, menunggu perubahan status, dan mengambil cuplikan layar. Agen dapat menggunakan perintah yang sama untuk memeriksa suntingan mereka sendiri.

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

Pemilih PART_PaneToggleButton menargetkan tombol menu dalam winui-navview templat. Untuk kontrol Anda sendiri, salin pemilih dari output winapp ui inspect atau winapp ui search.

Untuk menjalankan aplikasi di Windows Sandbox alih-alih di desktop Anda, tambahkan --on sandbox ke winapp run dan winapp ui. Untuk informasi selengkapnya, lihat Otomatisasi UI dan eksekusi Sandbox.

Kemas dan tandatangani

Saat Anda siap untuk menguji paket secara lokal, buat sertifikat pengembangan yang penerbitnya cocok dengan manifes Anda, lalu buat dan kemas proyek dalam satu langkah:

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

winapp pack membangun proyek dan menghasilkan .msix yang ditandatangani. Untuk menggabungkan build untuk beberapa arsitektur menjadi satu .msixbundle, lihat Bundel multi-arsitektur. Proyek harus dikemas, sehingga proyek yang menetapkan WindowsPackageType ke None tidak dapat dikemas. Untuk proyek WinUI, build SDK Aplikasi Windows mengelola manifes, titik masuk, dan pembuatan sumber daya, jadi --manifest, --executable, dan --skip-pri tidak diterima.

Sertifikat pengembangan hanya untuk pengujian lokal, dan menggunakan kata sandi default. Sebelum mendistribusikan aplikasi Anda, tanda tangani aplikasi Anda dengan sertifikat tepercaya, misalnya dengan winapp az-sign dan Penandatanganan Tepercaya Azure. Untuk informasi selengkapnya, lihat Mengemas proyek secara langsung dan Keamanan.

Proyek WinUI yang ada

winapp CLI bekerja dengan proyek WinUI yang Anda buat di Visual Studio. Arahkan winapp run ke file proyek, file solusi, atau folder yang berisi file tersebut. Untuk winapp pack, teruskan .csproj. Anda dapat terus membangun dan menelusuri kesalahan di Visual Studio dan menggunakan CLI winapp untuk alur kerja skrip, CI, dan agen.

WinUI dengan C++

winapp runjuga membangun dan meluncurkan proyek C++/WinRT WinUI (.vcxproj) yang Anda buat dari templat Visual Studio WinUI Blank App (Packaged). Ini membangun proyek dengan MSBuild Visual Studio, mendaftarkan aplikasi dengan identitas paket, dan meluncurkannya:

winapp run .\MyApp.vcxproj

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

Proyek C++ memerlukan Visual Studio atau Build Tools untuk Visual Studio dengan pengembangan Desktop dengan workload C++ dan alat pengembangan aplikasi C++ WinUI. winapp pack tidak dapat mengompilasi .vcxproj proyek, jadi buat paket MSIX di Visual Studio. Untuk prasyarat dan opsi, lihat proyek C++ (.vcxproj). Untuk aplikasi C++ yang tidak menggunakan WinUI, lihat Menggunakan CLI winapp dengan C++.

Samples

  • winui-app: aplikasi WinUI dalam paket dengan kontrol yang disiapkan untuk otomatisasi winapp ui
  • winui-unpackaged-app: aplikasi WinUI yang berjalan tanpa identitas paket
  • winui-solution: solusi multi-proyek yang menunjukkan bagaimana winapp run memilih proyek aplikasi
  • cpp-winui-app: aplikasi C++/WinRT WinUI paket (Visual Studio .vcxproj dengan XAML) yang berjalan denganwinapp run

Langkah berikutnya

  • Terakhir diperbarui pada