Debugging dengan Identitas Paket

Banyak API Windows (pemberitahuan push, tugas latar belakang, target berbagi, tugas startup, API AI Windows) mengharuskan aplikasi Anda memiliki identitas package. Selama pengembangan, Anda tidak ingin membuat penginstal MSIX penuh setiap kali Anda menguji — winapp menyediakan dua perintah untuk memberikan identitas aplikasi Anda dengan cepat.

Menggunakan Visual Studio dengan proyek pengemasan? Jika Anda sudah menggunakan Visual Studio untuk proyek yang dipaketkan, Anda mungkin tidak memerlukan winapp untuk debugging. Visual Studio sudah menangani pendaftaran paket, identitas, aktivasi AUMID, lampiran debugger, dan penelusuran kesalahan kode aktivasi — semuanya dari F5. Ini juga menawarkan Debug → Target Debug Lainnya → Debug Paket Aplikasi terinstal untuk skenario lanjutan. Alur kerja di bawah ini paling berguna untuk pengguna VS Code, alur kerja berbasis terminal, dan kerangka kerja yang tidak dipaketkan VS secara asli (Rust, Flutter, Tauri, Electron, C++ biasa).

Dua pendekatan: `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
Apa yang didaftarkannya	Paket tata letak fleksibel penuh (seluruh folder)	Paket ringan (satu file exe)
Cara aplikasi diluncurkan	Diluncurkan oleh winapp (aktivasi AUMID atau alias eksekusi)	Anda meluncurkan exe sendiri (baris perintah, IDE, dll.)
Mensimulasikan penginstalan MSIX	Ya — paling dekat dengan perilaku produksi	Tidak — hanya identitas jarang-jarang
File tetap berada di tempatnya	Disalin ke direktori tata letak AppX	Ya — exe tetap berada di jalur aslinya
Cakupan identitas	Seluruh isi folder (exe, DLL, aset)	Berkas eksekusi tunggal
Mudah bagi debugger	Lampirkan ke PID setelah peluncuran, atau gunakan `--no-launch` lalu luncurkan melalui alias	Luncurkan langsung dari debugger IDE Anda — exe memiliki identitas terlepas dari faktor lain.
Dukungan aplikasi konsol	`--with-alias` menyimpan stdin/stdout di terminal	Jalankan exe langsung di terminal
Terbaik untuk	Sebagian besar kerangka kerja (.NET, C++, Rust, Flutter, Tauri)	Electron, atau saat Anda memerlukan kontrol debugger IDE penuh (F5)

Kapan menggunakan yang mana

Standar: `winapp run`

Gunakan winapp run untuk sebagian besar alur kerja pengembangan. Ini mensimulasikan penginstalan MSIX nyata - aplikasi Anda mendapatkan identitas, kemampuan, dan asosiasi file yang sama seperti saat terpasang di lingkungan produksi.

# Build your app, then:
winapp run .\build\output

Gunakan `create-debug-identity` saat:

File exe Anda terpisah dari keluaran build Anda — misalnya, aplikasi Electron tempat electron.exe berada dalam node_modules/
Anda perlu men-debug kode startup dan tidak dapat melampirkan debugger cukup cepat setelah peluncuran AUMID
Pada beberapa debugger di mana Anda tidak dapat meluncurkan dengan AUMID dan memerlukan identitas pada proses yang diluncurkan — create-debug-identity mendaftarkan exe sehingga memiliki identitas tanpa memedulikan bagaimana proses tersebut dimulai
Anda sedang menguji perilaku sparse package, khususnya (AllowExternalContent, TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Skenario debug

Skenario A: Cukup gunakan dengan identitas

Alur kerja paling sederhana — bangun, jalankan dengan identitas, selesai.

winapp run .\build\Debug

Winapp mendaftarkan folder sebagai paket tata letak yang longgar dan meluncurkan aplikasi. API yang memerlukan identitas segera berfungsi. Ini mencakup sebagian besar skenario pengembangan dan pengujian.

Untuk aplikasi konsol yang memerlukan stdin/stdout di terminal saat ini, tambahkan --with-alias:

winapp run .\build\Debug --with-alias

Skenario B: Melampirkan debugger ke aplikasi yang sedang berjalan

Luncurkan dengan winapp run, perhatikan PID, lalu lampirkan debugger IDE Anda.

winapp run .\build\Debug
# Output: Process ID: 12345

Kemudian di IDE Anda:

Visual Studio Code: Jalankan dan Debug → pilih konfigurasi "Lampirkan" (lihat penyiapan IDE di bawah)
WinDbg: windbg -p 12345

Batasan: Anda akan melewatkan kode apa pun yang berjalan sebelum melampirkan. Untuk debug startup, gunakan Skenario D (create-debug-identity).

Skenario C: Daftarkan identitas, lalu luncurkan melalui AUMID atau alias dari IDE Anda

Gunakan --no-launch untuk mendaftarkan paket, lalu luncurkan aplikasi melalui AUMID-nya (dilaporkan oleh run) atau alias eksekusi dari IDE Anda.

Langkah 1: Daftarkan paket tanpa meluncurkan:

winapp run .\build\Debug --no-launch

Langkah 2: Konfigurasikan IDE Anda untuk diluncurkan melalui AUMID atau alias eksekusi (bukan eksekusi secara langsung).

Meluncurkan dengan AUMID: Gunakan perintah start shell:AppsFolder\<AUMID>. winapp run menghasilkan AUMID saat aplikasi didaftarkan.
Peluncuran dengan alias: Alias harus didefinisikan dalam manifes Anda (Package.appxmanifest lebih disukai, appxmanifest.xml juga didukung).

Penting: Menjalankan exe di folder build saja tidak akan memberikannya identitas. Aplikasi harus dimulai melalui aktivasi AUMID atau alias eksekusinya. Ini adalah cara kerja paket tata letak yang longgar - identitas terkait dengan jalur aktivasi, bukan file exe.

Skenario D: Luncurkan melalui IDE Anda dengan identitas (debugging saat startup)

Ini adalah pendekatan terbaik untuk men-debug kode startup dengan kontrol IDE penuh - debugger IDE Anda mengontrol proses dari instruksi pertama, dan exe memiliki identitas tidak peduli bagaimana hal itu diluncurkan.

winapp create-debug-identity .\build\Debug\myapp.exe

Sekarang luncurkan exe dengan cara apa pun yang Anda suka - dari terminal, dari Vs Code F5, dari skrip. Exe memiliki identitas karena Windows mendaftarkan paket sparse yang menunjuk langsung ke executable tersebut.

Perbedaannya dengan winapp run: Dengan create-debug-identity, identitas terikat dengan exe itu sendiri (melalui Add-AppxPackage -ExternalLocation). Dengan winapp run, identitas terkait dengan paket tata letak fleksibel — aplikasi harus diluncurkan melalui AUMID atau alias. Ini membuat create-debug-identity pilihan yang lebih baik ketika Anda membutuhkan IDE Anda untuk meluncurkan dan men-debug exe secara langsung.

Ini juga merupakan pendekatan terbaik untuk aplikasi Electron di mana jalur exe berbeda dari direktori sumber Anda.

Skenario E: Menangkap output debug dan diagnostik kerusakan

Tangkap pesan OutputDebugString dan pengecualian pencobaan pertama secara langsung. Kebisingan kerangka kerja (WinUI, COM, jejak internal DirectX) difilter dari konsol sehingga hanya pesan debug aplikasi Anda yang muncul. Semuanya masih ditulis ke file log untuk penyelidikan penuh.

Jika aplikasi mengalami crash, minidump diambil dan dianalisis secara otomatis:

winapp run .\build\Debug --debug-output

Ketika terjadi crash, output mencakup jenis pengecualian, pesan, dan jejak tumpukan dengan file sumber dan nomor baris (diselesaikan dari PDB di folder output build Anda). Crash terkelola (.NET) dianalisis secara instan tanpa alat eksternal. Crash Native (C++/WinRT) menunjukkan nama modul dan offset; tambahkan --symbols untuk mengunduh simbol PDB agar mendapatkan nama fungsi lengkap.

winapp run .\build\Debug --debug-output --symbols

Penting: Ini mengaitkan winapp sebagai debugger. Windows hanya mengizinkan satu debugger per proses, jadi Anda tidak dapat juga menggunakan Visual Studio, VS Code, atau WinDbg.

Triase pengecualian yang disematkan WinUI

Kebanyakan kegagalan WinUI dimulai di dalam penangan peristiwa XAML dan muncul sebagai pengecualian tersimpan (0xC000027B) yang kemudian dimunculkan kembali oleh dispatcher, sehingga stack trace normal tidak lagi mengarah ke penyebab yang sebenarnya. Ketika aplikasi yang crash dimuat Microsoft.UI.Xaml.dll, winapp secara otomatis menjalankan langkah triase tambahan yang mendekode stowed exception dan rantai dispatch XAML native (Microsoft.UI.Xaml → CXcpDispatcher → CoreMessagingXP → CLR host). Hasilnya ditambahkan ke log debug. Tidak perlu flag — fitur ini diaktifkan secara otomatis untuk dump WinUI. Tambahkan --symbols untuk nama fungsi yang sudah sepenuhnya diresolusikan dalam rantai dispatch.

Agar ini berfungsi, winapp menangkap crash dump beserta rekaman stowed exception yang mengakhiri proses (dan parameternya, yang menunjuk ke array stowed exception) sambil mempertahankan konteks thread first-chance, sehingga analisis terkelola standar tetap dapat memulihkan frame pengguna asli Anda and langkah triase dapat menemukan stowed exception tersebut.

Tahap ini menjalankan DbgEng dengan ekstensi JavaScript WinDbg milik tim WinUI. Mesin debug native (dbgeng.dll dan sejenisnya) berasal dari NuGet, dan JsProvider.dll — host skrip JavaScript, yang tidak ada di NuGet — diambil saat pertama kali digunakan langsung dari unduhan resmi WinDbg (hanya beberapa ratus kilobyte yang diperlukan yang dibaca, bukan seluruh paket). Karena JsProvider.dll harus memiliki build yang sama dengan engine — memuat penyedia yang build-nya tidak cocok akan membuat debugger crash saat startup — JsProvider.dll dipatok ke bundel WinDbg tertentu yang build-nya cocok dengan engine NuGet (bukan rilis saat ini yang terus berubah), dan setelah diperoleh, kedua build tersebut dibandingkan: jika tidak cocok, pasangan tersebut ditolak dan triase tidak dilakukan dengan alasan yang jelas, alih-alih membuat debugger crash tanpa pemberitahuan yang jelas. Paket debugger dikunci ke versi tertentu dan, sebelum DLL native apa pun diekstrak dan dimuat, diverifikasi menggunakan hash konten SHA-512 yang tertanam dalam hasil kompilasi (dan ekstensinya diverifikasi terhadap hash yang dipatok); JsProvider.dll juga wajib memiliki tanda tangan Microsoft Authenticode yang valid, yang diperiksa dengan pemeriksaan pencabutan penuh pada seluruh rantai sertifikat (beralih ke pemeriksaan tanda tangan saja saat data pencabutan tidak dapat diakses ketika offline, tetapi selalu menolak sertifikat yang telah dicabut). Unduhan dipentaskan ke file sementara, diverifikasi, lalu diterbitkan secara atomik ke dalam cache, sehingga eksekusi bersamaan tidak pernah mengamati DLL yang ditulis sebagian atau belum diverifikasi. Pada setiap eksekusi, biner yang disimpan dalam cache diperiksa ulang (kecocokan antara tanda tangan JsProvider.dll dan build engine-nya, serta DLL engine untuk memastikan citra PE yang valid), sehingga cache yang terpotong atau menyimpang dapat memulihkan dirinya sendiri dengan mengakuisisi ulang, alih-alih gagal pada setiap eksekusi. Secara keseluruhan, ini berarti feed hasil pencerminan atau yang telah disusupi tidak dapat menggantikan biner dengan versi yang telah diubah — setiap kegagalan akan melewati triase alih-alih memuat kode yang tidak terverifikasi. Semua disimpan dalam cache di dalam direktori global winapp, sehingga eksekusi selanjutnya dapat dilakukan secara offline. Jika lingkungan Anda memblokir unduhan tersebut, instal Alat Debugging untuk Windows (melalui SDK Windows) atau atur WINAPP_DBGTOOLS_DIR variabel lingkungan ke direktori debugger yang sudah berisi dbgeng.dll dan JsProvider.dll. Ketika WINAPP_DBGTOOLS_DIR diatur, pengaturan tersebut menjadi acuan utama — hanya direktori itu yang dirujuk — jadi, jika tidak lengkap, log akan menyebutkan secara spesifik komponen yang hilang (dbgeng.dll dan/atau JsProvider.dll), alih-alih menyarankan Anda menyetel variabel yang sudah disetel. Ketika triase berhasil, konsol menampilkan kesimpulan singkat dalam satu baris (kode kesalahan/pesan dari pengecualian tersimpan); ketika biner tidak dapat diperoleh, proses triase dilewati (analisis managed/native standar tetap berjalan), konsol akan menyatakannya, dan log menjelaskan alasannya.

Lolos triase berjalan dalam proses anak berumur pendek. Ini diperlukan: proses utama winapp memuat sistem dbghelp.dll saat menangkap dan menganalisis dump, dan mesin modern dbgeng.dll tidak dapat terhubung ke salinan lama yang sudah dimuat di memori — proses baru memberi mesin keadaan pemuat yang bersih. Mendekode struktur pengecualian yang disimpan juga memerlukan simbol sistem operasi (combase.dll), yang diunduh --symbols dari server simbol publik Microsoft; pada build yang simbolnya tidak dipublikasikan di sana, tahap triase masih dapat mengidentifikasi pengecualian yang disimpan tersebut, tetapi tidak dapat menguraikannya sepenuhnya.

Penyiapan IDE

Visual Studio Code

Ekstensi WinApp VS Code menyediakan jenis debug kustomwinapp yang meluncurkan aplikasi Anda dengan identitas paket dan melampirkan debugger - semuanya dari satu tekan F5. Instal melalui Visual Studio Marketplace; kode sumber dan pelacak isunya berada di repositori microsoft/WinAppVSCE.

Debugging F5 sekali tekan dengan identitas

Tambahkan konfigurasi peluncuran winapp ke .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

Saat Anda menekan F5:

Ekstensi memindai ruang kerja Anda untuk membuat direktori output yang berisi .exe file.
Anda memilih folder build untuk dijalankan (atau mengatur inputFolder untuk melewati prompt).
Ini meluncurkan aplikasi Anda melalui winapp run untuk memberikannya identitas paket.
Sesi debug anak dilampirkan ke proses yang sedang berjalan menggunakan debugger yang Anda tentukan.

Setelah debugger terpasang, Anda mendapatkan pengalaman penelusuran kesalahan Visual Studio Code lengkap — atur titik henti dengan mengklik selokan, menelusuri baris demi baris kode (), melangkah ke fungsi (F10F11), memeriksa variabel di panel Variabel, dan mengevaluasi ekspresi di Konsol Debug. Aplikasi ini berjalan dengan identitas paket sepenuhnya, sehingga API yang bergantung pada identitas berperilaku persis seperti di lingkungan produksi.

Penting: Jenis winapp debug tidak membangun proyek Anda secara otomatis. Setelah membuat perubahan kode, kompilasi ulang sebelum menekan F5.

Mengotomatiskan build dengan `preLaunchTask`

Untuk menghindari lupa membangun kembali, tambahkan preLaunchTask yang akan membangun proyek Anda sebelum setiap sesi debug.

Tentukan tugas build di .vscode/tasks.json (misalnya untuk .NET):

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

Rujuk pada launch.json:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Pengaturan konfigurasi

Harta benda	Tipe	Default	Deskripsi
`inputFolder`	string		Jalur ke folder output build yang berisi biner aplikasi Anda (misalnya, `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Jika tidak diatur, Anda akan diminta untuk memilih folder.
`manifest`	string		Jalur ke file manifes AppX (misalnya, `AppxManifest.xml`, , `Package.appxmanifest`atau `appxmanifest.xml`). Jika tidak diatur, CLI mendeteksi secara otomatis dari folder input atau direktori saat ini.
`debuggerType`	string	`coreclr`	Debugger dasar yang akan digunakan (`coreclr`, `cppvsdbg`, atau `node`).
`workingDirectory`	string	folder ruang kerja	Direktori kerja untuk aplikasi.
`args`	string		Argumen baris perintah yang diteruskan ke aplikasi.
`outputAppxDirectory`	string		Direktori output untuk paket tata letak longgar. Secara default ke `AppX` folder di dalam folder input.
`port`	number	`9229`	(`node` hanya) Port yang digunakan untuk pendengar untuk Node.js `--inspect` dan koneksi lampiran. Ambil alih ketika port default sudah digunakan.

