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 saat ini)
  • --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

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

Deteksi 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)

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

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.

memulihkan

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

winapp restore [options]

Opsi:

  • --config-dir <path> - Direktori yang berisi winapp.yaml (default: direktori saat ini)

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 yang diinisialisasi dengan winapp init, tidak ada winapp.yaml. Gunakan dotnet restore untuk memulihkan paket NuGet sebagai gantinya.

Contoh: 

# Restore from winapp.yaml in current directory
winapp restore

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 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)

winapp pack <input-folder> [options]

Argumen:

  • input-folder - Direktori yang berisi file aplikasi ke paket

Opsi:

  • --output <filename> - Nama file MSIX output (default: <name>_<version>_<arch>.msix, jatuh kembali ke <name>_<version>.msix, , <name>_<arch>.msixatau <name>.msix ketika versi/lengkungan tidak dapat ditentukan)
  • --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
  • --install-cert - Menginstal sertifikat ke komputer
  • --publisher <name> - nama Publisher untuk pembuatan sertifikat
  • --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.

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 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

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 :

  1. Jika --executable disediakan (jalur relatif terhadap folder input), tempat penampung diganti dengan nilai yang ditentukan
  2. Jika tidak, winapp pack memindai akar folder input untuk .exe file — jika tepat satu ditemukan, itu digunakan secara otomatis
  3. 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

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

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> - CN Publisher (default: CN=<current user>)
  • --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:

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.

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.

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-folder> [options]

Argumen:

  • input-folder - Direktori yang berisi aplikasi yang akan dijalankan (diperlukan)

Opsi:

  • --manifest <path> - Jalur ke Package.appxmanifest (default: deteksi otomatis dari folder input atau direktori saat ini)
  • --output-appx-directory <path> - Direktori output untuk paket tata letak longgar (default: AppX di dalam direktori folder input)
  • --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. uap5:ExecutionAlias Memerlukan dalam manifes (gunakan winapp manifest add-alias untuk menambahkannya). Tidak dapat digabungkan dengan --no-launch. Tidak dapat digabungkan dengan --json.
  • --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. 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. 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. Mencetak PID ke stdout (atau di JSON dengan --json). 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.

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

Properti MSBuild (paket NuGet):

Saat menggunakan paket NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run secara otomatis memanggil winapp run. 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 false Luncurkan melalui alias eksekusi alih-alih aktivasi AUMID
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. 
<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 [options]

Opsi:

  • --manifest <path> - Jalur ke Package.appxmanifest (default: deteksi otomatis dari direktori saat ini)
  • --force - Lewati pemeriksaan direktori lokasi penginstalan dan batalkan pendaftaran meskipun paket terdaftar dari pohon proyek yang berbeda
  • --json - Format output sebagai JSON

Apa fungsinya:

  • Membaca nama paket dari 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 lokasi penginstalan paket berada di bawah pohon direktori saat ini (kecuali --force)
  • Membatalkan pendaftaran paket yang cocok

Contoh: 

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

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

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

# 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> - Mengekstrak informasi penerbit dari Package.appxmanifest
  • --publisher <name> - nama Publisher untuk sertifikat
  • --output <path> - Jalur file sertifikat output (mendukung jalur absolut dan relatif)
  • --password <password> - Kata sandi sertifikat (default: "kata sandi")
  • --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": "..."}).

info sertifikasi

Tampilkan detail sertifikat dari file PFX. 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)

Opsi:

  • --password <password> - Kata sandi untuk file PFX (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> [options]

Argumen:

  • file-path - Jalur ke paket MSIX atau dapat dieksekusi untuk ditandatangani

Opsi:

  • --cert <path> - Jalur ke sertifikat penandatanganan
  • --cert-password <password> - Kata sandi sertifikat (default: "kata sandi")

Contoh: 

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

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 kemasan lokasi sparse/eksternalAppxMetadata\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:

  1. winapp manifest generate --template sparse — Membuat manifes jarang dengan AllowExternalContent
  2. winapp create-external-catalog ./bin — Hasilkan katalog integritas kode untuk executable aplikasi Anda
  3. 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

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

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.

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 (dialog pengambilan otomatis secara terpisah)
  • invoke - Aktifkan elemen (klik, alihkan, perluas)
  • click - Klik elemen melalui simulasi mouse (untuk kontrol yang tidak mendukung pemanggilan)
  • set-value - Tetapkan nilai pada elemen yang dapat diedit (teks, angka)
  • 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

Opsi:

  • -a, --app <app> - Aplikasi target (nama, judul, atau PID)
  • -w, --window <hwnd> - Jendela target menurut HWND (stabil)

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

  • Last updated on