Debug pengecualian dalam aplikasi .NET menggunakan Snapshot Debugger

  • Artikel

Dengan Snapshot Debugger, Anda dapat secara otomatis mengumpulkan rekam jepret debug saat pengecualian terjadi di aplikasi .NET langsung Anda. Rekam jepret debug yang dikumpulkan menunjukkan status kode sumber dan variabel saat pengecualian dilemparkan.

Snapshot Debugger di Application Insights:

  • Memantau log yang dihasilkan sistem dari aplikasi web Anda.
  • Mengumpulkan snapshot pada pengecualian yang dilemparkan teratas Anda.
  • Menyediakan informasi yang Anda butuhkan untuk mendiagnosis masalah dalam produksi.

Pelajari selengkapnya tentang proses Snapshot Debugger dan Snapshot Uploader.

Aplikasi dan lingkungan yang didukung

Bagian ini mencantumkan aplikasi dan lingkungan yang didukung.

Aplikasi

Kumpulan snapshot tersedia untuk:

Lingkungan

Lingkungan berikut didukung:

Catatan

Aplikasi klien (misalnya, WPF, Formulir Windows, atau UWP) tidak didukung.

Prasyarat untuk menggunakan Snapshot Debugger

Paket dan konfigurasi

Izin

Cara kerja Snapshot Debugger

Snapshot Debugger diimplementasikan sebagai prosesor telemetri Application Insights. Saat aplikasi Anda berjalan, prosesor telemetri Snapshot Debugger ditambahkan ke alur log yang dihasilkan sistem aplikasi Anda.

Penting

Rekam jepret mungkin berisi data pribadi atau informasi sensitif lainnya dalam nilai variabel dan parameter. Data rekam jepret disimpan di wilayah yang sama dengan sumber daya Application Insights Anda.

Proses Snapshot Debugger

Proses Snapshot Debugger dimulai dan diakhir TrackException dengan metode . Rekam jepret proses adalah klon proses yang ditangguhkan, sehingga pengguna Anda mengalami sedikit atau tanpa gangguan.

  1. Aplikasi Anda melempar .TrackException

  2. Snapshot Debugger memantau pengecualian saat dilemparkan dengan berlangganan peristiwa AppDomain.CurrentDomain.FirstChanceException .

  3. Penghitung ditambahkan untuk ID masalah.

    • Ketika penghitung ThresholdForSnapshotting mencapai nilai , ID masalah ditambahkan ke paket koleksi.

    Catatan

    Nilai ThresholdForSnapshotting minimum default adalah 1. Dengan nilai ini, aplikasi Anda harus memicu pengecualian yang sama dua kali sebelum rekam jepret dibuat.

  4. ID masalah peristiwa pengecualian dihitung dan dibandingkan dengan ID masalah dalam rencana pengumpulan.

  5. Jika ada kecocokan antara ID masalah, rekam jepret proses yang sedang berjalan akan dibuat.

    • Snapshot diberi pengidentifikasi unik dan pengecualian dicap dengan pengidentifikasi tersebut.

    Catatan

    Tingkat pembuatan snapshot dibatasi oleh pengaturan SnapshotsPerTenMinutesLimit. Secara default, batasnya adalah satu rekam jepret setiap 10 menit.

  6. Setelah handler FirstChanceException dikembalikan, pengecualian yang dilemparkan diproses seperti biasa.

  7. Pengecualian mencapai TrackException metode lagi dan dilaporkan ke Application Insights, bersama dengan pengidentifikasi rekam jepret.

Catatan

Atur IsEnabledInDeveloperMode ke true jika Anda ingin membuat rekam jepret saat Anda men-debug di Visual Studio.

Proses Pengunggah Rekam Jepret

Meskipun proses Snapshot Debugger terus berjalan dan melayani lalu lintas kepada pengguna dengan sedikit gangguan, rekam jepret diserahkan ke proses Snapshot Uploader. Pengunggah Rekam Jepret:

  1. Membuat minidump.

  2. Mengunggah minidump ke Application Insights, bersama dengan file simbol (.pdb) yang relevan.

Catatan

