Dokumentasi dan Penggunaan CLI

Penyelesaian Shell

Aktifkan penyelesaian tab untuk perintah, opsi, dan nilai. Lihat panduan Penyelesaian Shell untuk instruksi penyiapan.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

inisialisasi

Menginisialisasi direktori dengan Windows SDK, SDK Aplikasi Windows, dan aset yang diperlukan untuk pengembangan Windows modern.

winapp init [base-directory] [options]

Argumen:

base-directory - Direktori dasar/akar untuk aplikasi/ruang kerja (default: direktori saat ini)

Opsi:

--config-dir <path> - Direktori untuk membaca/menyimpan konfigurasi (default: direktori proyek yang dipilih, atau direktori saat ini jika tidak ada proyek yang terdeteksi)
--setup-sdks - Mode penginstalan SDK: 'stabil' (default), 'pratinjau', 'eksperimental', atau 'tidak ada' (lewati penginstalan SDK)
--ignore-config, --no-config - Jangan gunakan file konfigurasi untuk manajemen versi
--no-gitignore - Jangan perbarui file .gitignore
--use-defaults, --no-prompt - Jangan meminta, dan menggunakan default semua perintah
--config-only - Hanya menangani operasi file konfigurasi, lewati penginstalan paket
--exe <path> - Jalur ke aplikasi yang dapat dieksekusi. Membutuhkan --sparse. Menghasilkan manifes jarang khusus identitas untuk exe alih-alih penyiapan paket/SDK lengkap.
--sparse - Hasilkan manifes identitas jarang (appxmanifest.xml) untuk exe desktop yang ada. Melewati penginstalan SDK/paket. Gunakan dengan --exe.
--name <name> - Ambil alih nama paket (jarang saja; default: disimpulkan dari exe)
--publisher <CN> - Mengambil alih penerbit CN (hanya jarang; default: disimpulkan dari nama perusahaan exe)
--output-dir <path> - Direktori untuk menulis manifes jarang dan Assets/ (hanya jarang; default: sparse/ folder di direktori saat ini)
--force - Timpa yang ada appxmanifest.xml di direktori target (hanya jarang). Tanpa itu, init gagal alih-alih mengganti manifes/aset yang ada.
--add-js-bindings (hanya npm) - Tambahkan winapp.jsBindings ke package.json dan hasilkan pengikatan JS/TypeScript, tanpa meminta (tidak kompatibel dengan --setup-sdks none)

Apa fungsinya:

winapp.yaml Membuat file konfigurasi (hanya ketika paket SDK dikelola; dilewati dengan --setup-sdks none)
Mengunduh paket Windows SDK dan SDK Aplikasi Windows
Menghasilkan header dan biner C++/WinRT
Membuat Package.appxmanifest
Menyiapkan alat build dan mengaktifkan mode pengembang
Memperbarui .gitignore untuk mengecualikan file yang dihasilkan
Menyimpan file yang dapat dibagikan di direktori cache global
Menghasilkan pengikatan JS untuk API SDK Aplikasi Windows saat diaktifkan (hanya npm)

Deteksi proyek otomatis:

Ketika init dijalankan tanpa argumen direktori, ia melakukan pencarian luas-pertama dari pohon direktori saat ini untuk menemukan proyek yang kompatibel (hingga 10). Jenis proyek yang didukung:

Tauri — tauri.conf.json ditemukan satu tingkat di bawah direktori
Elektron — package.json dengan electron dalam dependensi atau devDependencies
Flutter — pubspec.yaml di akar proyek
.NET — .csproj di akar proyek
Rust — Cargo.toml di akar proyek
C++ — CMakeLists.txt di akar proyek

Pencarian melewati direktori yang umumnya diabaikan (node_modules, bin, obj, .git, dll.). Ketika proyek yang kompatibel ditemukan, subdirektori di bawahnya tidak dicari.

Jika argumen direktori disediakan (misalnya, winapp init . atau winapp init path/to/project), pencarian dilewati dan init hanya memeriksa direktori tersebut untuk proyek yang kompatibel
Jika --use-defaults (atau --no-prompt) diatur tanpa argumen direktori, init lewati pencarian dan inisialisasi direktori saat ini secara non-interaktif, peringatan terlebih dahulu jika tidak ada jenis proyek yang diketahui terdeteksi di sana (misalnya, winapp init --use-defaults)
Di lingkungan non-interaktif (piped stdin, CI, input yang dialihkan), init secara otomatis menggunakan --use-defaults perilaku dan memancarkan peringatan: Non-interactive environment detected. Using default values.
Jika direktori saat ini adalah proyek yang kompatibel, init segera dilanjutkan
Jika tepat satu proyek ditemukan di tempat lain, Anda diminta untuk mengonfirmasi
Jika beberapa proyek ditemukan, Anda dapat memilih proyek mana yang akan diinisialisasi — direktori saat ini selalu tersedia sebagai opsi fallback
Jika tidak ada proyek yang ditemukan, Anda diperingatkan dan ditanya apakah akan tetap melanjutkan
Jika pencarian mencapai batas 10 proyek, peringatan menyarankan untuk memberikan argumen direktori

Alur proyek .NET otomatis:

Ketika file .csproj ditemukan di direktori target, init menggunakan alur khusus .NET yang disederhanakan:

Memvalidasi dan memperbarui TargetFramework ke TFM yang kompatibel dengan Windows (misalnya, net10.0-windows10.0.26100.0)
Menambahkan Microsoft.WindowsAppSDK dan Microsoft.Windows.SDK.BuildTools sebagai entri NuGet PackageReference langsung di .csproj
Menghasilkan Package.appxmanifest, aset, dan sertifikat pengembangan
Tidak membuat winapp.yaml atau mengunduh proyeksi C++ (gunakan dotnet restore untuk paket NuGet)

Mode identitas jarang (--exe + --sparse):

Menghasilkan manifes paket jarang khusus identitas untuk desktop yang ada yang dapat dieksekusi — langkah pertama alur kerja kemasan jarang. Tidak seperti alur penuh init , ini melewati semua penginstalan SDK/paket (paket identitas jarang tidak memiliki dependensi SDK) dan hanya menghasilkan aset manifes dan tempat penampung.

Menyimpulkan nama paket, penerbit, deskripsi, dan versi dari exe melalui FileVersionInfo (ambil alih dengan --name, , --publisheratau secara interaktif)
appxmanifest.xml Menulis (dengan nama exe diganti menjadi Executable) ditambah Assets/ folder ke sparse/ folder di direktori saat ini (atau --output-dir)
--use-defaults / --no-prompt Menggunakan untuk melewati perintah penimpaan interaktif (ramah CI)
--exe tanpa --sparse kesalahan

Aset bersifat eksternal. Jarang .msix hanya identitas: yang dihasilkan diselesaikan dari direktori penginstalan aplikasi (lokasi konten eksternal) pada runtime, tidak dibundel Assets/ ke .msixdalam . Sebarkan bersama aplikasi Anda.

Langkah selanjutnya setelah winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> untuk membangun identitas .msix, lalu winapp embed-identity <exe>. Lihat Panduan Kemasan Jarang untuk panduan lengkap.

Contoh:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

Tips: Menginstal SDK setelah penyiapan awal

Jika Anda menjalankan init dengan --setup-sdks none (atau melewati penginstalan SDK) dan nantinya memerlukan SDK:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

Gunakan --setup-sdks preview atau --setup-sdks experimental untuk versi SDK pratinjau/eksperimental.

baru

Buat aplikasi WinUI baru dari templat SDK Aplikasi Windows dotnet new resmi. Interaktif secara default; secara otomatis menggunakan default di lingkungan non-interaktif.

winapp new [options]

Opsi:

-t, --template <short-name>- Nama pendek templat (misalnya winui, , , winui-navviewwinui-mvvm, winui-lib, winui-unittest, atau templat Reaktor eksperimental seperti reactor atau reactor-mvu). Divalidasi terhadap paket yang diinstal pada waktu proses; jalankan winapp new --list untuk melihat semua. Default: winui (aplikasi XAML kosong).
-n, --name <name> - Nama untuk aplikasi/proyek baru (default: berasal dari --output, lainnya WinUIApp)
-o, --output <path> - Direktori untuk membuat aplikasi di (default: ./<name>)
--use-defaults, --no-prompt - Jangan minta; gunakan default (templat kosong, nama dari --output/--name, dan pertahankan paket templat yang diinstal daripada memperbaruinya)
--force - Perancah bahkan jika direktori output sudah berisi file
--template-version <latest|installed|version> - Versi paket templat WinUI: latest menginstal paket terbaru yang diterbitkan, installed menyimpan apa pun yang sudah diunduh (tidak ada jaringan), atau menyematkan versi eksplisit seperti 1.2.3. Default: instal yang terbaru ketika tidak ada paket, jika tidak, minta untuk memperbarui paket kedaluarsa (disimpan as-is di bawah --use-defaults).
--list - Cantumkan templat WinUI yang tersedia dan keluar (instal paket terbaru terlebih dahulu jika tidak ada yang diinstal)
--json - Format output sebagai JSON

Template:

Paket ini mengirimkan dua gaya aplikasi WinUI. Templat XAML menentukan UI dalam markup dengan kode C# di belakang. Templat reaktor adalah C# murni tanpa XAML, menggunakan pola MVU (Model-View-Update). Daftar templat dibaca langsung dari paket yang diinstal, sehingga selalu mencerminkan versi yang Anda miliki — jalankan winapp new --list untuk melihat set saat ini. Templat umum:

Nama pendek	Deskripsi
`winui`	Aplikasi XAML kosong minimal (kemasan MSIX)
`winui-navview`	Aplikasi pemula XAML NavigationView
`winui-tabview`	Aplikasi pemula XAML TabView
`winui-mvvm`	Aplikasi XAML MVVM (CommunityToolkit.Mvvm)
`winui-lib`	Pustaka kelas WinUI 3
`winui-unittest`	Aplikasi MSTest kemasan; pengujian berjalan saat diluncurkan
`reactor`	Eksperimen. Aplikasi Reaktor Kosong — C#murni, tanpa XAML
`reactor-mvu`	Eksperimen. Aplikasi reaktor yang menunjukkan pola MVU
`reactor-navview`	Eksperimen. Aplikasi pemula NavigationView Reaktor
`reactor-tabview`	Eksperimen. Aplikasi pemula TabView Reaktor

Templat reaktor bersifat eksperimental. Mereka mereferensikan paket prarilis Microsoft.UI.Reactor , yang APInya dapat berubah atau dihapus dalam rilis mendatang. winapp new menandai mereka (Eksperimental) di --list dan di pemilih interaktif, mengatur "Experimental": true di --json, dan mencetak peringatan setelah perancah. Mereka tidak pernah dipilih sebagai templat default. Reaktor juga memerlukan .NET 10 SDK atau yang lebih baru; pada SDK winapp new yang lebih lama gagal di depan dengan versi yang dibutuhkan daripada perancah proyek yang tidak dapat Anda bangun.

Nama pendek kanonis setiap templat adalah daftar alias pertama untuk itu; alias dotnet new apa pun yang tercantum (misalnya winui3, , wasdk-singlewinui-reactor) juga diterima. Saat dijalankan di dalam proyek WinUI yang ada, dotnet new juga menampilkan templat item (misalnya halaman kosong), yang winapp new ditambahkan ke dalam proyek saat ini daripada membuat yang baru.

Penerapan versi paket templat:

winapp new tidak lagi menyematkan versi paket templat tertentu. Jika tidak ada paket yang diinstal, paket akan menginstal yang terbaru. Jika paket yang lebih lama sudah diinstal, paket tersebut memeriksa umpan dan, ketika ada yang lebih baru, meminta apakah akan memperbarui — kecuali dalam eksekusi/--use-defaults non-interaktif, yang menyimpan paket yang diinstal. Gunakan --template-version latest untuk selalu mengambil yang terbaru tanpa meminta, atau --template-version installed untuk selalu menggunakan paket yang diunduh tanpa pemeriksaan jaringan. Meneruskan versi eksplisit (misalnya --template-version 1.2.3) selalu menginstal dengan tepat versi tersebut — menginstal ulang bahkan ketika paket yang lebih baru sudah ada — sehingga perancah dapat direproduksi di seluruh mesin.

Eksekusi pertama mungkin memakan waktu lebih lama: Menginstal atau memperbarui paket templat, atau memulihkan paket NuGet SDK Aplikasi Windows yang hilang yang digunakan oleh templat yang dipilih, dapat memerlukan unduhan tambahan. Ini juga dapat terjadi setelah versi SDK Aplikasi Windows baru diterbitkan. Jika perancah masih berjalan setelah 10 detik, winapp new perbarui pesan statusnya untuk menunjukkan bahwa paket mungkin diunduh atau dipulihkan.

Apa fungsinya:

Memverifikasi SDK .NET diinstal (gagal cepat dengan panduan jika hilang — winapp tidak menginstal toolchain)
Menginstal atau memperbarui paket templat WinUI resmi (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) sesuai permintaan
Menghitung templat yang tersedia dari paket yang diinstal dan mendelegasikan perancah ke dotnet new <short-name>

Templat aplikasi WinUI sudah menyertakan kemasan dan identitas Windows (Package.appxmanifest), sehingga tidak diperlukan langkah terpisahwinapp init. Untuk templat aplikasi, gunakan winapp run untuk membangun dan meluncurkan aplikasi. winui-lib Templat menghasilkan pustaka kelas untuk dirujuk dari proyek aplikasi (tidak memiliki manifes aplikasi). winui-unittest Templat adalah aplikasi MSTest kemasan yang pengujiannya dijalankan saat aplikasi diluncurkan (winapp run) — bukan melalui dotnet test. winapp newperancah terhadap kerangka kerja target .NET SDK yang diinstal dan mencetak langkah berikutnya yang sesuai untuk templat yang Anda pilih.

Teruskan bendera global --verbose (-v) untuk menggemakan setiap pemanggilan yang mendasar dotnet (kueri paket, pemeriksaan pembaruan, instal, dotnet new list, perancah) bersama dengan output lengkapnya - berguna untuk mendiagnosis masalah paket templat atau perancah.

Contoh:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

memulihkan

Pulihkan paket dan hasilkan ulang berkas berdasarkan konfigurasi yang ada winapp.yaml.

winapp restore [base-directory] [options]

Argumen:

base-directory - Direktori untuk memulihkan (default: direktori saat ini). Juga memilih dari mana winapp.yaml dan nuget.config dibaca kecuali --config-dir mengambil alih.

Opsi:

--config-dir <path> - Direktori yang berisi winapp.yaml (default: base-directory)

Apa fungsinya:

Membaca konfigurasi winapp.yaml yang ada
Mengunduh/memperbarui paket SDK ke versi yang ditentukan
Meregenerasi header dan biner C++/WinRT
Menyimpan file yang dapat dibagikan di direktori cache global

Nota

Untuk proyek .NET tidak winapp.yaml ada — versi SDK hidup sebagai PackageReference entri di .csproj — sehingga winapp restore berjalan dotnet restore untuk Anda.

Contoh:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Umpan NuGet kustom dan privat:

winapp init, , restoredan update unduh paket Windows SDK dan SDK Aplikasi Windows melalui NuGet, menghormati hierarki standar nuget.config Anda. Umpan dan cermin privat, info masuk umpan (termasuk penyedia kredensial), dan semua pekerjaan kustom globalPackagesFolder seperti yang mereka lakukan untuk dotnet restore. Untuk memulihkan secara eksklusif dari cermin Anda sendiri, <clear /> sumber yang diwariskan dan tambahkan hanya milik Anda:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Nota

