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.

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.

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