Tidak lebih dari 50 rekam jepret per hari dapat diunggah.

Jika Anda mengaktifkan Snapshot Debugger tetapi tidak melihat rekam jepret, lihat panduan Pemecahan Masalah.

Pembatasan

Bagian ini membahas batasan untuk Snapshot Debugger.

  • Retensi data

    Snapshot debug disimpan selama 15 hari. Kebijakan retensi data default ini ditetapkan per aplikasi. Jika Anda perlu meningkatkan nilai ini, Anda dapat meminta peningkatan dengan membuka kasus dukungan di portal Microsoft Azure. Untuk setiap instans Application Insights, jumlah maksimum yang diizinkan adalah 50 salinan bayangan per hari.

  • Terbitkan simbol

    Snapshot Debugger memerlukan file simbol di server produksi untuk:

    • Dekode variabel
    • Memberikan pengalaman penelusuran kesalahan di Visual Studio

    Secara default, Visual Studio 2017 versi 15.2+ menerbitkan simbol untuk build rilis saat diterbitkan ke App Service.

    Dalam versi sebelumnya, Anda harus menambahkan baris berikut ke file profil .pubxml publikasi Anda sehingga simbol diterbitkan dalam mode rilis:

         <ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>

    Untuk Azure Compute dan jenis lainnya, pastikan bahwa file simbol adalah:

    • Di folder aplikasi .dll utama yang sama (biasanya, wwwroot/bin), atau
    • Tersedia di jalur saat ini.

    Untuk informasi selengkapnya mengenai berbagai opsi simbol yang tersedia, lihat dokumentasi Visual Studio. Untuk hasil terbaik, kami sarankan Anda menggunakan Full, Portable, atau Embedded.

  • Build yang dioptimalkan

    Dalam beberapa kasus, variabel lokal tidak dapat dilihat dalam build rilis karena pengoptimalan yang diterapkan oleh pengkompilasi JIT.

    Namun, di App Service, Snapshot Debugger dapat mendeoptimasi metode pelemparan yang merupakan bagian dari rencana pengumpulannya.

    Tip

    Instal ekstensi Situs Application Insights dalam instans App Service Anda untuk mendapatkan dukungan deoptimisasi.

Langkah berikutnya

Aktifkan Application Insights Snapshot Debugger untuk aplikasi Anda:

Catatan rilis untuk Microsoft.ApplicationInsights.SnapshotCollector

Bagian ini berisi catatan rilis untuk Microsoft.ApplicationInsights.SnapshotCollector paket NuGet untuk aplikasi .NET, yang digunakan oleh Application Insights Snapshot Debugger.

Pelajari lebih lanjut tentang Application Insights Snapshot Debugger untuk aplikasi .NET.

Untuk laporan bug dan umpan balik, buka masalah di GitHub.

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, namun kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

1.4.6

Rilis titik untuk mengatasi regresi saat menggunakan aplikasi .NET 8.

Perbaikan bug

  • Pengecualian yang dilemparkan dari metode yang dihasilkan secara dinamis (misalnya pohon ekspresi yang dikompilasi) di .NET 8 tidak dilacak dengan benar. Tetap.

1.4.5

Rilis poin untuk mengatasi bug yang dilaporkan pengguna.

Perbaikan bug

  • Memperbaiki AccessViolationException saat membaca beberapa PDB.

Perubahan

  • Menambahkan ReadMe ke paket NuGet.
  • Msdia140.dll yang diperbarui.

1.4.4

Rilis poin untuk mengatasi bug yang dilaporkan pengguna.

Perbaikan bug

Perubahan

  • Pesan kegagalan pemindaian PDB yang diturunkan dari Kesalahan ke Peringatan.
  • Msdia140.dll yang diperbarui.
  • Hindari membuat koneksi layanan jika debugger dinonaktifkan melalui pengaturan ekstensi situs.

1.4.3

Rilis poin untuk mengatasi bug yang dilaporkan pengguna.

Perbaikan bug

1.4.2

Rilis poin untuk mengatasi bug yang dilaporkan pengguna.

Perbaikan bug

Memperbaiki ArgumentException: Delegasi harus berjenis yang sama.

1.4.1