Untuk proyek asli winapp diselesaikan nuget.config dari direktori yang dioperasikannya pada:restoreinit/argumen direktori, --config-dir ketika diberikan, jika tidak, direktori saat ini. Untuk .NET proyek, sumber berasal dari hierarki proyek sendiri nuget.config sebagai gantinya, karena itulah yang dotnet add package dan dotnet restore gunakan, jadi letakkan konfigurasi umpan privat di direktori proyek atau leluhur. Di --config-dir luar hierarki tersebut dilaporkan dan diabaikan alih-alih secara diam-diam memilih versi yang tidak dapat dipulihkan proyek. Jalankan perintah ini hanya terhadap direktori yang Anda percayai, kewaspadaan yang sama yang berlaku untuk dotnet restore. Saat beberapa sumber dikonfigurasi, gunakan Pemetaan Sumber Paket untuk menyematkan setiap paket ke umpan.

perbarui

Perbarui paket ke versi terbarunya dan perbarui file konfigurasi.

winapp update [options]

Opsi:

--setup-sdks <stable|preview|experimental|none> - Mode penginstalan SDK: stable (default), preview, experimental, atau none (lewati penginstalan SDK)

Apa fungsinya:

Membaca konfigurasi yang winapp.yaml ada di direktori saat ini
Memperbarui semua paket ke versi terbaru yang tersedia
Memperbarui file winapp.yaml dengan nomor versi baru
Meregenerasi header dan biner C++/WinRT

Contoh:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

paket

Buat paket MSIX dari proyek atau direktori aplikasi yang disiapkan. Memerlukan file manifes (Package.appxmanifest lebih disukai, appxmanifest.xml juga didukung) untuk hadir di direktori target, di direktori saat ini, atau diteruskan dengan --manifest opsi . (jalankan init atau manifest generate buat manifes)

Teruskan satu .csproj untuk membangun proyek dan mengemas outputnya dalam satu langkah (mode proyek, lihat Mengemas proyek langsung di bawah). Teruskan beberapa folder input untuk membuat .msixbundle distribusi multi-arsitektur (lihat Bundel multi-arsitektur di bawah).

winapp pack <input-folder> [input-folder...] [options]

Argumen:

input-folder - Satu .csproj untuk membangun dan mengemas (mode proyek), atau satu atau beberapa direktori yang berisi file aplikasi ke paket. Teruskan beberapa folder (misalnya, ./publish/x64 ./publish/arm64) untuk membuat bundel MSIX. Untuk paket identitas jarang, teruskan file jarang appxmanifest.xml secara langsung alih-alih folder (lihat Paket identitas jarang di bawah).

Opsi:

--output <filename> - Nama file output. Untuk paket tunggal: <name>_<version>_<arch>.msix (mundur ke <name>_<version>.msix, , <name>_<arch>.msixatau <name>.msix). Untuk bundel: <name>_<version>_<arch1>_<arch2>.msixbundle.
--name <name> - Nama paket (default: dari manifes)
--manifest <path> - Jalur ke file manifes (Package.appxmanifest lebih disukai, appxmanifest.xml juga didukung; default: deteksi otomatis)
--cert <path> - Jalur ke sertifikat penandatanganan (memungkinkan penandatanganan otomatis)
--cert-password <password> - Kata sandi sertifikat (default: "kata sandi")
--generate-cert - Membuat sertifikat pengembangan baru
--no-sign - Kirim paket yang tidak ditandatangani, menimpa konfigurasi penandatanganan proyek apa pun (misalnya untuk pengiriman Store atau alur penandatanganan eksternal). Tidak dapat digabungkan dengan --cert atau --generate-cert.
--install-cert - Menginstal sertifikat ke komputer
--publisher <name>- Publisher untuk pembuatan sertifikat. Menerima nama khusus X.500 lengkap atau nama kosong (secara otomatis dibungkus sebagai CN=<name>)
--self-contained - Runtime SDK Aplikasi Windows bundel
--skip-pri - Lewati pembuatan file PRI
--executable <path> - Jalur ke yang dapat dieksekusi relatif terhadap folder input (juga --exe). Digunakan untuk menyelesaikan $targetnametoken$ placeholder dalam berkas manifes.

opsi mode Project (memerlukan .csproj input; ditolak untuk input folder/bundel/manifes):

--configuration <name> (-c) - Konfigurasi build (default: Release)
--arch <arch> - Arsitektur target: x64, , arm64atau x86 (default: arsitektur proses saat ini)
--framework <tfm> (-f) - Moniker kerangka kerja target untuk proyek multi-target
--no-build - Mengemas output build yang ada tanpa membangun kembali
--no-restore - Lewati pemulihan proyek sebelum membangun
--property <name=value> (-p) - Properti MSBuild, diteruskan ke build dan evaluasi (dapat diulang)

Catatan: Untuk WinUI / EnableMsixTooling.csproj (mode proyek perkakas MSIX), SDK Aplikasi Windows memiliki manifes, titik masuk, dan pembuatan PRI, jadi --manifest, --executable, dan --skip-pri ditolak — konfigurasikan <AppxManifest>, titik masuk proyek, dan build sumber dayanya dalam proyek itu sendiri. Ketiga opsi tersebut masih berlaku untuk input folder dan untuk mode proyek generik (non-MSIX-tooling). .csproj

Apa fungsinya:

Memvalidasi dan memproses file Package.appxmanifest
$placeholder$ Menyelesaikan token dalam manifes (lihat Tempat penampung manifes di bawah)
Memastikan dependensi kerangka kerja yang tepat
Memperbarui manifes berdampingan dengan pendaftaran
Secara otomatis menemukan dan membundel file non-gambar yang direferensikan dalam manifes (misalnya, AppExtension manifest.json, file konfigurasi) dari direktori manifes atau folder input jika hilang dari penahapan
Secara otomatis menemukan komponen WinRT pihak ketiga dan mendaftarkan kelas yang dapat diaktifkan (lihat penemuan komponen WinRT di bawah)
Menangani penyebaran WinAppSDK mandiri
Menandatangani paket jika sertifikat disediakan

Mengemas proyek secara langsung

Ketika input adalah satu .csproj, winapp pack membangun proyek (menggunakan opsi di atas) dan mengemas output yang dihasilkan — tidak perlu membangun secara terpisah atau menemukan folder output terlebih dahulu. Ini mencerminkan winapp runmode proyek.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Arsitektur target berasal dari --arch, atau dari kesepian -p RuntimeIdentifier=<rid> ketika Anda tidak lulus --arch (RID yang tepat dipertahankan dan mendorong build). Melewati keduanya --arch dan -p RuntimeIdentifier merupakan konflik dan ditolak.

Proyek harus dibangun sebagai aplikasi paket (EnableMsixTooling=true dengan Package.appxmanifest); proyek yang dibangun sebagai aplikasi yang tidak dikemas (WindowsPackageType=None) tidak memiliki manifes MSIX untuk mengemas dan winapp pack melaporkan kesalahan yang dapat ditindaklanjuti. Input folder, bundel, dan manifes jarang tidak berubah.

mode Project menghasilkan satu .msix atau satu arsitektur saja .msixbundle (lihat Bundel multi-arsitektur). Ini tidak menghasilkan arsip Store-upload atau bundel pemisahan sumber daya (bahasa/skala): eksplisit -p UapAppxPackageBuildMode=StoreUpload atau -p AppxBundleAutoResourcePackageQualifiers=... ditolak dengan catatan untuk menjalankan perintah pengemasan SDK asli secara langsung untuk alur tersebut.

Paket identitas jarang

Ketika input adalah file jarang appxmanifest.xml (satu mendeklarasikan <uap10:AllowExternalContent>true</uap10:AllowExternalContent> di bawah <Properties>) daripada folder, winapp pack membangun hanya identitas.msix - itu hanya mengemas manifes, tanpa biner atau aset aplikasi. Ini adalah langkah 2 dari alur kerja kemasan jarang.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