Debugger yang didukung

`debuggerType`	Bahasa	Ekstensi yang Diperlukan
`coreclr` (standar)	C# / .NET	C# Dev Kit
`cppvsdbg`	C / C++	C/C++
`node`	Node.js / Elektron	Bawaan

Contoh untuk proyek C++:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Penelusuran kesalahan startup dengan Buat Identitas Debug

Jika Anda perlu men-debug kode startup dari instruksi pertama, pendekatan lampiran F5 mungkin kehilangan kode awal. Sebagai gantinya, gunakan perintah WinApp: Buat Identitas Debug dari Palet Perintah (Ctrl+Shift+P) untuk mendaftarkan paket jarang untuk executable Anda, lalu luncurkan dengan debugger standar Anda:

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Karena create-debug-identity mendaftarkan identitas pada exe itu sendiri, aplikasi memiliki identitas tidak peduli bagaimana hal itu diluncurkan - termasuk dari konfigurasi peluncuran Visual Studio Code standar.

Melampirkan ke proses yang sedang berjalan

Jika Anda lebih suka meluncurkan dari winapp run terminal lalu melampirkan, gunakan konfigurasi lampirkan standar:

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Untuk C++/Rust, gunakan "type": "cppvsdbg" (MSVC) atau "type": "lldb" (LLDB):

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Pembersihan

Setelah selesai menguji, jalankan WinApp: Unregister Package dari Palet Perintah untuk menghapus paket pengembangan yang sideload tanpa meninggalkan VS Code.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-24