Rilis poin untuk mengembalikan perubahan yang melanggar yang diperkenalkan di 1.4.0.

Perbaikan bug

Metode Tetap tidak ditemukan di WebJobs.

1.4.0

Mengatasi beberapa peningkatan dan menambahkan dukungan untuk autentikasi Microsoft Entra untuk penyerapan Application Insights.

Perubahan

  • Mengurangi ukuran paket Snapshot Collector sebesar 60% dari 10,34 MB menjadi 4,11 MB.
  • Netstandard2.0 yang ditargetkan hanya di Snapshot Collector.
  • Dependensi Application Insights SDK yang terbentur ke 2.15.0.
  • Ditambahkan kembali MinidumpWithThreadInfo saat menulis cadangan.
  • Ditambahkan CompatibilityVersion untuk meningkatkan sinkronisasi antara agen Snapshot Collector dan Snapshot Uploader pada perubahan yang melanggar.
  • Algoritma penamaan LogFile yang diubah SnapshotUploader untuk menghindari I/O file yang berlebihan di App Service.
  • Menambahkan pid, role name, dan process start time untuk mengunggah metadata blob.
  • Digunakan System.Diagnostics.Process dalam Snapshot Collector dan Snapshot Uploader.

Fitur baru

Menambahkan autentikasi Microsoft Entra ke SnapshotCollector. Untuk mempelajari selengkapnya tentang autentikasi Microsoft Entra di Application Insights, lihat Autentikasi Microsoft Entra untuk Application Insights.

1.3.7.5

Rilis poin untuk mendukung perbaikan dari 1.4.0-pre.

Perbaikan bug

Memperbaiki ObjectDisposedException saat dimatikan.

1.3.7.4

Rilis titik untuk mengatasi masalah yang ditemukan dalam menguji skenario lampiran tanpa kode App Service.

Perubahan

Target netcoreapp3.0 sekarang tergantung pada Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (sebelumnya >= 2.1.2).

1.3.7.3

Rilis poin untuk mengatasi beberapa masalah berdampak tinggi.

Perbaikan bug

  • Memperbaiki penemuan PDB di folder wwwroot/bin , yang rusak ketika kami mengubah algoritma pencarian simbol di 1.3.6.
  • Tetap berisik ExtractWasCalledMultipleTimesException dalam telemetri.

1.3.7

Perubahan

Target netcoreapp2.0SnapshotCollector tergantung pada Microsoft.ApplicationInsights.AspNetCore>= 2.1.1 (lagi). Perubahan ini mengembalikan perilaku ke cara sebelum 1.3.5. Kami mencoba meningkatkannya di 1.3.6, tetapi melanggar beberapa skenario App Service.

Fitur baru

Snapshot Collector membaca dan mengurai ConnectionString dari variabel lingkungan APPLICATIONINSIGHTS_CONNECTION_STRING atau dari TelemetryConfiguration. Terutama, ini digunakan untuk mengatur titik akhir untuk menyambungkan ke layanan Snapshot. Untuk informasi selengkapnya, lihat Dokumentasi string koneksi.

Perbaikan bug

Beralih menggunakan HttpClient untuk semua target kecuali net45 karena WebRequest gagal di beberapa lingkungan karena tidak kompatibel SecurityProtocol (memerlukan TLS 1.2).

1.3.6

Perubahan

  • SnapshotCollector sekarang tergantung pada Microsoft.ApplicationInsights>= 2.5.1 untuk semua kerangka kerja target. Persyaratan ini mungkin merupakan perubahan yang melanggar jika aplikasi Anda bergantung pada versi SDK Microsoft.ApplicationInsights yang lebih lama.
  • Menghapus dukungan untuk TLS 1.0 dan 1.1 di Snapshot Uploader.
  • Periode pemindaian PDB sekarang default-nya 24 jam, bukan 15 menit. Dapat dikonfigurasi melalui PdbRescanInterval pada SnapshotCollectorConfiguration.
  • Pemindaian PDB hanya mencari folder tingkat atas, alih-alih rekursif. Perubahan ini mungkin merupakan perubahan yang melanggar jika simbol Anda berada di subfolder folder biner.