Output default ke <PackageName>.identity.msix dalam direktori saat ini (ambil alih dengan --output).
Penandatanganan hanya terjadi ketika --cert (atau --generate-cert) disediakan.
Jika Anda meneruskan folder yang manifesnya AllowExternalContentmenyatakan , perilaku pengemasan folder yang ada berlaku, tetapi winapp pack memperingatkan jika menemukan aset (.ico/.jpg/.png) atau biner (.exe.dll//.so) — untuk paket jarang, ini termasuk di lokasi eksternal, bukan di dalam ..msix

Setelah mengemas, jalankan winapp embed-identity <exe> dan daftarkan paket di alat penginstal Anda dengan Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Lihat Panduan Kemasan Jarang.

Penemuan komponen WinRT

Saat pengemasan, winapp pack secara otomatis memindai paket NuGet yang ditentukan dalam winapp.yaml atau *.csproj untuk komponen WinRT pihak ketiga (misalnya, Win2D). Ini menguraikan .winmd file untuk mengekstrak nama kelas yang dapat diaktifkan dan menemukan DLL implementasinya. Entri yang ditemukan terdaftar sebagai berikut:

Framework-dependent (default): Kelas yang dapat diaktifkan ditambahkan sebagai <InProcessServer> entri dalam Package.appxmanifest
Mandiri (--self-contained): Kelas yang dapat diaktifkan disematkan dalam manifes berdampingan (SxS) dalam manifes yang dapat dieksekusi

Resolusi tempat penampung selama pengemasan:

Jika manifes berisi $targetnametoken$ dalam Executable atribut :

Jika --executable disediakan (jalur relatif terhadap folder input), tempat penampung diganti dengan nilai yang ditentukan
Jika tidak, winapp pack memindai akar folder input untuk .exe file — jika tepat satu ditemukan, itu digunakan secara otomatis
Jika nol atau beberapa .exe file ditemukan, kesalahan ditampilkan yang meminta Anda untuk menentukan --executable

Contoh:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Bundel multi-arsitektur

Ketika beberapa folder input diteruskan, winapp pack membuat yang .msixbundle berisi satu .msix per arsitektur:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

Perintah ini secara otomatis mendeteksi arsitektur setiap folder dari header PE primer yang dapat dieksekusi, memvalidasi konsistensi di seluruh irisan (Identitas, Kemampuan, Dependensi), dan menghasilkan <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Resolusi manifes untuk bundel:

Setiap ikatan dalam bundel membutuhkan manifes. Perintah menyelesaikan manifes dalam urutan ini:

--manifest <path> — Jika ditentukan, manifes tunggal ini digunakan untuk semua irisan. secara ProcessorArchitecture otomatis diperbarui per iringan agar sesuai dengan arsitektur yang terdeteksi.
Manifes per folder — Jika setiap folder input berisi Package.appxmanifest manifes folder (atau appxmanifest.xml), manifes folder tersebut digunakan untuk ikatannya.
Fallback direktori saat ini — Jika folder tidak memiliki manifes, perintah mencari Package.appxmanifest di direktori kerja saat ini dan menggunakannya (dengan arsitektur bertanda otomatis).

Dalam semua kasus, manifes diperbarui secara otomatis: tempat penampung diselesaikan, dependensi disuntikkan, dan ProcessorArchitecture diatur paksa ke arsitektur yang terdeteksi. Setelah resolusi, validasi irisan silang memastikan bahwa Identitas (Nama, Versi, Publisher), Kemampuan, dan Dependensi konsisten di semua irisan — hanya ProcessorArchitecture mungkin berbeda. Versi paket yang ditentukan dalam irisan dikaitkan ke versi bundel MSIX, kecuali jika 0.0.0.0itu , dalam hal ini versi berbasis tanda waktu dibuat secara otomatis.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

create-debug-identity

Buat identitas aplikasi untuk penelusuran kesalahan menggunakan kemasan jarang. Exe tetap berada di lokasi aslinya — Windows mengaitkan identitas dengannya melalui Add-AppxPackage -ExternalLocation.

Kapan menggunakan ini vs winapp run: Gunakan create-debug-identity saat exe terpisah dari kode aplikasi Anda (misalnya, aplikasi Electron tempat electron.exe berada ), node_modulesatau saat secara khusus menguji perilaku paket jarang. Untuk sebagian besar kerangka kerja di mana exe berada di folder output build Anda, gunakan winapp run sebagai gantinya - ini mendaftarkan paket tata letak longgar penuh dan meluncurkan aplikasi. Lihat Panduan Penelusuran Kesalahan untuk perbandingan lengkap.

winapp create-debug-identity [entrypoint] [options]

Argumen:

entrypoint - Jalur ke executable (.exe) atau skrip yang membutuhkan identitas

Opsi:

--manifest <path> - Jalur ke file manifes aplikasi, baik Package.appxmanifest atau appxmanifest.xml (default: deteksi Package.appxmanifest otomatis atau appxmanifest.xml di direktori saat ini)
--no-install - Jangan instal paket setelah pembuatan
--keep-identity - Simpan identitas manifes as-is, tanpa menambahkan .debug ke nama paket dan ID aplikasi

Apa fungsinya:

Memodifikasi manifes berdampingan yang dapat dieksekusi
Mendaftarkan paket terbatas untuk identifikasi
Mengaktifkan debugging API yang memerlukan identitas

Contoh:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

identitas tersemat

Sambungkan aplikasi desktop ke paket identitas jarangnya dengan menyematkan elemen ke dalam manifes aplikasi berdampingan <msix> (fusion). Ini adalah langkah 3 dari alur kerja kemasan jarang - ini memberi tahu Windows paket identitas mana yang dimiliki exe yang sedang berjalan.

winapp embed-identity <target> [options]

Argumen:

target - File yang akan diperbarui. Terdeteksi secara otomatis oleh ekstensi:
- .exe (Mode EXE) — menyematkan <msix> elemen langsung ke manifes berdampingan exe menggunakan mt.exe.
- .xml / .manifest (Mode XML) — menyisipkan atau mengganti <msix> elemen dalam file manifes SxS eksternal (dibuat jika tidak ada). Bangun ulang aplikasi Anda setelah itu sehingga manifes yang diperbarui disematkan di biner.

Opsi:

--manifest <path> - Jalur ke jarang appxmanifest.xml untuk membaca identitas (packageName, publisher, applicationId) dari. Saat dihilangkan, perintah mencari sparse/ folder di samping target terlebih dahulu, lalu di direktori saat ini, lalu direktori target dan direktori saat ini, untuk appxmanifest.xml.

Contoh:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

Perintah ini idempogen: menjalankannya kembali menggantikan elemen yang ada <msix> daripada menduplikasinya.

Mewujudkan

Membuat dan mengelola file Package.appxmanifest.

pembuatan manifest

Hasilkan Package.appxmanifest dari templat.

winapp manifest generate [directory] [options]

Argumen:

directory - Direktori untuk menghasilkan manifes di (default: direktori saat ini)

Opsi:

--package-name <name> - Nama paket (default: nama folder)
--publisher-name <name>- Publisher nama khusus (default: CN=<pengguna> saat ini). Menerima X.500 DN dengan komponen bernilai tunggal yang dipisahkan koma (RDN dan garis miring terbalik multinilai + tidak didukung); nama kosong dibungkus secara otomatis sebagai CN=<name>.
--version <version> - Versi (default: "1.0.0.0")
--description <text> - Deskripsi (default: "Aplikasi Saya")
--entrypoint <path> - Titik masuk yang dapat dieksekusi atau skrip
--template <type> - Jenis templat: packaged (default) atau sparse
--logo-path <path> - Jalur ke file gambar logo
--if-exists <Error|Overwrite|Skip> - Perilaku ketika file manifes sudah ada di jalur target (default: Error)

Template:

packaged - Manifes aplikasi terbungkus standar
sparse - Manifes aplikasi menggunakan kemasan lokasi sparse/eksternal

Tempat penampung manifes

Manifes yang dihasilkan menggunakan token $placeholder$ (dilingkupi tanda dolar) yang diresolusikan secara otomatis pada waktu pengemasan:

Placeholder	Diselesaikan menjadi	Example
$targetnametoken$	Nama yang dapat dieksekusi tanpa ekstensi	`Executable="$targetnametoken$.exe"` → `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Selalu diselesaikan secara otomatis

Ini mengikuti konvensi yang sama yang digunakan oleh templat proyek Visual Studio, sehingga manifes portabel di seluruh alat.

Bagaimana placeholder diidentifikasi:

winapp pack — Selama pengemasan, $targetnametoken$ diselesaikan menggunakan --executable opsi atau dengan mendeteksi .exe tunggal secara otomatis di folder input. Jika beberapa file (atau nol) .exe ditemukan dan --executable tidak ditentukan, kesalahan akan ditampilkan.
winapp create-debug-identity — Ketika argumen entrypoint disediakan, $targetnametoken$ diselesaikan dari argumen tersebut. Tanpa titik masuk, tempat penampung yang dapat dieksekusi harus sudah diselesaikan dalam manifes.
winapp manifest generate --executable — Ketika --executable disediakan, metadata manifes (versi, deskripsi) dan ikon diekstraksi dari yang dapat dieksekusi, tetapi manifes yang dihasilkan masih menggunakan $targetnametoken$.exe; tempat penampung ini diselesaikan nanti (misalnya winapp pack atau winapp create-debug-identity).

PS: Keeping $targetnametoken$ dalam manifes checked-in Anda menghindari nama yang dapat dieksekusi pengodean keras dan berfungsi dengan build winapp pack dan Visual Studio.

Contoh:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

add-alias manifes

Tambahkan alias eksekusi (uap5:AppExecutionAlias) ke Package.appxmanifest. Ini memungkinkan peluncuran aplikasi yang dipaketkan dari baris perintah dengan mengetikkan nama alias.

winapp manifest add-alias [options]

Opsi:

--name <alias> - Nama alias (misalnya myapp.exe). Default: disimpulkan Executable dari atribut dalam manifes.
--manifest <path> - Jalur ke Package.appxmanifest (default: cari direktori saat ini)
--app-id <id> - Id Aplikasi untuk menambahkan alias ke (default: elemen Aplikasi pertama)

Apa fungsinya:

Membaca manifes dan menyimpulkan alias dari Executable atribut (mempertahankan tempat penampung seperti $targetnametoken$.exe)
uap5 Menambahkan deklarasi namespace jika belum ada
<Extensions> Menambahkan blok dengan <uap5:AppExecutionAlias> di dalam elemen Aplikasi target
Jika alias sudah ada, laporkan dan keluar dengan sukses

Contoh:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

aset pembaruan manifes

Hasilkan semua aset gambar MSIX yang diperlukan dari satu gambar sumber.

winapp manifest update-assets <image-path> [options]

Argumen:

image-path - Jalur ke file gambar sumber (PNG, JPG, SVG, ICO, GIF, BMP, dll.)

Opsi:

--manifest <path> - Jalur ke file Package.appxmanifest (default: cari direktori saat ini)
--light-image <path> - Jalur ke gambar sumber terpisah untuk varian tema terang

Description:

Mengambil satu gambar sumber dan menghasilkan sekumpulan aset gambar MSIX yang komprehensif berdasarkan referensi aset manifes:

Untuk setiap aset yang dirujuk dalam manifes:

5 varian skala — dasar (tanpa akhiran), .scale-125, , .scale-150.scale-200,.scale-400

Untuk ikon aplikasi (Square44x44Logo / AppList, 44×44 base):

14 varian targetsize berlapis — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
14 varian targetsize yang tidak diplika — .targetsize-{size}_altform-unplated

Additionally:

app.ico — File ICO multi-resolusi (16, 24, 32, 48, 256) untuk integrasi shell. Jika file yang ada .ico ditemukan di direktori aset (misalnya AppIcon.ico dari templat proyek), file tersebut diganti di tempat daripada membuat duplikat

Dengan --light-image:

Tema ringan menargetkan varian — .targetsize-{size}_altform-lightunplated (ikon aplikasi)
Varian skala tema ringan — .scale-{factor}_altform-colorful_theme-light (petak peta, logo toko)

Dukungan SVG: File SVG didukung penuh sebagai gambar sumber. Mereka dirender sebagai vektor langsung di setiap ukuran target, menghasilkan hasil sempurna piksel di semua resolusi. File harus mendeklarasikan ukurannya sendiri, melalui viewBox atau absolut width dan height atribut; lebar persentase tanpa viewBox menggambarkan ukuran tertentu. Sumber yang menyatakan tidak ditolak dengan SVG image has no usable dimensions alih-alih menghasilkan aset kosong.

Perintah menskalakan gambar secara proporsional sambil mempertahankan rasio aspek, mempusatkannya dengan latar belakang transparan saat diperlukan. Aset disimpan ke Assets direktori berdasarkan lokasi manifes.

Contoh:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

eksekusi

Buat paket tata letak longgar dari folder output build, daftarkan dengan Windows menggunakan API Windows.Management.Deployment.PackageManager, dan luncurkan aplikasi — mensimulasikan penginstalan MSIX lengkap untuk penelusuran kesalahan. Mengembalikan ID proses untuk lampiran debugger.

winapp run beroperasi dalam salah satu dari tiga mode, dipilih secara otomatis dari input:

Mode folder — input adalah folder build-output (berisi Package.appxmanifest/AppxManifest.xml).
Project mode — input adalah .csproj, .sln/.slnx solusi, atau direktori yang berisinya. winapp run membangun proyek dan meluncurkannya, mendukung aplikasi WinUI yang dikemas dan tidak dikemas . Lihat mode Project di bawah ini.
Mode file tunggal — input adalah .csaplikasi berbasis file .NET. winapp run membangunnya, menghasilkan manifes dari arahannya #:property , dan meluncurkannya dengan identitas paket.

Tip

Pemilihan mode diam secara default. Jika direktori diperlakukan sebagai folder build-output ketika Anda mengharapkannya dibangun sebagai proyek, jalankan kembali dengan --verbose — mode folder melaporkan mengapa folder dipilih (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Direktori hanya dibangun sebagai proyek ketika .csproj/.slnx/.slndengan aplikasi yang dapat dijalankan berada di tingkat atasnya; tidak dicari secara rekursif.

This adalah perintah pilihan untuk penelusuran kesalahan dengan identitas paket untuk sebagian besar kerangka kerja (.NET, C++, Rust, Flutter, Tauri). Tidak seperti create-debug-identity yang mendaftarkan paket jarang untuk satu exe, winapp run mendaftarkan seluruh folder sebagai paket tata letak longgar, sama seperti penginstalan MSIX nyata. Lihat Panduan Penelusuran Kesalahan untuk alur kerja penelusuran kesalahan umum.

winapp run [<input>] [options]

Argumen:

input- Aplikasi yang akan dijalankan: folder build-output (mode folder), .cs aplikasi berbasis file .NET (mode file tunggal), .csproj proyek, .sln/.slnx solusi, atau direktori yang berisi salah satu di tingkat atasnya (mode proyek; direktori tidak dicari secara rekursif). Gunakan . untuk membangun/menjalankan proyek di direktori saat ini. Opsional — default ke direktori saat ini saat dihilangkan (cocok dotnet run).

Opsi:

--manifest <path> - Jalur ke Package.appxmanifest (default: deteksi otomatis dari folder input atau direktori saat ini)
--output-appx-directory <path> - Direktori output untuk tata letak longgar (default: AppX di dalam folder input). Tata letak default menghapus file yang tidak lagi ada di build; direktori kustom menyimpan file tambahan. Gunakan direktori kustom baru saat Anda memerlukan tata letak yang bersih.
--args <string> - Argumen baris perintah untuk diteruskan ke aplikasi. Atau, gunakan -- diikuti oleh argumen untuk menghindari pelepasan (misalnya, winapp run . -- --flag value).
--no-launch - Hanya buat identitas debug dan daftarkan paket tanpa meluncurkan aplikasi
--with-alias - Luncurkan aplikasi menggunakan alias eksekusinya alih-alih aktivasi AUMID. Aplikasi berjalan di terminal saat ini dengan stdin/stdout/stderr yang diwariskan. Jarang diperlukan: aplikasi dengan OutputType=Exe sudah meluncurkan cara ini secara default. winapp menambahkan yang diperlukan uap5:ExecutionAlias ke manifes yang ditahapkannya dalam tata letak AppX, jadi tidak ada perubahan pada manifes check-in Anda yang diperlukan; alias yang dinyatakan aplikasi itu sendiri digunakan as-is. Tidak dapat dikombinasikan dengan --no-launch, --detach, --without-alias, atau --json.
--without-alias - Memaksa aktivasi AUMID untuk aplikasi yang jika tidak akan diluncurkan melalui alias eksekusi. Aplikasi konsol kemudian berjalan tanpa konsol dan tidak mencetak apa pun ke terminal ini. Tidak dapat digabungkan dengan --with-alias.
--debug-output - Menangkap OutputDebugString pesan dan pengecualian kesempatan pertama dari aplikasi yang diluncurkan. Kebisingan kerangka kerja (WinUI, COM, DirectX) difilter dari output konsol; file log lengkap menangkap semuanya. Jika aplikasi mengalami crash, secara otomatis mengambil minidump dan menganalisisnya untuk menampilkan jenis pengecualian, pesan, dan pelacakan tumpukan dengan file sumber:nomor baris (diselesaikan dari PDB di folder output build). Crash terkelola (.NET) dianalisis secara instan tanpa alat eksternal. Crash asli (C++/WinRT) menunjukkan nama modul dan offset. Ketika aplikasi yang mengalami crash adalah aplikasi WinUI 3 (Microsoft.UI.Xaml.dll dimuat), pass triase pengecualian ekstra dicuri berjalan secara otomatis untuk memunculkan HRESULT asal, rantai ErrorContext-nya, dan tumpukan pengiriman XAML asli penuh; komponen debugger yang diperlukan diunduh pada penggunaan pertama (lihat Debugging, dapat diambil alih melalui WINAPP_DBGTOOLS_DIR variabel lingkungan). Hanya satu debugger yang dapat dilampirkan ke proses pada satu waktu, sehingga debugger lain (Visual Studio, VS Code) tidak dapat digunakan secara bersamaan. Gunakan --no-launch sebagai gantinya jika Anda perlu melampirkan debugger yang berbeda. Tidak dapat digabungkan dengan --no-launch. Tidak dapat digabungkan dengan --json.
--symbols - Unduh simbol PDB dari Microsoft Symbol Server untuk analisis crash asli yang lebih kaya dengan nama fungsi yang diselesaikan. Hanya digunakan dengan --debug-output. Jika dihilangkan dan crash asli terjadi, output akan menyarankan untuk menambahkan bendera ini. Bendera ini juga meningkatkan tumpukan triase pengecualian WinUI yang disematkan untuk aplikasi WinUI 3. Pertama-tama jalankan simbol unduhan dan cache secara lokal; Eksekusi berikutnya menggunakan cache.
--unregister-on-exit - Batalkan pendaftaran paket pengembangan setelah aplikasi keluar. Hanya menghapus paket yang terdaftar dalam mode pengembangan. Tidak dapat digabungkan dengan --no-launch.
--detach - Luncurkan aplikasi dan segera kembali tanpa menunggunya keluar. Berguna untuk CI/automation di mana Anda perlu berinteraksi dengan aplikasi setelah peluncuran. Eksekusi lokal mencetak PID; target menjalankan pencetakan target UI terlingkup. JSON mencakup PID dan cakupan target. Tidak dapat dikombinasikan dengan --no-launch, --debug-output, --with-alias, atau --unregister-on-exit.
--clean - Hapus data aplikasi paket yang ada (LocalState, pengaturan, dll.) sebelum menyebarkan ulang. Secara default, data aplikasi dipertahankan di seluruh penyebaran ulang.
--json - Format output sebagai JSON untuk konsumsi terprogram (misalnya CI/automation). Berguna dengan --detach untuk menangkap PID. Tidak dapat digabungkan dengan --with-alias atau --debug-output.
--on <target> - Bangun di host, lalu daftarkan dan jalankan di target. Saat ini mendukung sandbox, tanpa fallback ke eksekusi lokal. Gunakan --detach sebelum perintah UI tindak lanjut. Sandbox --debug-output memerlukan aplikasi yang dipaketkan. Lihat Windows eksekusi Sandbox untuk penyiapan, dukungan runtime, dan masa pakai aplikasi yang dilepas.

Persistensi data aplikasi:

Secara default, winapp run pertahankan data aplikasi Anda (LocalState, , RoamingState, Settingsdll.) saat menyebarkan ulang. Jika aplikasi Anda menulis data ke ApplicationData.Current.LocalFolder atau Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dalam konteks paket, data tersebut akan bertahan di seluruh winapp run pemanggilan.

Gunakan --clean saat Anda memerlukan awal baru (misalnya, untuk mengatur ulang status rusak atau menguji perilaku eksekusi pertama).

Apa fungsinya:

Menemukan atau menghasilkan Package.appxmanifest
Membuat dan mendaftarkan identitas debug menggunakan paket tata letak longgar
Menghitung ID Model Pengguna Aplikasi (AUMID)
Meluncurkan aplikasi menggunakan identitas terdaftar (kecuali --no-launch ditentukan)
Mencetak ID proses (PID) untuk lampiran debugger

Contoh:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

mode Project (proyek SDK .NET)

Ketika input adalah .csproj,.slnx/.sln solusi, atau direktori yang berisi satu (termasuk .),winapp run membangun proyek dengan dotnet build dan kemudian meluncurkannya. Ini mendukung aplikasi WinUI yang dikemas dan tidak dikemas, dan menginstal arsitektur yang cocok Windows App Runtime yang dibutuhkan aplikasi sebelum diluncurkan.

Input solusi: arahkan winapp run ke (atau direktori yang berisinya — solusi lebih disukai/.slnx.slndaripada file yang longgar.csproj) dan menyelesaikan proyek aplikasi yang dapat dijalankan, lalu membangunnya dengan $(SolutionDir) dan properti saudara Solution* yang ditentukan, sehingga proyek yang bergantung pada mereka dibangun seperti yang mereka lakukan di Visual Studio. Aturan resolusi:

Proyek pengujian dilewati saat memilih secara otomatis, sehingga solusi yang berisi aplikasi ditambah pengujiannya diselesaikan ke aplikasi tanpa --project perlu. (Proyek pengujian WinUI adalah aplikasi yang dipaketkan sendiri, jadi jenis output saja tidak dapat membedakannya.)
Jika satu-satunya proyek yang dapat dijalankan adalah proyek pengujian, proyek tersebut akan berjalan.
Jika ada lebih dari satu proyek aplikasi yang dapat dijalankan, winapp run tidak menebak proyek startup — kesalahannya mencantumkan kandidat. Gunakan --project <name> untuk memilih, yang selalu dihormati, termasuk untuk memilih proyek pengujian.

Dikemas vs. unpackaged terdeteksi secara otomatis dari properti MSBuild efektif WindowsPackageType proyek (tidak pernah dari kehadiran manifes):

Dipaketkan (WindowsPackageType=MSIX, default paket WinUI) — membangun, lalu mendaftarkan output build sebagai paket tata letak longgar dan diluncurkan melalui AUMID (alur yang sama dengan mode folder).
Unpackaged (WindowsPackageType=None) — membangun, memastikan Windows App Runtime yang bergantung pada kerangka kerja diinstal, lalu meluncurkan build .exe secara langsung. Paksa ini untuk proyek yang dipaketkan dengan -p WindowsPackageType=None.

mode Project memerlukan .NET SDK 8.0.100 atau yang lebih baru (untuk MSBuild --getProperty).

AOT asli: tambahkan grup properti ini di dalam elemen file <Project> project, lalu tambahkan --aot:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aotmendukung proyek x64 dan ARM64 dan memerlukan .NET SDK 8.0.300 atau yang lebih baru. Ini berjalan dotnet publish dengan konfigurasi AOT proyek, lalu meluncurkan output tersebut; gunakan -p PublishAot=true untuk penimpaan satu kali. Ini tidak melakukan sertifikasi runtime terpisah dan tidak dapat dikombinasikan dengan --no-build atau --manifest.

Untuk aplikasi yang menggunakan identitas paket tanpa tata letak MSIX yang dihasilkan, sertakan Package.appxmanifest atau appxmanifest.xml dalam output penerbitan proyek. Winapp menahapkan file yang diterbitkan dengan manifes tersebut. Jika kedua nama ada, winapp berhenti alih-alih memilih salah satunya; hapus manifes kedaluwarsa dan konfigurasikan proyek untuk menerbitkan manifes yang dimaksudkan saja.

opsi mode Project (diabaikan dalam mode folder kecuali dinyatakan):

-c, --configuration <name> - Bangun konfigurasi. Standar: Debug. (Juga dihormati dalam mode file tunggal.)
--arch <x64|arm64|x86> - Arsitektur target. Default: arsitektur proses saat ini. Menentukan arsitektur build RID dan Windows App Runtime, dan memilih profil publikasi yang bergantung pada platform yang cocok jika diperlukan oleh build yang efektif. (Juga dihormati dalam mode file tunggal.)
-r, --runtime <rid>- Pengidentifikasi runtime .NET target (misalnya win-x64). Project mode hanya menggunakan arsitektur RID, selalu membangun kanonis win-<arch>, dan menolak RID non-Windows (misalnya linux-x64). Arsitekturnya mengambil alih --arch dan dapat memilih profil penerbitan yang diperlukan. (Juga dihormati dalam mode file tunggal, di mana ia mengambil alih yang #:property RuntimeIdentifier dideklarasikan oleh file.)
-f, --framework <tfm> - Moniker kerangka kerja target untuk proyek multi-target (misalnya net10.0-windows10.0.26100.0). (Ditolak dalam mode file tunggal — gunakan #:property TargetFramework=....)
--project <name-or-path> - Ketika input adalah solusi (.sln/.slnx) atau direktori dengan beberapa proyek aplikasi yang dapat dijalankan, memilih proyek mana yang akan diluncurkan (berdasarkan nama atau jalur proyek). (Ditolak dalam mode file tunggal — .cs aplikasi berbasis file itu sendiri adalah proyek.)
--no-build - Lewati pembangunan dan jalankan output build yang ada (masih mengevaluasi properti output). (Juga dihormati dalam mode file tunggal.)
--no-restore - Lewati pemulihan sebelum membangun atau penerbitan AOT Asli. (Juga dihormati dalam mode file tunggal.)
--aot- Jalankan proyek yang dikonfigurasi .NET Penerbitan AOT Asli. Membutuhkan efektif PublishAot=true. Ditolak dalam mode folder dan file tunggal.
-p, --property <Name=Value> - Properti MSBuild, diteruskan ke build dan evaluasi properti. Ulangi -p untuk beberapa properti; gunakan %3B atau %2C untuk titik koma atau koma harfiah dalam sebuah nilai. (Juga dihormati dalam mode file tunggal, di mana itu adalah satu-satunya cara untuk mengatur TargetFramework.)

Membangun output &verbositas: eksekusi proyek biasa menggunakan dotnet build, lalu mengevaluasi output bawaan. Pulihkan dan bangun aliran output secara langsung, dengan kredensial dari URL umpan terautentikasi yang diredaksi. Dengan --aot, winapp menggunakan dotnet publish; --verbose menunjukkan perintah terbitkan dan jalur yang diselesaikan. Gunakan opsi verbositas di bawah ini untuk mengontrol apa yang ditampilkan:

Tanda	verbositas dotnet	Menambahkan
(default)	`minimal`	—
`--verbose`	`minimal`	jejak keputusan build winapp
`--quiet`	`quiet`	—

AOT asli menerbitkan aliran output saat tiba. Di bawah --json, pulihkan/bangun pemanggilan dan output anak masuk ke stderr sehingga stdout tetap murni JSON. Di bawah --quiet, pemanggilan ditekan dan output pemulihan/build dotnet yang tenang dirutekan ke stderr sehingga stdout tetap bersih. Output penerbitan AOT asli juga masuk ke stderr di bawah salah satu opsi.

Penerapan opsi: opsi identitas/tata letak longgar (--manifest, , --output-appx-directory, --no-launch, --with-alias--unregister-on-exit, --clean, ) --executablehanya berlaku untuk aplikasi paket. Mereka ditolak dengan kesalahan yang jelas untuk aplikasi yang tidak dikemas (yang tidak memiliki paket MSIX). Opsi peluncuran/debug (--args/--, --detach, , --debug-output--symbols, ) --jsonberfungsi di keduanya.

contoh mode Project:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

Mode file tunggal (.NET aplikasi berbasis file)

.NET 10 memungkinkan Anda menjalankan satu .cs file tanpa file proyek, mengonfigurasinya dengan #: direktif di bagian atas. Arahkan winapp run pada file tersebut dan membuat aplikasi, menghasilkan appxmanifest untuk itu, dan meluncurkannya dengan identitas paket — jadi Windows.ApplicationModel.Package.Current berfungsi, aplikasi mendapatkan AUMID nyata dan entri menu Mulai, dan API yang hanya memerlukan pekerjaan identitas (pemberitahuan aplikasi, ApplicationData, AI di perangkat).

Integrasi shell seperti penangan protokol, asosiasi file, target berbagi, dan tugas startup memerlukan entri yang dinyatakan <Extensions> , yang tidak berisi manifes yang dihasilkan. Untuk menambahkannya, tulis manifes Anda sendiri — lihat Membawa manifes Anda sendiri di bawah ini.

winapp run counter.cs

Atau jalankan dengan biasa dotnet run — lihat Menjalankan dengan dotnet run di bawah ini.

Anda tidak menulis manifes. Jelaskan paket dengan #:property arahan sebagai gantinya:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Properti manifes. Semua bersifat opsional; masing-masing kembali ke default yang masuk akal:

Harta benda	Kumpulan	Default
`WinAppPackageName`	`Identity/@Name` (identitas paket)	nama file, dibersihkan ke `[-.A-Za-z0-9]`, ditambah hash singkat dari jalur file (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	Nama yang diperlihatkan di Mulai dan Pengaturan	nama file tanpa ekstensinya
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Nama kosong dibungkus sebagai `CN=<name>`.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, dinormalisasi (lihat di bawah)
`WinAppDescription`	Deskripsi yang ditampilkan selama penginstalan dan di Pengaturan	nama tampilan
`WinAppCapabilities`	Kemampuan untuk mendeklarasikan, dipisahkan oleh `;` atau `,`	tidak ada

Version. Versi paket harus tepat empat angka, masing-masing 0–65535. WinAppVersion (atau, jika Anda tidak mengaturnya, properti standar Version ) dinormalisasi agar pas: apa pun -preview/-rc akhiran dihilangkan dan komponen yang hilang diisi dengan nol, jadi #:property Version=1.2.3-preview.4 menjadi 1.2.3.0 dan mengatur versi rakitan dan versi paket Anda bersama-sama. Nilai yang tidak dapat disesuaikan — komponen di atas 65535, atau lebih dari empat komponen — ditolak dengan kesalahan daripada diubah secara diam-diam.

Capabilities

Aplikasi Anda menjalankan kepercayaan penuh dengan identitas, yang memenuhi API yang hanya memerlukan aplikasi paket. Tetapi beberapa API terjaga pada kemampuan yang dinyatakan terlepas dari — API AI Windows adalah kasus umum. (Integrasi Shell seperti penangan protokol dan asosiasi file adalah kasus ketiga: yang membutuhkan entri yang ditulis <Extensions> , bukan kemampuan, jadi gunakan manifes Anda sendiri untuk mereka.)

#:property WinAppCapabilities=systemAIModels

Itu saja Phi Silica dan API model perangkat lainnya yang dibutuhkan dari manifes. Deklarasikan beberapa dengan memisahkannya:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp menulis masing-masing ke dalam elemen dan namespace XML yang sebenarnya diperlukan, mendeklarasikan namespace layanan tersebut, dan menaikkan MaxVersionTested ketika kemampuan membutuhkan yang lebih baru. Ini lebih penting daripada kedengarannya: kemampuan tersebar di beberapa elemen yang berbeda, dan daftar yang sama di atas menjadi tiga bentuk yang berbeda -

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Nama winapp tahu ditulis untuk Anda. Untuk hal lain — set terbatas tumbuh dari waktu ke waktu - kualifikasikan sendiri dengan awalan namespace:

Awalan	Memancarkan
`rescap:`	`<rescap:Capability>` — kemampuan terbatas
`uap:`,`uap6:`,`uap7:`,`uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` di namespace default

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Nama kosong yang tidak dikenal ditolak dengan kesalahan penamaan awalan ini, daripada ditebak — kemampuan yang dipancarkan di namespace yang salah menghasilkan manifes Windows menolak untuk mendaftar atau menerima saat diam-diam tidak memberikannya.

Bawa manifes Anda sendiri

Jika Anda memerlukan sesuatu yang tidak dicakup properti — handler protokol, asosiasi file, alias eksekusi — tulis manifes dan winapp run akan menggunakannya secara verbatim alih-alih menghasilkannya. Ini diambil dari, secara berurutan:

--manifest <path> pada baris perintah.
#:property WinAppManifestPath=<path> .cs dalam file.
Manifes yang berada di .cs samping file, bernama <filename>.appxmanifest (misalnya counter.appxmanifest di samping counter.cs).

Hanya nama per file yang diambil secara otomatis. Package.appxmanifest Atau appxmanifest.xml di folder yang sama sengaja diabaikan — beberapa .cs file dapat berbagi folder, dan mengadopsi nama bersama akan secara diam-diam menjalankan satu aplikasi di bawah identitas orang lain. Untuk menggunakan satu manifes untuk beberapa file, beri nama secara eksplisit dengan --manifest atau WinAppManifestPath.

Jika tidak, Package.appxmanifest dihasilkan ke dalam output build, bersama dengan aset gambar default, dan di-refresh pada setiap eksekusi.

Options. Setiap opsi mode folder berfungsi: --no-launch, , --with-alias, --without-alias, --detach--clean, --debug-output--symbols, , --unregister-on-exit,/----args , --json--executable, --manifest, , --output-appx-directoryplus -c/--configuration, , --no-build, --no-restore, dan .-p/--property

Tip

Aplikasi konsol mencetak ke terminal Anda secara default. Aplikasi paket yang diluncurkan melalui AUMID tidak memiliki konsol, sehingga aplikasi khusus konsol akan berjalan dengan benar dan tidak mencetak apa pun. winapp menghindari hal tersebut: aplikasi dengan OutputType=Exe diluncurkan melalui alias eksekusi sebagai gantinya, yang mewarisi stdin/stdout/stderr terminal ini. Anda masih mendapatkan identitas paket, dan Anda tidak perlu memintanya:

winapp run counter.cs

Teruskan --without-alias untuk memaksa aktivasi AUMID sebagai gantinya - aplikasi kemudian berjalan tanpa konsol dan tidak mencetak apa pun di sini. Aplikasi berjendela (WinExe) menunjukkan jendela, sehingga tetap aktivasi AUMID; teruskan --with-alias jika Anda tetap menginginkannya di terminal ini. Untuk memperbaiki pilihan dalam file daripada pada setiap baris perintah, atur properti yang sama dengan penggunaan .csproj :

#:property WinAppRunUseExecutionAlias=false

Winapp alias menyatakan dinamai sesuai dengan nama keluarga paket, dengan winapp- awalan - jadi com.contoso.counter diterbitkan oleh CN=You mendapatkan winapp-com.contoso.counter_gspb8g6x97k2t.exe. Bagian berikutnya adalah hash penerbit Windows turunan, sehingga dua aplikasi yang berbagi nama di bawah penerbit yang berbeda masih mendapatkan alias yang berbeda. Awalan menjaga nama tetap bersih dari perintah nyata: aplikasi di python.cs mendapatkan winapp-… alias, tidak pernah python.exe. Jika Anda menulis manifes Anda sendiri, alias yang Anda nyatakan ada digunakan as-is dan winapp tidak menambahkan apa pun.

Itu hanya berlaku untuk alias. Pendaftaran itu sendiri dikunci pada nama paket, jadi menjalankan aplikasi kedua yang menyatakan hal yang sama WinAppPackageName di bawah penerbit yang berbeda menggantikan pendaftaran pertama daripada duduk bersamanya. Beri nama masing-masing aplikasi sendiri jika Anda ingin keduanya terdaftar sekaligus.

winapp run mencetak alias yang terdaftar, jadi Anda tidak perlu menghitung hash untuk menemukannya.

Alias adalah perintah pada PATH Anda yang berlangsung selama paket tetap terdaftar. Jika beberapa paket lain sudah memiliki nama, winapp mengatakan demikian. Ketika menyimpulkan alias untuk Anda, itu diluncurkan melalui AUMID sebagai gantinya, daripada memulai aplikasi yang salah; ketika Anda memintanya secara eksplisit — dengan --with-alias atau #:property WinAppRunUseExecutionAlias=true — itu gagal alih-alih melakukan sesuatu yang lain secara diam-diam.

Dua opsi mode proyek tidak berlaku, karena aplikasi berbasis file mengonfigurasi dirinya sendiri. Mereka ditolak dengan pesan yang memberi nama direktif untuk digunakan sebagai gantinya:

Option	Gunakan sebagai gantinya
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	tidak ada — `.cs` file adalah proyek

--arch dan -r/--runtime bekerja seperti yang mereka lakukan dalam mode proyek. Ketika Anda tidak lulus baik, winapp membangun untuk arsitektur komputer Anda - yang merupakan apa yang dibutuhkan aplikasi SDK Aplikasi Windows mandiri, karena tanpa itu SDK membangun AnyCPU dan gagal dengan WindowsAppSDKSelfContained requires a supported Windows architecture. #:property RuntimeIdentifier=win-arm64 Dalam file dihormati; eksplisit --arch/--runtime mengambil alihnya.

Kedua pekerjaan yang dikemas dan tidak dikemas, terdeteksi dari efektif WindowsPackageType persis seperti dalam mode proyek: default mendaftarkan tata letak longgar dan meluncurkannya dengan identitas, saat #:property WindowsPackageType=None membangun aplikasi, menginstal Windows App Runtime yang cocok, dan meluncurkan .exe secara langsung. (Aplikasi paket diluncurkan melalui alias eksekusinya atau melalui aktivasi AUMID — lihat catatan konsol di atas; pilihan tersebut terpisah dari apakah dikemas.) Opsi identitas (--no-launch, , --with-alias, --without-alias--clean, --unregister-on-exit, --manifest, --output-appx-directory) hanya berlaku untuk aplikasi paket.

Berjalan dengan `dotnet run`

Anda tidak perlu mengetik winapp . Referensi paket Microsoft.Windows.SDK.BuildTools.WinApp dari file dan biasa dotnet run memberi Anda peluncuran paket yang sama:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

MSBuild paket menargetkan mengalihkan eksekusi ke winapp, paket mana, mendaftar, dan meluncurkan aplikasi yang dotnet run baru saja dibuat — tidak dibangun kembali. Penanganan manifes tidak berubah: winapp menyelesaikannya persis seperti yang dilakukan untuk winapp run, jadi #:property WinAppManifestPath=… dan <filename>.appxmanifest di samping .cs keduanya terhormat (lihat Bawa manifes Anda sendiri), seluruh Package.appxmanifest direktori masih diabaikan, dan jika tidak, satu dihasilkan dari arahan Anda #:property dan disegarkan setiap eksekusi.

Dua kondisi harus menahan pengalihan terjadi:

Direktif	Mengapa
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	target yang melakukan pengiriman pengalihan dalam paket ini
`#:property TargetFramework=net10.0-windows…`	file biasa `net10.0` dibiarkan saja, sehingga berjalan tanpa kemasan

#:property WindowsPackageType=None Menambahkan juga meninggalkan file saja: dotnet run kemudian menjalankan .exe secara langsung, tanpa identitas. Gunakan winapp run untuk jalur yang tidak dikemas jika Anda ingin pencocokan Windows App Runtime diinstal terlebih dahulu.

Atur #:property EnableWinAppRunSupport=false untuk menolak pengalihan sepenuhnya, dan properti yang WinAppRun* dijelaskan di bawah Konfigurasi untuk membentuk peluncuran — misalnya:

#:property WinAppRunUnregisterOnExit=true

Jika dotnet run menjalankan aplikasi yang tidak dikemas saat Anda mengharapkan identitas, tanyakan alasannya kepada MSBuild. Gunakan dotnet build, tidak dotnet msbuild - hanya dotnet build mensintesis proyek virtual yang dikompilasi oleh aplikasi berbasis file:

dotnet build counter.cs -t:WinAppRunSupportInfo

Mode file tunggal memerlukan .NET SDK 10.0.300 atau yang lebih baru.

Pendaftaran keluar dari eksekusi. winapp run counter.cs meninggalkan paket yang terdaftar setelah aplikasi keluar, persis seperti folder dan mode proyek — jadi LocalState bertahan, dan menjalankan kembali file yang sama menggunakan kembali identitas yang sama daripada menumpuk pendaftaran. winapp mengatakan demikian pertama kali mendaftarkan aplikasi, dan winapp unregister mengambil sendiri .cs :

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs tidak memerlukan jalur manifes: ini mengevaluasi nilai file #:property dengan cara run yang sama, dan hanya menghapus paket yang terdaftar dari output build file tersebut. Aplikasi bernama sama yang terdaftar dari folder lain ditolak kecuali Anda lulus --force. Jika eksekusi menggunakan opsi yang membentuk identitas atau tata letak, teruskan yang sama ke unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p mengambil alih arahan file sendiri, dan Directory.Build.props di samping .cs kunci WinAppPackageName kaleng atau $(Configuration)$(RuntimeIdentifier) — sehingga masing-masing dapat mengubah paket mana yang akan didaftarkan.

Setelah output sementara SDK dibersihkan, winapp unregister counter.cs tidak dapat lagi mengonfirmasi pendaftaran berasal dari file tersebut dan akan melewatinya - gunakan winapp unregister --prune untuk menghapus pendaftaran yang filenya hilang, atau --force untuk menghapus file tertentu. Jika eksekusi digunakan --output-appx-directory, teruskan direktori yang sama sehingga unregister dapat mengenali tata letak.

Hal yang sama berlaku untuk jalur output kustom: kepemilikan dikonfirmasi dari tata letak standar <root>\bin\<configuration> SDK, sehingga eksekusi yang dibangun dengan tidak dapat dicocokkan dengan -p OutputPath=<somewhere-else> file sumbernya. unregister lewati daripada menebak direktori yang lebih luas — beri nama tata letak dengan --output-appx-directory, atau gunakan --force.

Contoh file tunggal:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Nota

Identitas default mencakup hash singkat dari jalur file — counter.cs menjadi sesuatu seperti counter-a1b2c3d4 — sehingga dua counter.cs file di folder yang berbeda adalah aplikasi yang berbeda dan menyimpan pengaturannya sendiri dan LocalState. Hash berasal dari jalur , sehingga bertahan dari pengeditan dan menjalankan kembali dan hanya berubah jika Anda memindahkan file. Atur #:property WinAppPackageName=<name> untuk memilih identitas stabil sendiri; dinormalisasi ke apa yang Identity/@Name memungkinkan — karakter di luar [-.A-Za-z0-9] dijatuhkan, nama yang lebih pendek dari 3 karakter diisi dengan 1, dan hasilnya dibatasi pada 50 karakter, jadi My App daftarkan sebagai MyApp. Bagaimanapun menu Mulai dan Pengaturan menampilkan Anda WinAppDisplayName (default: nama file), bukan identitas. Identitas selalu dilingkupkan ke akun pengguna Anda, sehingga tidak pernah bertabrakan dengan pengguna lain di komputer yang sama.

Properti MSBuild (paket NuGet):

Saat menggunakan paket NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run secara otomatis memanggil winapp run.

Semua yang ditulis setelah dotnet run diteruskan ke aplikasi Anda, persis seperti tanpa paket. Konfigurasikan peluncur dengan properti MSBuild di bawah ini:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

Properti MSBuild berikut ini dapat diatur dalam perilaku kontrol Anda .csproj :

Harta benda	Default	Deskripsi
`EnableWinAppRunSupport`	`true`	Mengaktifkan/menonaktifkan fungsionalitas dukungan eksekusi
`WinAppLaunchArgs`	(kosong)	Argumen untuk diteruskan ke aplikasi saat diluncurkan
`WinAppRunUseExecutionAlias`	disimpulkan dari aplikasi	Luncurkan melalui alias eksekusi alih-alih aktivasi AUMID. Unset kiri, winapp menyimpulkannya: aplikasi konsol menggunakan alias sehingga outputnya mencapai terminal, aplikasi berjendela menggunakan AUMID. Atur `true` atau `false` putuskan sendiri.
`WinAppRunNoLaunch`	`false`	Hanya daftarkan identitas tanpa meluncurkan
`WinAppRunDebugOutput`	`false`	Menangkap `OutputDebugString` pesan dan pengecualian kesempatan pertama. Hanya satu debugger yang dapat melampirkan pada satu waktu (mencegah VS/VS Code). Gunakan `WinAppRunNoLaunch` sebagai gantinya untuk melampirkan debugger yang berbeda.
`WinAppRunDetach`	`false`	Kembali segera setelah diluncurkan alih-alih menunggu aplikasi keluar. Mencetak PID.
`WinAppRunUnregisterOnExit`	`false`	Membatalkan pendaftaran paket pengembangan setelah aplikasi keluar
`WinAppRunClean`	`false`	Hapus data aplikasi paket yang ada (LocalState, pengaturan) sebelum menyebarkan ulang
`WinAppRunSymbols`	`false`	Unduh simbol dari Microsoft Symbol Server untuk analisis crash asli yang lebih kaya. Hanya memiliki efek dengan `WinAppRunDebugOutput`.
`WinAppRunExecutable`	(kosong)	Jalur yang dapat dieksekusi relatif terhadap folder build-output. Gunakan saat manifes berisi $targetnametoken$ dan folder output memiliki lebih dari satu `.exe`.
`WinAppRunArgs`	(kosong)	Argumen mentah ditambahkan ke `winapp run` baris perintah, untuk opsi tanpa properti khusus (misalnya `--verbose`). Ditambahkan setelah setiap properti di atas.

Pengaturan yang saling eksklusif. WinAppRunNoLaunch dan WinAppRunDetach masing-masing menggambarkan perilaku peluncuran yang berbeda, sehingga berkonflik dengan properti peluncuran lainnya dan satu sama lain. Pengaturan pasangan yang bertentangan gagal dijalankan dengan --X and --Y cannot be used together:

Harta benda	Tidak dapat digabungkan dengan
`WinAppRunNoLaunch`	`WinAppRunDetach`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias sengaja tidak ada dalam daftar itu, di kedua arah. false meminta aktivasi AUMID, yang sudah tidak digunakan dan dilepas; true hanya tidak diterapkan ketika keduanya diatur, karena alias eksekusi membutuhkan proses yang dilacak dan berjalan. Jadi proyek yang memeriksa <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> masih berjalan dengan bersih di bawah dotnet run -p:WinAppRunDetach=true, meluncurkan melalui AUMID daripada gagal.

WinAppRunUseExecutionAlias, , WinAppRunDebugOutputdan WinAppRunUnregisterOnExit dapat dikombinasikan satu sama lain. WinAppRunClean, , WinAppRunSymbolsWinAppRunExecutable, dan WinAppLaunchArgs tidak memiliki batasan. WinAppRunArgs menambahkan tidak ada batasan sendiri, tetapi sakelar yang diteruskan melaluinya diperiksa seperti yang lain, jadi WinAppRunArgs="--detach" masih bertentangan dengan WinAppRunNoLaunch.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

batalkan pendaftaran

Batalkan pendaftaran paket pengembangan yang dimuat samping. Hanya menghapus paket yang terdaftar dalam mode pengembangan (misalnya, melalui winapp run atau create-debug-identity). Paket yang diinstal penyimpanan atau MSIX tidak pernah dihapus.

winapp unregister [input] [options]

Argumen:

input- Jalur ke aplikasi berbasis file .NET (satu .cs) yang paketnya harus tidak terdaftar. Identitasnya diselesaikan dengan cara winapp run yang sama menyelesaikannya — dari manifes yang ditulis jika aplikasi memilikinya, jika tidak dari nilainya #:property — sehingga tidak ada jalur manifes yang diperlukan. Hilangkan untuk menggunakan --manifest atau mendeteksi manifes secara otomatis di direktori saat ini. Tidak dapat dikombinasikan dengan , yang menamai paket dengan --manifestcara yang berbeda dan dapat diselesaikan ke yang berbeda.

Opsi:

--manifest <path> - Jalur ke Package.appxmanifest (default: deteksi otomatis dari direktori saat ini)
--force - Hanya untuk membatalkan pendaftaran lokal, lewati pemeriksaan direktori lokasi penginstalan dan batalkan pendaftaran meskipun paket terdaftar dari pohon proyek yang berbeda. Ini ditolak dengan --on; pemeriksaan kepemilikan target tidak dapat dilewati.
--on <target> - Hapus pendaftaran pengembangan milik winapp yang cocok dari sandbox, bukan mesin ini. Memerlukan manifes dan tidak mendukung --force. Lihat Pembersihan aplikasi sandbox.
--prune - Hapus setiap pendaftaran mode pengembangan yang filenya hilang. Tidak dapat dikombinasikan dengan input, --manifest, , --property--configuration, --arch, --runtime, atau --output-appx-directory.
-p, --property <Name=Value> - Properti MSBuild yang digunakan saat menyelesaikan .cs identitas aplikasi berbasis file. Berulang. Teruskan properti yang memengaruhi identitas yang sama dengan eksekusi yang digunakan (misalnya -p WinAppPackageName=...), karena properti baris perintah mengambil alih arahan file itu sendiri #:property . Hanya berlaku untuk .cs input.
-c, --configuration <name> - Konfigurasi build yang digunakan saat menyelesaikan .cs identitas aplikasi berbasis file. Standar: Debug. Teruskan konfigurasi yang sama dengan eksekusi yang digunakan: di Directory.Build.props samping .cs dapat mengatur WinAppPackageName atau WinAppManifestPath secara kondisional pada $(Configuration). Hanya berlaku untuk .cs input.
--arch <x64|arm64|x86> - Arsitektur target yang digunakan saat menyelesaikan .cs identitas aplikasi berbasis file. Default: arsitektur proses saat ini. Berikan arsitektur yang sama dengan eksekusi yang digunakan, karena identitas juga dapat di-key off $(RuntimeIdentifier). Hanya berlaku untuk .cs input.
-r, --runtime <rid>- Pengidentifikasi runtime .NET target (misalnya win-x64) yang digunakan saat menyelesaikan .cs identitas aplikasi berbasis file. Hanya arsitekturnya yang digunakan, dan mengambil alih --arch. Hanya berlaku untuk .cs input.
--output-appx-directory <path> - Direktori tata letak AppX tempat paket didaftarkan. Hanya diperlukan ketika eksekusi digunakan --output-appx-directory, karena tidak ada pada catatan paket yang menjalankan opsi menghasilkan tata letaknya.
--json - Format output sebagai JSON

Apa fungsinya:

Menentukan nama paket — dari identitas file yang .cs diselesaikan, atau dengan membaca manifes
Mencari kedua {name} paket dan {name}.debug (varian debug dibuat oleh create-debug-identity)
Memverifikasi setiap paket terdaftar dalam mode pengembangan (IsDevelopmentMode == true)
Memverifikasi paket milik aplikasi yang Anda beri nama (kecuali --force) — lokasi penginstalannya harus berada di bawah direktori yang Anda identifikasi: .cs output build file sendiri, direktori manifes, direktori saat ini, atau eksplisit --output-appx-directory. Paket yang lokasi penginstalannya tidak dapat diselesaikan (filenya dihapus) dilewati, karena identitas saja bukan bukti kepemilikan: dua aplikasi yang keduanya ditetapkan #:property WinAppPackageName=counter mendaftarkan identitas yang sama dari folder yang berbeda. Gunakan --prune untuk menghapus pendaftaran yang filenya hilang.
Membatalkan pendaftaran paket yang cocok

Membersihkan pendaftaran yang mati (--prune):

Pendaftaran keluar dari file-filenya. Hapus output build, pohon proyek, atau (untuk aplikasi berbasis file) biarkan Windows membersihkan %LOCALAPPDATA%\Temp, dan paket tetap terdaftar: Windows menjaga identitas dan entri menu Mulai, tetapi aktivasi diam-diam tidak melakukan apa-apa. Ini terakumulasi secara tak terlihat.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Hanya pendaftaran mode pengembangan yang dipertimbangkan, dan masing-masing dihapus dengan nama paket lengkapnya, sehingga paket bernama sama yang masih diinstal dari lokasi langsung tidak tersentuh. Perintah ada karena lokasi penginstalan yang hilang biasanya merupakan folder yang dihapus tetapi juga menjelaskan paket yang terdaftar dari berbagi jaringan yang terputus atau drive yang dapat dilepas — tinjau daftar sebelum mengonfirmasi.

Contoh:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

cert

Membuat, memeriksa, dan menginstal sertifikat pengembangan.

menghasilkan sertifikat

Hasilkan sertifikat pengembangan untuk penandatanganan paket.

winapp cert generate [options]

Opsi:

--manifest <Package.appxmanifest>- Ekstrak sertifikat publisher dari manifes Identity/@Publisher. Hanya penerbit yang diperlukan, sehingga manifes yang sebagian lengkap masih berfungsi. Jika manifes tidak memiliki penerbit yang dapat digunakan, perintah gagal alih-alih menggantikan default, sehingga sertifikat tidak pernah dapat secara diam-diam tidak cocok dengan manifes.
--publisher <name>- Publisher untuk sertifikat. Saat membuat sertifikat, opsi ini lebih diutamakan --manifest; nilai yang kosong secara eksplisit gagal alih-alih menggunakan penerbit manifes. Menerima nama khusus X.500 lengkap (misalnya, CN=Contoso, O=Contoso Ltd, C=US) atau nama kosong yang secara otomatis dibungkus sebagai CN=<name>. Komponen harus bernilai tunggal dan dipisahkan koma; RDN multinilai (CN=Foo+OU=Bar) dan garis miring terbelakang tidak didukung karena penerbit manifes MSIX tidak dapat mewakilinya. Nama khusus yang salah bentuk (misalnya CN= atau CN=A,,O=B) ditolak dengan keluar bukan nol dan kesalahan penamaan masalah, daripada menghasilkan sertifikat yang tidak pernah dapat mencocokkan penerbit manifes.
--output <path> - Jalur file sertifikat output (mendukung jalur absolut dan relatif)
--password <password> - Kata sandi sertifikat (default: password, yang diketahui publik — lihat output JSON dan Keamanan)
--valid-days <valid-days> - Jumlah hari sertifikat valid (default: 365)
--install - Instal sertifikat ke penyimpanan komputer lokal setelah pembuatan
--if-exists <Error|Overwrite|Skip> - Atur perilaku jika file sertifikat sudah ada (default: Kesalahan)
--export-cer - Ekspor .cer file (hanya kunci publik) bersama .pfxdengan . Berguna untuk mendistribusikan sertifikat publik secara terpisah untuk penginstalan kepercayaan.
--json - Format output sebagai JSON untuk konsumsi terprogram. Kesalahan juga dikembalikan sebagai JSON ({"error": "..."}).

Output JSON:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher adalah nama tampilan dan subjectName nama khusus lengkap yang dikeluarkan sertifikat. defaultPasswordIsPublic selalu ada. Ketika itu adalah true, .pfx dilindungi oleh kata sandi yang dapat ditebak siapa pun, sehingga sertifikat hanya boleh menandatangani build yang tetap ada di komputer Anda sendiri - periksa sebelum skrip menyerahkan sertifikat ke yang lain. warnings melakukan pengungkapan yang sama dengan teks dan dihilangkan ketika tidak ada yang perlu dilaporkan. publicCertificatePath hanya muncul dengan --export-cer.

info sertifikasi

Menampilkan detail sertifikat dari file PFX atau CER. Berguna untuk memverifikasi sertifikat yang cocok dengan manifes Anda sebelum menandatangani.

winapp cert info <cert-path> [options]

Argumen:

cert-path - Jalur ke file sertifikat (PFX atau CER)

Opsi:

--password <password> - Kata sandi untuk file PFX, diabaikan untuk CER publik (default: "kata sandi")
--json - Format output sebagai JSON

instalasi sertifikat

Instal sertifikat ke penyimpanan sertifikat komputer.

winapp cert install <cert-path> [options]

Argumen:

cert-path - Jalur ke file sertifikat untuk diinstal

Contoh:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

tanda

Tanda tangani paket MSIX dan executable dengan sertifikat.

winapp sign <file-path> <cert-path> [options]

Argumen:

file-path - Jalur ke paket MSIX atau dapat dieksekusi untuk ditandatangani
cert-path - Jalur ke sertifikat penandatanganan (.pfx)

Opsi:

--password <password> - Kata sandi sertifikat (default: "kata sandi")
--timestamp <url> - URL server tanda waktu RFC 3161

Contoh:

# Sign MSIX package
winapp sign MyApp.msix ./mycert.pfx

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

Menandatangani kode file (bundel exe, MSIX, atau MSIX) menggunakan Penandatanganan Tepercaya Azure — identitas penandatanganan yang dikelola cloud, sehingga tidak ada kunci privat (PFX) yang pernah ada di komputer lokal.

winapp az-sign <file-path> [options]

Argumen:

file-path - Jalur ke file yang akan ditandatangani (exe, msix, atau msixbundle)

Opsi:

--subscription, -s - Azure ID langganan yang akan digunakan. Jika tidak disediakan dan beberapa langganan ada, Anda akan diminta
--resource-group, -r - Grup sumber daya untuk mempersempit akun penandatanganan
--account - Nama akun penandatanganan. Harus digunakan dengan --resource-group
--profile, -p - Nama profil sertifikat. Harus digunakan dengan --account
--metadata-file, -m - Jalur ke metadata.json. Lewati penemuan sumber daya dan permintaan pemilihan akun/profil dan tanda tangan secara langsung. Kredensial Azure non-interaktif harus sudah tersedia; CLI dapat kembali ke permintaan penyewa interaktif atau az login, tetapi API terprogram npm selalu non-interaktif dan gagal alih-alih meminta

Otentikasi:

az-signmenggunakan rantai kredensial standar Azure (DefaultAzureCredential). Untuk CI/CD, atur AZURE_TENANT_ID, AZURE_CLIENT_ID, dan AZURE_CLIENT_SECRET (atau gunakan GitHub Actions OIDC / identitas terkelola). Sesi Azure CLI yang ada (az login, termasuk azure/login Tindakan GitHub) juga dihormati di lingkungan apa pun. Hanya ketika tidak ada kredensial yang ditemukan dan sesi interaktif akan az-sign diluncurkan az login untuk Anda.

Prasyarat:

Akun penandatanganan kode Azure dan profil sertifikat (dibuat di portal Azure setelah validasi identitas), ditambah peran Penandatangan Profil Sertifikat PenandatanganAn Kode yang ditetapkan ke identitas Anda. Untuk panduan selengkapnya, kunjungi dokumen mulai cepat Penandatanganan Artefak Azure.
Runtime x64 seluruh mesin .NET 8 (atau yang lebih baru) terinstal. Pustaka klien penandatanganan Azure adalah rakitan terkelola yang signtool.exe dimuat dalam proses terpisah; runtime mandiri winapp tidak memenuhinya. Instal dari https://dotnet.microsoft.com/download jika penandatanganan gagal dengan kesalahan pemuatan runtime.
Microsoft Visual C++ Redistributable (x64). Pustaka klien penandatanganan Azure tergantung pada runtime VC++, dan karena winapp mengunduh paket NuGet mentah daripada penginstal alat klien resmi, dependensi ini tidak diinstal secara otomatis. Mesin bersih dapat memuat-gagal bahkan dengan .NET dan SignTool ada. Instal x64 terbaru yang dapat didistribusikan ulang dari https://aka.ms/vs/17/release/vc_redist.x64.exe jika penandatanganan gagal dengan 0xc000007b, "Aplikasi tidak dapat dimulai dengan benar", atau kesalahan DLL yang hilang dari dlib.

CI hak istimewa terkecil: Penemuan otomatis (mencantumkan langganan, grup sumber daya, akun, dan profil) memerlukan akses baca di cakupan induk. Untuk menghindari setiap panggilan daftar koleksi, lewati keempat --subscription, , --resource-group, --account, dan --profile: az-sign lalu validasi akun dan profil dengan pembacaan sumber daya langsung (GET pada setiap sumber daya bernama) alih-alih menghitung koleksi induk, sehingga perwakilan yang tercakup hanya untuk akun dan profil itu saja sudah cukup. Menghilangkan salah satu dari mereka memperkenalkan kembali panggilan daftar — misalnya, keluar --subscription membuat az-sign daftar langganan yang dapat diakses identitas Anda — yang mungkin tidak diizinkan untuk dilakukan oleh prinsipal yang tercakup secara sempit. Perwakilan yang dilingkupkan hanya ke satu profil sertifikat dapat melewati validasi sepenuhnya dengan meneruskan pra-hasil --metadata-file (yang menentukan titik akhir akun dan profil secara langsung).

Contoh:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

create-external-catalog

Buat file katalog yang CodeIntegrityExternal.cat berisi hash file yang dapat dieksekusi dari direktori tertentu. Katalog ini digunakan dengan bendera TrustedLaunch dalam manifes paket jarang MSIX (AllowExternalContent) untuk memungkinkan eksekusi file eksternal tidak termasuk dalam paket itu sendiri.

Ini mirip dengan cara signtool.exe membuat saat menandatangani paket MSIX, tetapi menghasilkan katalog eksternal untuk digunakan dengan AppxMetadata\CodeIntegrity.cat.

winapp create-external-catalog <input-folder> [options]

Argumen:

input-folder - Satu atau beberapa direktori yang berisi file yang dapat dieksekusi untuk diproses. Pisahkan beberapa direktori dengan titik koma (misalnya, "dir1;dir2")

Opsi:

--recursive, -r - Sertakan file dari subdirektori
--use-page-hashes - Sertakan hash halaman saat membuat katalog (menghasilkan katalog yang lebih besar dengan data hash per halaman)
--compute-flat-hashes - Sertakan hash file datar saat membuat katalog
--if-exists <Error|Overwrite|Skip> - Perilaku ketika file output sudah ada (default: Error)
--output, -o - Jalur file katalog output. Jika tidak ditentukan, CodeIntegrityExternal.cat dibuat di direktori saat ini. Jika direktori ditentukan, nama file default ditambahkan.

Apa fungsinya:

Memindai direktori tertentu untuk file yang dapat dieksekusi (biner PE dengan bagian kode)
Menghasilkan File Definisi Katalog (CDF) dengan hash dari semua executable yang ditemukan
Menggunakan API CryptoCAT Windows untuk menghasilkan file katalog .cat
File yang tidak dapat dieksekusi (misalnya, .txt, .dll tanpa bagian kode) secara otomatis dilewati

Contoh:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Kapan menggunakan:

Gunakan perintah ini saat membuat paket MSIX jarang yang menggunakan TrustedLaunch untuk memverifikasi executable eksternal. Alur kerja umumnya adalah:

winapp manifest generate --template sparse — Membuat manifes jarang dengan AllowExternalContent
winapp create-external-catalog ./bin — Hasilkan katalog integritas kode untuk executable aplikasi Anda
winapp pack — Mengemas manifes, aset, dan katalog ke dalam MSIX

perangkat

Akses alat Windows SDK langsung. Menggunakan alat yang tersedia di Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Alat yang tersedia:

makeappx - Membuat dan memanipulasi paket aplikasi
signtool - Menandatangani file dan memverifikasi tanda tangan
mt - Alat manifes untuk rakitan berdampingan
Dan alat SDK Windows lainnya dari Microsoft.Windows. SDK. BuildTools

Contoh:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

Verifikasi tanda tangan

Alat build diunduh dari NuGet lalu dijalankan, sehingga winapp memeriksa masing-masing alat untuk tanda tangan Microsoft Authenticode yang valid segera sebelum menjalankannya. Sertifikat harus memberi nama Microsoft Corporation sebagai organisasi penandatanganan. Ini berlaku untuk setiap perintah yang keluar ke alat SDK, termasuk tool, , packagedan sign. Alat yang gagal, pemeriksaan tidak dijalankan:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Kegagalan di sini berarti file pada disk bukan yang Microsoft publikasikan — paling sering unduhan rusak atau parsial. Hapus paket dari cache NuGet dan jalankan perintah lagi sehingga winapp mengunduh ulang.

winapp kemudian menjaga alat tetap terbuka selama berjalan, sehingga file yang diperiksa adalah file Windows dimuat. Jika tidak dapat menahan alat di tempat, alat tersebut juga tidak dijalankan:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Tutup apa pun yang menggunakan file — pemindaian antivirus atau editor terbuka adalah penyebab yang biasa — dan jalankan perintah lagi. Jika alat hilang daripada digunakan, hapus paket dari cache NuGet sehingga winapp mengunduhnya kembali.

simpan

Jalankan perintah Microsoft Store Developer CLI. Perintah ini akan mengunduh Microsoft Store Developer CLI jika belum diunduh. Pelajari selengkapnya tentang Microsoft Store Developer CLI.

winapp store [args...]

Argumen:

args... – Argumen untuk diteruskan langsung ke msstore CLI. Lihat dokumentasi MSStore CLI untuk perintah dan opsi yang tersedia.

Apa fungsinya:

Memastikan Microsoft Store Developer CLI (msstore) diunduh dan tersedia di sistem Anda.
Meneruskan semua argumen ke msstore CLI.
Menjalankan perintah yang menunjukkan output langsung di terminal Anda.

Contoh:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

Dapatkan Jalur Aplikasi Windows

Dapatkan jalur untuk menginstal komponen Windows SDK.

winapp get-winapp-path [options]

Apa yang dikembalikannya:

Jalur ke .winapp direktori ruang kerja
Direktori penginstalan paket
Lokasi header yang dihasilkan

sasaran

Jalankan perintah, salin file, periksa status, atau ambil seluruh desktop tamu.

Setiap kata kerja mengambil sandbox sebagai argumen pertamanya. Kecuali untuk snapshot, perintah ini dapat menyiapkan atau memulai Sandbox. Lihat Windows eksekusi Sandbox untuk prasyarat, izin, siklus hidup, dan pemulihan.

target exec

Jalankan perintah sebagai pengguna tamu.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

Argumen setelah -- mempertahankan batasannya. Aliran standar dan kode keluar proses tamu diteruskan; ini bukan terminal penuh. --json memformat kegagalan winapp pada stderr tanpa mengubah stdout perintah turunan. Gunakan terstruktur error.code untuk membedakan kegagalan target dari status keluar aplikasi sendiri.

Eksplisit WINAPP_UI_WORKFLOW_ID juga mengelompokkan panggilan UI tamu yang dilakukan oleh perintah; lihat Koordinasi UI Sandbox.

pendorongan target dan penarikan target

Salin file atau direktori ke arah yang dinamai oleh kata kerja.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Jalur target relatif terhadap area kerja terkelola target; jalur target absolut, berakar, dan UNC ditolak. Tujuan file menyertakan nama filenya. Lihat Menjalankan perintah dan menyalin file untuk tata letak direktori, penanganan tautan, dan menjalankan skrip yang disalin.

rekam jepret target

Laporkan kesiapan, penyebaran, dan jendela tamu tanpa memulai Sandbox.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

Ini tidak menghubungkan kembali klien atau memperbaiki agen. Tidak ada Sandbox yang berjalan adalah hasil yang berhasil, bukan kesalahan. Lihat Memeriksa Sandbox untuk menginterpretasikan kesiapan dan ID proses.

cuplikan layar target

Ambil desktop tamu pada ukuran piksel aslinya sebagai PNG host, tanpa pemilih aplikasi atau batas jendela host. --json melaporkan asal koordinat tamu.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Gunakan ui screenshot --on sandbox -a <app> untuk jendela aplikasi sebagai gantinya. Lihat Cuplikan layar dan rekaman untuk persyaratan klien, batasan fokus, dan penanganan output.

catatan target

Rekam desktop tamu ke H.264 MP4. File video dan bingkai host tiba setelah perekaman selesai; JSON dan manifes bingkai menjelaskan skala atau padding apa pun.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Menggunakan opsi ui recorddurasi, bingkai, timpa, dan hasil , tetapi mengambil desktop daripada satu aplikasi. Lebih suka positif --duration-sec untuk penggunaan CLI tanpa pengawas durationSec; pembantu npm memerlukan . Lihat Pengambilan sandbox untuk bukti parsial dan kegagalan kesiapan pengambilan.

find-ui

Agen-pertama. find-ui dibangun terutama untuk agen pengkodean AI — memungkinkan agen menarik markup WinUI nyata dan mengompilasi dari galeri pengiriman alih-alih menemukannya, dan --json membuat setiap hasil (dan setiap kegagalan) dapat dibaca mesin. Cara kerjanya juga ditik dengan tangan.

Cari kontrol dan sampel WinUI untuk contoh kode kerja. Khusus WinUI: korpus adalah Galeri WinUI 3 dan Toolkit Komunitas Windows (ditambah beberapa pola inti yang dikumpulkan) — tidak mencakup WPF, WinForms, atau kerangka kerja UI lainnya. Sumber ketiga, ReactorGallery microsoft-ui-reactor, adalah keikutsertaan: itu dikecualikan dari pencarian normal dan hanya dicari saat Anda meneruskan --source reactor (sampel deklaratif C#-only-nya tidak menempel ke aplikasi XAML standar, jadi jangkau hanya saat membangun proyek Reactor/MVU).

winapp find-ui "<query>" [options]

Corpora Gallery, Toolkit, dan Reactor dikirim ke dalam CLI, jadi find-ui bekerja tanpa akses jaringan — termasuk pada eksekusi pertama kali di sandbox agen atau di belakang proksi perusahaan yang memblokir raw.githubusercontent.com. Ketika GitHub dapat dijangkau, CLI menyegarkan darinya dan menyimpan hasil per pengguna di bawah <global .winapp>/cache/find-ui; korpus bawaan hanyalah lantai, tidak pernah langit-langit. Data cache di-refresh paling banyak setiap 24 jam, atau sesuai permintaan dengan --refresh.

Korpus bawaan diambil kembali dari GitHub setiap kali rilis stabil dibuat, dan refresh yang gagal menghentikan build rilis daripada mengirim data yang lebih lama secara diam-diam — pembuat roti mengambil melalui jalur --refresh kode yang sama menggunakan, jadi kegagalan di sana berarti refresh langsung rusak juga dan layak diselidiki sebelum pengiriman. Rilis masih dapat dipotong terhadap korpus yang diterapkan sebelumnya, tetapi hanya sebagai penimpaan eksplisit. Ketika hasil disajikan dari salinan bawaan corpora Gallery/Toolkit/Reactor, find-ui mengatakan demikian pada stderr dan --json output membawa "corpus": "embedded" (nilai lain: "network" untuk pengambilan baru, "cache" untuk cache lokal). Permintaan khusus inti — --source core, atau set --id yang semuanya merupakan pola inti — juga melaporkan "embedded" , karena pola inti yang dikumpulkan dikompilasi ke dalam CLI dan tidak pernah diambil; tidak mencetak pemberitahuan kedaluwarsa, --refresh karena tidak dapat mengubahnya. Bidang corpus dilaporkan setiap kali hasil dilayani; tidak ada hanya ketika tidak ada korpus yang dapat dimuat sama sekali.

Opsi:

--id <id> - Ambil kode (Gallery/Toolkit mengembalikan XAML dan/atau C#; Reaktor adalah C#-only) ditambah catatan prasyarat untuk satu atau beberapa id skenario dari pencarian sebelumnya (misalnya gallery-tabview-1). Berulang. Id tidak peka huruf besar/kecil — GALLERY-TABVIEW-1 menyelesaikan hal yang sama seperti gallery-tabview-1.
--list - Cantumkan setiap kontrol/id sampel yang dapat ditemukan alih-alih pencarian (Galeri + Toolkit + inti; sumber Reaktor keikutsertaan dikecualikan).
--source <gallery|toolkit|reactor|core> - Membatasi hasil pencarian ke satu sumber. (Cari saja — tidak valid dengan --list/--id.) Reaktor ikut serta — dikecualikan dari pencarian normal, jadi --source reactor adalah satu-satunya cara untuk mencarinya.
--max <N> - Jumlah maksimum kontrol yang cocok untuk dikembalikan (default: 3). Hanya berlaku untuk pencarian; diabaikan dengan --list/--id.
--refresh- Melewati cache lokal dan mengambil kembali korpus WinUI dari GitHub.
--json - Memancarkan JSON terstruktur (ramah agen). Untuk pencarian, setiap kecocokan membawa source, , scorecontrol, description, dan scenarios array yang entrinya menyimpan per skenario id dan header; untuk --id, kode lengkap. Di bawah --jsonsetiap kegagalan — termasuk kesalahan argumen/pengurai seperti non-bilangan bulat --max — dipancarkan sebagai objek datar {"error": "..."} pada stdout dengan kode keluar bukan nol, sehingga output tetap dapat dibaca mesin.

Alur kerja: cari secara ringkas untuk menemukan kontrol yang tepat dan id skenarionya, lalu ambil kode lengkap untuk kecocokan terbaik dengan --id.

Contoh:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

Terkait:find-ui mencari sampel WinUI; gunakan find-api untuk mencari permukaan API (jenis, anggota, enum) referensi proyek, dan winapp ui search untuk mencari pohon UI aplikasi yang sedang berjalan .

find-api

Agen-pertama. find-api dibangun terutama untuk agen pengodean AI - ini membumikan kode yang dihasilkan di permukaan API proyek benar-benar mereferensikan alih-alih rekolleksi model itu, dan --json ditambah kode keluar bukan nol pada simbol yang hilang memungkinkan codegen gerbang agen pada jawabannya. Cara kerjanya juga ditik dengan tangan.

Cari dan periksa permukaan API Windows/WinRT (jenis, anggota, enum, namespace layanan) yang tersedia untuk proyek, diselesaikan dari metadata yang dirujuk.winmd/.dll. Bentuk telanjang mencari; sub-kata kerja menelusuri jenis, namespace, atau indeks tertentu itu sendiri.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

Indeks dibangun dari paket NuGet/SDK yang dipulihkan proyek (melalui project.assets.json) pada penggunaan pertama dan disegarkan secara otomatis saat proyek dipulihkan. Ini berada di bawah cache global .winapp (cache/find-api/) dan dibagikan di seluruh proyek. Pulihkan proyek terlebih dahulu (winapp restore atau dotnet restore).

Setiap kecocokan tercantum di bawah namespace layanannya dengan paket yang mengirimkannya dan ringkasan satu baris tentang apa yang dilakukannya, sehingga hasilnya dapat digunakan tanpa panggilan kedua members :

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Tambahkan --verbose juga untuk mencetak file cache pada disk yang mendukung setiap namespace layanan, yang berguna saat mendiagnosis indeks kedaluwarsa atau tidak terduga.

Berjalan winapp find-api tanpa kueri sama sekali mencetak ringkasan penggunaan singkat dan keluar 0 — ini adalah permintaan bantuan, bukan pencarian yang tidak menemukan apa pun.

Cakupan. Setiap jawaban berasal dari tepat satu cakupan, dilaporkan sebagai scope dalam --json dan sebagai catatan dalam output teks:

project - proyek di direktori saat ini (atau --project / --project-dir). Mencakup Windows SDK, SDK Aplikasi Windows, dan paket NuGet proyek sendiri. Metadata SDK Aplikasi Windows adalah rilis referensi proyek: jika komputer memiliki Windows App Runtime yang lebih baru yang diinstal, find-api memperingatkan dan membiarkannya keluar daripada mengonfirmasi jenis yang tidak dapat dikompilasi proyek.
sdk- metadata SDK + SDK Aplikasi Windows Windows di seluruh komputer, digunakan secara otomatis ketika direktori saat ini tidak berisi proyek dan tanpa solusi. Ini membuat find-api dapat digunakan untuk menjelajahi API sebelum proyek apa pun ada, dan tidak memerlukan akses jaringan. Ini sengaja tidak termasuk paket NuGet pihak ketiga, sehingga jenis dari (misalnya) Toolkit Komunitas tidak akan ditemukan dalam cakupan ini.

Kueri dari direktori tanpa proyek dan tidak ada solusi yang selalu dijawab oleh sdk cakupan - tidak pernah oleh proyek mana pun yang kebetulan diindeks dalam cache bersama - sehingga hasil tidak pernah bergantung pada status global yang tidak terkait. Teruskan --project sdk untuk memilih cakupan SDK secara eksplisit dari dalam proyek, dan winapp find-api refresh --project sdk untuk membangunnya kembali setelah menginstal SDK Windows baru.

Direktori solusi. Dari direktori yang .sln/.slnx memegang tanpa file proyek di sampingnya, proyek yang dibangun solusi menjawab alih-alih sdk cakupan - mereka diindeks sesuai permintaan, sehingga paket NuGet mereka disertakan. Saat solusi membangun lebih dari satu proyek terindeks, kueri mencantumkannya dan meminta --project <name> daripada memilihnya.

Perintah:

(Telanjang)find-api "<query>" ["<query>"...] - Jenis pencarian dan nama anggota, kembali ke ringkasan yang didokumenkan, dikelompokkan menurut namespace layanan
members <type> [<type>...] [--filter <text>] - Mencantumkan properti, peristiwa, dan metode jenis (anggota yang dideklarasikan dengan tanda tangan, anggota yang diwariskan yang dirangkum dengan mendeklarasikan jenis)
check-property <type> <property> [<property>...] - Validasi properti ada pada jenis (keluar dari non-nol jika ada yang hilang). Properti baca-saja dilaporkan dengan ⚠️ dan "baca-saja, tidak dapat ditetapkan" daripada biasa ✅, sehingga properti seperti ActualWidth tidak salah untuk sesuatu yang dapat Anda tetapkan. Nama properti dicocokkan dengan huruf besar/kecil, karena C# dan XAML adalah: check-property Button background keluar dari non-nol dan menawarkan Background sebagai kecocokan dekat daripada melaporkan nama yang tidak benar-benar dapat Anda tulis.
enums <type> [<type>...] [--filter <text>] - Mencantumkan nilai enum (keluar dari bukan nol ketika jenisnya bukan enum)
packages - Mencantumkan paket metadata terindeks, dengan jumlah jenis/anggota per paket
stats - Tampilkan statistik indeks agregat (paket, namespace, jenis, anggota, .winmd file)
refresh [--scan] - Membangun kembali indeks untuk proyek (--scan mengindeks setiap proyek di bawah direktori). Dengan --project <name>, nama yang cocok dengan tidak ada proyek terindeks tunggal yang gagal alih-alih mengindeks direktori saat ini.

Batching.search, members, enums, dan check-property terima beberapa subjek dalam satu pemanggilan. Untuk agen AI, ini adalah tuas biaya terbesar tunggal: biaya marginal pencarian didominasi oleh perjalanan pulang pergi (setiap panggilan mengirim ulang seluruh percakapan), bukan dengan ukuran payload, sehingga satu panggilan menjawab sepuluh pertanyaan jauh lebih murah daripada sepuluh panggilan.

Satu subjek mengembalikan bentuk payload yang selalu dimilikinya, baik dalam teks --jsonmaupun .
Dua subjek atau lebih mengembalikan amplop — { "count": N, "results": [ ... ] } di --json, dengan setiap elemen menjadi payload subjek tunggal normal; check-property menambahkan missingCount. Output teks merender setiap subjek secara berurutan di bawah satu header cakupan.
check-property batch properti pada satu jenis: argumen pertama adalah jenis , setiap argumen setelah itu adalah properti . Dalam mode batch, properti yang ada mencetak satu ✅ baris; detail mendekati miss penuh hanya dicetak untuk yang tidak.
Batch keluar 0 hanya jika setiap subjek diselesaikan dan ditemukan — sehingga batch masih aman untuk mengaktifkan codegen gerbang.

Cari peringkat. Kueri yang sama persis dengan nama jenis diberi peringkat di depan kecocokan parsial, dan ketika nama pendek dibagikan oleh beberapa namespace hanya tabrakan nama yang tepat yang tercantum sebagai ambigu — kueri seperti NavigationView melaporkan beberapa namespace yang menentukan jenis yang tepat daripada setiap namespace yang berisi simbol bernama serupa. Daftar ambiguitas mematuhi --max, dan hasil normal masih dicetak di bawahnya.

Ketik nama.members, check-property, dan enums terima nama pendek (NavigationView) atau nama yang sepenuhnya memenuhi syarat (Microsoft.UI.Xaml.Controls.NavigationView). Ketika nama pendek dibagikan oleh jenis modern Microsoft.* dan kembar UWP warisannyaWindows.*, Microsoft.* jenis menjawab — yaitu proyeksi yang digunakan aplikasi SDK Aplikasi Windows — dan nama yang sepenuhnya memenuhi syarat yang diselesaikan selalu ditampilkan. Tabrakan lain keluar bukan nol dan mencantumkan kandidat alih-alih menebak.

Tanda tangan metode. Tanda tangan dicetak dengan cara Anda akan menulis panggilan: metode yang Anda panggil pada jenis daripada pada instans ditampilkan dengan static, dan parameter referensi ditunjukkan dengan kata kunci yang benar-benar dibutuhkan — out, , inatau ref. Jadi TryGetValue membaca Boolean TryGetValue(String key, out String value), yang mengkompilasi seperti yang ditulis.

Opsi:

--max <n> - Jumlah maksimum hasil pencarian yang dikelompokkan namespace (default 5; hanya pencarian). Juga membatasi daftar ambiguitas, sehingga kueri singkat yang bertabrakan di banyak namespace tetap dapat dibaca.
--filter <text> - Persempit daftar pada members dan enums: substring yang tidak peka huruf besar/kecil pada nama anggota/nilai. Paling baik digunakan pada jenis dengan ratusan anggota. Sebagian besar enum cukup kecil untuk membuang utuh (bahkan Symbol, yang terbesar di WinUI pada nilai 197), jadi memfilternya biasanya biaya lebih dari yang menghemat setelah Anda memperhitungkan tebakan kedua. Jangan pernah menjalankan kembali perintah yang sama dengan teks filter yang berbeda — buang sekali dan baca.
--all - Pada members, cantumkan permukaan lengkap: tanda tangan penuh untuk anggota yang diwariskan, ditambah statis pengidentifikasi properti dependensi dan deskripsi per anggota, yang semuanya dihilangkan daftar yang tidak difilter (lihat Ukuran daftar di bawah). --verbose menyiratkannya; gunakan --all ketika Anda juga menginginkan --json, yang tidak dapat dikombinasikan dengan --verbose.
--scan - Menemukan dan mengindeks setiap proyek secara rekursif di bawah direktori (refresh hanya)
--project <name>- Project untuk mengkueri (cocok dengan .csproj/.vcxproj nama), atau sdk untuk mengkueri cakupan SDK Windows di seluruh komputer
--project-dir <path>- Project direktori ke kueri (default ke direktori saat ini). Jalur yang tidak ada adalah kesalahan — jalur tersebut tidak pernah dijawab secara diam-diam sdk dari cakupan.
--json - Memancarkan payload yang dapat dibaca mesin pada stdout (didukung oleh setiap kata kerja). Payload kueri mengidentifikasi indeks yang menjawab melalui ( atau ), projectName, dan projectDir (tidak ada untuk cakupan SDK) — nama proyek tidak unik di seluruh direktori, begitu juga projectDir identitas yang dapat diandalkansdk.projectscope Di bawah --jsonsetiap kegagalan — termasuk kesalahan argumen/pengurai seperti non-bilangan bulat --max — dipancarkan sebagai objek datar {"error": "..."} pada stdout dengan kode keluar bukan nol, sehingga output tetap dapat dibaca mesin.

Contoh:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Ketika --filter diterapkan, output masih melaporkan total yang tidak difilter (totalValues, atautotalEvents//totalPropertiestotalMethods di --json), sehingga tampilan sempit tidak pernah keliru untuk API kecil. Filter yang cocok dengan tidak ada yang masih keluar 0 dan mengatakan begitu eksplisit — yaitu "tidak ada yang cocok dengan filter Anda", bukan "tidak ada jenis seperti itu".

Ukuran daftar. Daftar yang tidak difilter members adalah satu bentuk mahal — members Button mencakup 288 anggota, di mana 280 diwariskan dari 6 jenis dasar. Panggilan yang tidak difilter adalah kueri orientasi ("apa jenis ini, kira-kira apa yang dapat dilakukannya?"), sehingga menjawabnya dan menghilangkan bagian tidak ada yang ditulis dari:

Tanda tangan anggota yang diwariskan — anggota yang diwariskan dikelompokkan dengan mendeklarasikan jenis dan dicantumkan berdasarkan nama saja, sehingga bentuk permukaan yang diwariskan masih terlihat tanpa 280 tanda tangan penuh.
Statis pengidentifikasi properti dependensi (BackgroundProperty) — 28% properti kontrol WinUI yang khas. Mereka ada untuk diteruskan ke GetValue/SetValue, tidak ditetapkan.
Deskripsi per anggota — prosa XML-doc, kira-kira 16% payload.
Bidang yang disiratkan oleh lingkungannya di --json: kind (tersirat oleh array yang berisiproperties//eventsmethods), returnType (token signaturedepan ), dan inherited ketika false (tersirat oleh ).declaringType

Apa yang dihilangkan selalu dilaporkan (hiddenDependencyProperties, descriptionsOmitted, dan hint dalam --json; baris "Dihilangkan:" dalam teks), dan total masih menjelaskan seluruh jenis. Baik --filter dan --all lihat permukaan lengkap dengan tanda tangan dan deskripsi lengkap, jadi members Button --filter BackgroundProperty masih menemukan pengidentifikasi dan members Button --filter Click masih mengembalikan Clicktanda tangan yang diwariskan. Diukur pada samples/winui-app, ini membutuhkan waktu members Button --json dari 91.954 hingga 10.567 karakter (−88,5%) sambil pergi --filter dan --all byte-identik.

Bagaimana kueri dicocokkan. winapp find-api "language model" LanguageModel peringkat di atas cocok dengan kata-kata yang tersebar di seluruh namespace dan anggota, termasuk di luar proyek saat jenis diindeks. Pencarian bersifat leksikal, bukan semantik: ini cocok dengan seluruh kata pengidentifikasi alih-alih menjalankan huruf apa pun, jadi llm menemukan IImageLLMAdapterSession tetapi tidak ScrollMode. Ketika kueri tidak cocok dengan nama, kueri dicoba terhadap ringkasan jenis dan anggota yang didokumentasikan, yang memungkinkan "random-access stream" menemukan IRandomAccessStream. Deskripsi peringkat di bawah setiap nama cocok, dan hanya merangkum paket yang benar-benar dapat dicari - paket tanpa dokumentasi XML tidak berkontribusi pada teks deskripsi.

Proyek tanpa file proyek MSBuild. Aplikasi Electron (atau aplikasi non-.NET lain yang didorong oleh winapp.yaml) tidak .csproj memiliki dan oleh karena itu tidak ada project.assets.json. find-api mengindeksnya dari .winapp/winmds.lock.json yang menulis, yang merekam hal yang sama: setiap paket yang diselesaikan, versinya, dan file yang winapp restore.winmd dikontribusikannya. Proyek seperti itu dinamai sesuai direktorinya, dan indeksnya kedaluwarsa ketika lockfile ditulis ulang. Direktori yang menyimpan .csproj dan winapp.yaml diindeks dari .csproj, yang merupakan deskripsi yang lebih tepat tentang apa yang dikompilasi proyek.

Jawaban negatif memenuhi syarat ketika indeks tidak lengkap. Jika metadata paket tidak dapat dibaca, "tidak ada jenis seperti itu" dan "paket itu tidak pernah diindeks" terlihat identik - dan bertindak pada yang pertama ketika benar-benar yang kedua menghasilkan kode terhadap API yang Anda diberitahu tidak ada. Jadi setiap jawaban negatif, termasuk search yang mengembalikan hasil nol, membawa catatan bahwa indeks adalah parsial dan titik di winapp find-api refresh. Jawaban positif tidak terpengaruh.

Nama jenis generik. Metadata menyimpan jenis generik dengan akhiran aritas (IAsyncOperation`1), yang bukan bagaimana siapa pun menulisnya. members, enums, dan check-property terima setiap formulir: IAsyncOperation, IAsyncOperation<StorageFile>, dan IAsyncOperation`1 semua diselesaikan ke jenis yang sama. Nama kosong cocok dengan aritas apa pun; aritas yang dinyatakan (dalam salah satu notasi) harus cocok, jadi Holder<A, B> tidak akan diselesaikan ke parameter Holder<T>tunggal .

--json payload menghilangkan diagnostik. Jalur file cache hanya muncul di bawah --verbose (output teks yang cocok, di mana mereka sudah verbose-saja), dan array saran kosong dihilangkan daripada diserialisasikan sebagai [].

Kode keluar:search tanpa hit, check-property pada properti yang hilang, dan enums pada jenis non-enum semua keluar dari non-nol - pembuatan kode gerbang dan pemeriksaan CI pada mereka. Pemanggilan batch keluar dari non-nol jika ada subjek yang gagal. Properti baca-saja bukan kegagalan — itu ada, sehingga check-property keluar 0 dan menandainya dalam output (writable: false dalam --json). Properti init melaporkan writable: false karena alasan yang sama: properti dapat diatur dalam penginisialisasi objek, dan tanda tangannya mengatakan { get; init; }, tetapi menetapkannya setelahnya tidak dikompilasi.

Terkait:find-api menjawab "apakah API ini ada dan apa anggotanya?"; gunakan find-ui untuk menemukan sampel WinUI yang berfungsi untuk kontrol.

node generate-bindings

(Hanya tersedia dalam paket NPM) Buat pengikatan JS untuk API SDK Aplikasi Windows. Pengikatan dideklarasikan oleh "winapp": { "jsBindings": {...} } namespace di package.json dan ditulis ke .winapp/bindings/.

npx winapp node generate-bindings [options]

Opsi:

--verbose, -v - Aktifkan output verbose per file codegen
--quiet, -q - Menekan kemajuan dan output informasi

Apa fungsinya:

winapp.jsBindings Membaca blok dari package.json dan yang winmds.lock.json ditulis oleh yang terakhir winapp restore, lalu memancarkan pengikatan yang ditik .js + .d.ts ke dalam.winapp/bindings/
Tidak memodifikasi package.json — ini adalah regenerator pasif. winapp.jsBindings Menambahkan blok dan @microsoft/dynwinrt dependensi runtime terjadi saat winapp init pengikatan JS diaktifkan; perintah ini gagal dengan cepat jika blok tidak ada
Memperingatkan (tetapi tidak menulis) jika @microsoft/dynwinrt hilang dari dependensi Anda — jalankan npm install setelah init menambahkannya

Nota

Pengikatan hanya npm - mereka memerlukan pemanggilan melalui npx winapp (@microsoft/winappclipaket npm); CLI winget mandiri tidak memunculkannya. Jalankan winapp init secara interaktif dan ikut serta, atau gunakan winapp init . --use-defaults --add-js-bindings, sebelum menggunakan perintah ini untuk meregenerasi pengikatan. Jika Anda mengedit winapp.yaml, jalankan npx winapp restore untuk merefresh dependensi Windows sebelum meregenerasi.

Contoh:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Lihat panduan pengikatan JS untuk alur kerja end-to-end dan winapp.jsBindings opsi konfigurasi.

node membuat-addon

(Hanya tersedia dalam paket NPM) Menghasilkan templat addon C++ atau C# asli dengan Windows SDK dan integrasi SDK Aplikasi Windows.

npx winapp node create-addon [options]

Opsi:

--name <name> - Nama addon (default: "nativeWindowsAddon")
--template - Pilih jenis addon. Opsi adalah cs atau cpp (default: cpp)
--verbose - Aktifkan output verbose

Apa fungsinya:

Membuat direktori addon dengan file templat
Menghasilkan binding.gyp dan addon.cc dengan contoh SDK Windows
Menginstal dependensi npm yang diperlukan (nan, node-addon-api, node-gyp)
Menambahkan skrip build ke package.json

Contoh:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

node add-electron-debug-identity

(Hanya tersedia dalam paket NPM) Tambahkan identitas aplikasi ke proses pengembangan Electron dengan menggunakan kemasan jarang. Memerlukan Package.appxmanifest (buat dengan winapp init atau winapp manifest generate jika Anda tidak memilikinya).

Penting

Ada masalah yang diketahui dengan aplikasi Electron kemasan jarang yang menyebabkan aplikasi crash pada awal atau tidak merender konten web. Masalah ini telah diperbaiki di Windows tetapi belum menyebar ke perangkat Windows eksternal. Jika Anda melihat masalah ini setelah memanggil add-electron-debug-identity, Anda dapat menonaktifkan kotak pasir di aplikasi Electron untuk tujuan debug dengan --no-sandbox bendera. Masalah ini tidak memengaruhi kemasan MSIX penuh.

Untuk menghapus identitas debug Electron, gunakan winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Opsi:

Option	Deskripsi
`--manifest <path>`	Jalur ke Package.appxmanifest kustom (default: Package.appxmanifest di direktori saat ini)
`--no-install`	Jangan memasang atau memodifikasi dependensi; hanya mengonfigurasi identitas debug Electron.
`--keep-identity`	Pertahankan identitas manifes as-is, tanpa menambahkan `.debug` ke nama paket dan ID aplikasi
`--verbose`	Mengaktifkan output verbose

Apa fungsinya:

Mendaftarkan identitas debug untuk proses electron.exe
Memungkinkan pengujian API yang memerlukan identitas dalam pengembangan Electron
Menggunakan Package.appxmanifest yang ada untuk konfigurasi identitas

Contoh:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node clear-electron-debug-identity

(Hanya tersedia dalam paket NPM) Hapus identitas paket dari proses debug Electron dengan memulihkan electron.exe asli dari cadangan.

npx winapp node clear-electron-debug-identity [options]

Opsi:

Option	Deskripsi
`--verbose`	Mengaktifkan output verbose

Apa fungsinya:

Memulihkan electron.exe dari cadangan yang dibuat oleh add-electron-debug-identity
Menghapus file cadangan setelah pemulihan
Mengembalikan Electron ke status aslinya tanpa identitas paket

Contoh:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Opsi Global

Semua perintah mendukung opsi global ini:

--verbose, -v - Aktifkan output verbose untuk pengelogan terperinci
--quiet, -q - Menyembunyikan pesan kemajuan
--help, -h - Tampilkan bantuan perintah

Direktori Singgahan Global

Winapp membuat direktori untuk menyimpan file yang dapat dibagikan di antara beberapa proyek.

Secara default, winapp membuat direktori di $UserProfile/.winapp sebagai direktori cache global.

Untuk menggunakan lokasi yang berbeda, atur WINAPP_CLI_CACHE_DIRECTORY variabel lingkungan.

Dalam cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Di PowerShell dan pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Winapp akan membuat direktori ini secara otomatis ketika Anda menjalankan perintah seperti init atau restore.

Perbarui Pemeriksaan

Winapp CLI secara berkala memeriksa versi baru dan menampilkan pemberitahuan satu baris saat pembaruan tersedia. Pemeriksaan ini berjalan di latar belakang dan tidak menambahkan latensi ke perintah.

Pemeriksaan pembaruan secara otomatis dinonaktifkan di lingkungan CI (GitHub Actions, Azure Pipelines, dll.).

Untuk menonaktifkan pemeriksaan pembaruan secara manual, atur WINAPP_CLI_UPDATE_CHECK variabel lingkungan ke 0.

Dalam cmd:

set WINAPP_CLI_UPDATE_CHECK=0

Di PowerShell dan pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Untuk membuat ini permanen:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

Identitas alur kerja UI

winapp ui perintah yang mendorong desktop fisik selalu bergantian kooperatif, sehingga dua alur kerja yang berjalan sekaligus tidak dapat mencuri fokus satu sama lain atau mengabaikan menu satu sama lain. Arbitrase tersebut tidak memerlukan penyiapan dan tidak dapat dinonaktifkan.

Apa itu opsional adalah kelangsungan. Secara default, setiap perintah adalah satu bidikan mandiri yang merilis desktop segera setelah selesai. Untuk mempertahankan desktop di beberapa perintah, berikan semua id alur kerja yang sama:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

Gunakan nilai yang sama untuk menggandeng proses (misalnya rekaman dan klik yang harus diambilnya) dan nilai yang berbeda untuk alur kerja independen. Setiap perintah tanpa id adalah alur kerja satu bidikan sendiri, bahkan ketika beberapa diluncurkan dari satu shell, sehingga host yang memulai shell baru per perintah harus menyuntikkan nilai eksplisit yang sama ke masing-masing. Nilai buram, tidak pernah diperlakukan sebagai kredensial, dan hanya pernah bertahan sebagai hash SHA-256. Lihat UI Automation → Mengoordinasikan alur kerja UI bersamaan.

ui

Periksa dan berinteraksi dengan menjalankan UI aplikasi Windows menggunakan UI Automation (UIA).

winapp ui [command] [options]

Perintah:

status - Sambungkan ke aplikasi dan tampilkan info
inspect - Lihat pohon elemen
search - Temukan elemen menurut pemilih
get-property - Membaca properti elemen
get-text / get-value - Membaca nilai/teks dari elemen (TextPattern, ValuePattern, atau Name)
screenshot - Ambil jendela/elemen sebagai PNG (beberapa jendela membentuk satu PNG komposit berlabel; lihat mengambil cakupan)
record- Rekam wilayah jendela/elemen ke video H.264 MP4 (Windows Graphics Capture + Media Foundation)
invoke - Aktifkan elemen (klik, alihkan, perluas)
click - Klik elemen melalui simulasi mouse (untuk kontrol yang tidak mendukung pemanggilan)
hover - Pindahkan mouse ke elemen untuk memicu tipsalat, flyout, dan status hover (tinggal default: 800ms)
drag - Seret mouse dari satu titik ke titik lainnya, menurut pemilih elemen atau koordinat layar x,y (urutkan ulang, mengubah ukuran, penggeser, seret dan letakkan)
touch- Suntikkan gerakan sentuh sintetis (ketuk, ketuk dua kali, tekan panjang, gesek, jepit, regangkan) di pusat elemen atau koordinat layar x,y
pen - Menyuntikkan input pena/stylus sintetis — ketukan dan goresan tinta dengan tekanan, tilt, dan mode penghapus yang dapat dikonfigurasi
send-keys - Mengirim input keyboard sintetis (bernama tombol, kombo, vk=0xNN mentah, atau teks literal) ke jendela
set-value - Tetapkan nilai pada elemen yang dapat diedit (teks, angka); kembali ke LegacyIAccessible put_accValue untuk kontrol edit kaya khusus TextPattern
focus - Pindahkan fokus keyboard
scroll-into-view - Elemen gulir terlihat
wait-for - Tunggu status elemen
list-windows - Mencantumkan semua jendela untuk aplikasi
get-focused - Laporkan elemen yang saat ini difokuskan
yield - Merilis giliran UI alur kerja saat ini; membutuhkan WINAPP_UI_WORKFLOW_ID

Opsi:

-a, --app <app> - Aplikasi target (nama, judul, atau PID)
-w, --window <hwnd> - Jendela target menurut HWND (stabil)
--on <target> - Jalankan kata kerja apa pun ui di sandbox; nama, PID, dan handel jendela merujuk ke tamu. Output dikirimkan ke host. Lihat Otomatisasi antarmuka pengguna Sandbox untuk penyiapan, koordinasi alur kerja, dan persyaratan klien.

catatan ui

Rekam jendela atau wilayah elemen ke H.264 MP4.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

Opsi rekaman:

--duration-sec <n> - Panjang rekaman dalam detik. 0 rekaman hingga Ctrl+C (default 0).
--fps <n> - Bingkai per detik untuk diambil (default 15).
--max-edge <px> - Downscale sehingga tepi terpanjang paling banyak ini banyak piksel (0 = tidak ada downscale).
--capture-screen - Ambil dari layar sehingga overlay/popup disertakan (dapat menangkap jendela yang menempati).
-o, --output <path> - Jalur output .mp4 (default ke recording-<timestamp>-<guid>.mp4).
--overwrite - Ganti output rekaman yang ada setelah proses baru selesai; output yang ada ditolak secara default. Bundel bingkai sebelumnya dipertahankan. Lihat Merekam pemulihan output.
--frames - Tulis JPEG bertanda waktu, , frames.ndjsondan manifest.json ke <output-name>.frames. Mendukung 1-30 fps dan --max-edge 64-4096 (default 1280), dengan batas frame-data 1 GiB.

Dengan --json, hasil akhir mencakup jalur output, dimensi, codec, mode pengambilan, irama, alasan berhenti, opsional frameArtifacts, dan peringatan.

Batasan yang diketahui: merekam elemen tertentu di dalam popup yang dirender di jendela tingkat atasnya sendiri (flyout WinUI/XAML, tip pengajaran, tipsalat) dapat menangkap jendela utama yang mendasar sebagai gantinya. Rekam seluruh jendela, atau ikuti alur kerja overlay cuplikan layar untuk diam popup. Dilacak di #646.

Untuk dokumentasi lengkap, lihat docs/ui-automation.md.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-03

Dokumentasi dan Penggunaan CLI

Penyelesaian Shell

inisialisasi

baru

memulihkan

perbarui

paket

Mengemas proyek secara langsung

Paket identitas jarang

Penemuan komponen WinRT

Bundel multi-arsitektur

create-debug-identity

identitas tersemat

Mewujudkan

pembuatan manifest

Tempat penampung manifes

add-alias manifes

aset pembaruan manifes

eksekusi

mode Project (proyek SDK .NET)

Mode file tunggal (.NET aplikasi berbasis file)

Capabilities

Bawa manifes Anda sendiri

Berjalan dengan dotnet run

batalkan pendaftaran

cert

menghasilkan sertifikat

info sertifikasi

instalasi sertifikat

tanda

az-sign

create-external-catalog

perangkat

simpan

Dapatkan Jalur Aplikasi Windows

sasaran

target exec

pendorongan target dan penarikan target

rekam jepret target

cuplikan layar target

catatan target

find-ui

find-api

node generate-bindings

node membuat-addon

node add-electron-debug-identity

node clear-electron-debug-identity

Opsi Global

Direktori Singgahan Global

Perbarui Pemeriksaan

Identitas alur kerja UI

ui

catatan ui

Saran dan Komentar

Sumber Daya Tambahan:

Berjalan dengan `dotnet run`