Fitur baru

  • Rotasi log masuk SnapshotUploader untuk menghindari pengisian folder log dengan file lama.
  • Dukungan deoptimisasi (melalui ReJIT pada melampirkan) untuk aplikasi .NET Core 3.0.
  • Menambahkan simbol ke paket NuGet.
  • Atur lebih banyak metadata saat Anda mengunggah minidump.
  • Initialized Menambahkan properti ke SnapshotCollectorTelemetryProcessor. Ini adalah CancellationToken, yang dibatalkan ketika Snapshot Collector diinisialisasi dan terhubung ke titik akhir layanan.
  • Snapshot sekarang dapat diambil untuk pengecualian dalam metode yang dihasilkan secara dinamis. Contohnya adalah pohon ekspresi yang dikompilasi yang dihasilkan oleh kueri Kerangka Kerja Entitas.

Perbaikan bug

  • AmbiguousMatchException memuat Snapshot Collector karena Status Monitor.
  • GetSnapshotCollector metode ekstensi sekarang mencari semua TelemetrySinks.
  • Jangan memulai Snapshot Uploader di platform yang tidak didukung.
  • Tangani InvalidOperationException saat Anda mendeoptimasi metode dinamis (misalnya, Kerangka Kerja Entitas).

1.3.5

  • Menambahkan dukungan untuk sovereign cloud (versi lama tidak berfungsi di sovereign cloud).
  • Menambahkan Snapshot Collector menjadi lebih mudah dengan menggunakan AddSnapshotCollector(). Untuk informasi selengkapnya, lihat Mengaktifkan Snapshot Debugger untuk aplikasi .NET di Azure App Service.
  • Gunakan pengaturan FISMA MD5 untuk memverifikasi blok blob. Pengaturan ini menghindari algoritma kripto .NET MD5 default, yang tidak tersedia ketika OS diatur ke mode yang mematuhi FIPS.
  • Abaikan bingkai .NET Framework saat mendeoptimasi panggilan fungsi. Kontrol perilaku ini dengan DeoptimizeIgnoredModules pengaturan konfigurasi.
  • DeoptimizeMethodCount Menambahkan pengaturan konfigurasi yang memungkinkan deoptimasi lebih dari satu panggilan fungsi.

1.3.4

  • Kunci instrumentasi terstruktur yang diizinkan.
  • Peningkatan ketahanan Pengunggah Rekam Jepret. Lanjutkan startup meskipun log pengunggah lama tidak dapat dipindahkan.
  • Mengaktifkan kembali pelaporan lebih banyak telemetri ketika SnapshotUploader.exe segera keluar (dinonaktifkan di 1.3.3).
  • Telemetri internal yang disederhanakan.
  • Fitur eksperimental: Paket pengumpulan Snappoint: Tambahkan snapshotOnFirstOccurence. Untuk informasi selengkapnya, lihat artikel GitHub ini.

1.3.3

Memperbaiki bug yang menyebabkan SnapshotUploader.exe berhenti merespons dan tidak mengunggah rekam jepret untuk aplikasi .NET Core.

1.3.2

  • Fitur eksperimental:Rencana pengumpulan Snappoint. Untuk informasi selengkapnya, lihat artikel GitHub ini.
  • SnapshotUploader.exe keluar ketika runtime membongkar AppDomain dari yang SnapshotCollector dimuat, alih-alih menunggu proses keluar. Tindakan ini meningkatkan keandalan kolektor saat dihosting di IIS.
  • Menambahkan konfigurasi untuk memungkinkan beberapa SnapshotCollector instans yang menggunakan kunci instrumentasi yang sama untuk berbagi proses yang sama SnapshotUploader : ShareUploaderProcess (default ke true).
  • Melaporkan lebih banyak telemetri ketika SnapshotUploader.exe segera keluar.
  • Mengurangi jumlah file dukungan SnapshotUploader.exe perlu menulis ke disk.

1.3.1

  • Dukungan yang dihapus untuk mengumpulkan rekam jepret dengan API RtlCloneUserProcess dan hanya mendukung API PssCaptureSnapshots.
  • Meningkatkan batas default pada berapa banyak rekam jepret yang dapat diambil dalam 10 menit dari satu menjadi tiga.
  • Izinkan SnapshotUploader.exe untuk menegosiasikan TLS 1.1 dan 1.2.
  • Melaporkan lebih banyak telemetri saat SnapshotUploader mencatat peringatan atau kesalahan.
  • Berhenti mengambil rekam jepret ketika layanan back-end melaporkan kuota harian tercapai (50 rekam jepret per hari).
  • Menambahkan check-in tambahan SnapshotUploader.exe untuk tidak mengizinkan dua instans berjalan dalam waktu yang sama.

1.3.0

Perubahan

  • Untuk aplikasi yang menargetkan .NET Framework, Snapshot Collector sekarang bergantung pada Microsoft.ApplicationInsights versi 2.3.0 atau yang lebih baru. Dulu 2.2.0 atau yang lebih baru. Kami percaya perubahan ini tidak akan menjadi masalah untuk sebagian besar aplikasi. Beri tahu kami jika perubahan ini mencegah Anda menggunakan Snapshot Collector terbaru.
  • Menggunakan penundaan back-off eksponensial di Snapshot Uploader saat mencoba kembali unggahan yang gagal.
  • Gunakan ServerTelemetryChannel (jika tersedia) untuk pelaporan telemetri yang lebih andal.
  • Gunakan SdkInternalOperationsMonitor pada koneksi awal ke layanan Snapshot Debugger sehingga pelacakan dependensi mengabaikannya.
  • Meningkatkan telemetri di sekitar koneksi awal ke Snapshot Debugger.
  • Laporkan lebih banyak telemetri untuk:
    • Versi App Service.
    • Instance komputasi Azure.
    • Kontainer.
    • Aplikasi Azure Functions.

Perbaikan bug

  • Saat interval atur ulang penghitung masalah diatur ke 24 hari, tafsirkan sebagai 24 jam.
  • Memperbaiki bug tempat Snapshot Uploader akan berhenti memproses rekam jepret baru jika ada pengecualian saat membuang rekam jepret.

1.2.3

Memperbaiki penandatanganan nama kuat dengan biner Snapshot Uploader.

1.2.2

Perubahan

  • File yang diperlukan untuk SnapshotUploader(64).exe sekarang disematkan sebagai sumber daya di DLL utama. Itu berarti SnapshotCollectorFiles folder tidak lagi dibuat, yang menyederhanakan build dan penyebaran dan mengurangi kekacauan dalam Penjelajah Solusi. Berhati-hatilah saat Anda meningkatkan untuk meninjau perubahan dalam file Anda .csproj . File Microsoft.ApplicationInsights.SnapshotCollector.targets ini tidak diperlukan lagi.
  • Telemetri dicatat ke sumber daya Application Insights Anda meskipun ProvideAnonymousTelemetry diatur ke false. Perubahan ini agar kita dapat menerapkan fitur pemeriksaan kesehatan di portal Azure. ProvideAnonymousTelemetry hanya memengaruhi telemetri yang dikirim ke Microsoft untuk dukungan dan peningkatan produk.
  • Saat TempFolder atau ShadowCopyFolder dialihkan ke variabel lingkungan, biarkan pengumpul tetap diam hingga variabel lingkungan tersebut diatur.
  • Untuk aplikasi yang terhubung ke internet melalui server proksi, Snapshot Collector sekarang secara otomatis memetakan pengaturan proksi apa pun dan meneruskannya ke SnapshotUploader.exe.
  • Turunkan prioritas SnapshotUploader proses (jika memungkinkan). Prioritas ini dapat ditimpa melalui IsLowPrioirtySnapshotUploader opsi .
  • GetSnapshotCollector Menambahkan metode ekstensi pada TelemetryConfiguration untuk skenario di mana Anda ingin mengonfigurasi Snapshot Collector secara terprogram.
  • Mengatur versi Application Insights SDK (bukan versi aplikasi) dalam telemetri yang menghadap pelanggan.
  • Mengirim peristiwa heartbeat pertama setelah dua menit.

Perbaikan bug

  • Diperbaiki NullReferenceException ketika pengecualian memiliki kamus Data null atau tidak dapat diubah.
  • Dalam pengunggah, coba lagi pencocokan PDB beberapa kali jika kita mendapatkan pelanggaran berbagi.
  • Memperbaiki telemetri duplikat saat lebih dari satu thread memanggil ke alur telemetri saat memulai.

1.2.1

Perubahan

  • File komentar Dokumen XML sekarang disertakan dalam paket NuGet.
  • ExcludeFromSnapshotting Menambahkan metode ekstensi untuk System.Exception skenario di mana Anda tahu Bahwa Anda memiliki pengecualian yang bising dan ingin menghindari pembuatan rekam jepret untuknya.
  • IsEnabledWhenProfiling Menambahkan properti konfigurasi yang default ke true. Ini adalah perubahan dari versi sebelumnya di mana pembuatan rekam jepret dinonaktifkan sementara jika Application Insights Profiler melakukan pengumpulan mendetail. Perilaku lama dapat dipulihkan dengan mengatur properti ini ke false.

Perbaikan bug

  • Tanda tangani SnapshotUploader64.exe dengan benar.
  • Melindungi dari inisialisasi ganda prosesor telemetri.
  • Mencegah pencatatan ganda telemetri di aplikasi dengan beberapa alur.
  • Memperbaiki bug dengan waktu kedaluwarsa paket koleksi, yang dapat mencegah rekam jepret setelah 24 jam.

1.2.0

Perubahan terbesar dalam versi ini (karenanya pindah ke nomor versi minor baru) adalah penulisan ulang dari pembuatan rekam jepret dan menangani alur. Dalam versi sebelumnya, fungsionalitas ini diimplementasikan dalam kode asli (ProductionBreakpoints.dll* dan SnapshotHolder.exe*). Implementasi baru adalah semua kode terkelola dengan P/Invokes.

Untuk versi pertama ini menggunakan alur baru, kami belum menyimpang jauh dari perilaku aslinya. Implementasi baru memungkinkan pelaporan kesalahan yang lebih baik dan menyiapkan kami untuk peningkatan di masa mendatang.

Perubahan lain dalam versi ini

  • MinidumpUploader.exe telah diganti namanya menjadi SnapshotUploader.exe (atau SnapshotUploader64.exe).
  • Menambahkan telemetri waktu ke permintaan DeOptimize/ReOptimize.
  • Menambahkan kompresi gzip untuk unggahan minidump.
  • Memperbaiki masalah di mana PDB dikunci mencegah peningkatan situs.
  • Catat nama folder asli (SnapshotCollectorFiles) saat menyalin bayangan.
  • Batas memori yang disesuaikan untuk proses 64-bit untuk mencegah situs dimulai ulang karena OOM.
  • Memperbaiki masalah di mana rekam jepret masih dikumpulkan bahkan setelah menonaktifkan.
  • Mencatat peristiwa heartbeat ke sumber daya AI pelanggan.
  • Meningkatkan kecepatan rekam jepret dengan menghapus "Sumber" dari ID masalah.

1.1.2

Perubahan

  • Telemetri penggunaan tertambah.
  • Mendeteksi dan melaporkan versi .NET dan OS.
  • Mendeteksi dan melaporkan lebih banyak lingkungan Azure (Azure Cloud Services, Azure Service Fabric).
  • Catat dan laporkan metrik pengecualian (jumlah pengecualian kesempatan pertama dan jumlah TrackException panggilan) dalam telemetri Heartbeat.

Perbaikan bug

  • Penanganan yang benar di SqlException mana pengecualian dalam (Win32Exception) tidak dilemparkan.
  • Memangkas spasi berikutnya pada folder simbol, yang menyebabkan penguraian argumen baris perintah yang salah ke MinidumpUploader.
  • Mencegah upaya ulang tak terbatas dari koneksi yang gagal ke titik akhir agen Snapshot Debugger.

1.1.0

Perubahan

  • Menambahkan perlindungan memori host. Fitur ini mengurangi dampak pada memori komputer host.
  • Meningkatkan pengalaman melihat rekam jepret portal Azure.