Men-debug aplikasi ASP.NET Core

Artikel ini menjelaskan cara men-debug Blazor aplikasi, termasuk men-debug Blazor WebAssembly aplikasi dengan alat pengembang browser atau lingkungan pengembangan terintegrasi (IDE).

Blazor Web Apps dapat di-debug di Visual Studio atau Visual Studio Code.

Blazor WebAssembly aplikasi dapat di-debug:

• Di Visual Studio atau Visual Studio Code.
• Menggunakan alat pengembang browser di browser berbasis Chromium, termasuk Microsoft Edge, Google Chrome, dan Firefox.

Skenario yang tersedia untuk Blazor WebAssembly penelusuran kesalahan meliputi:

• Atur dan hapus titik henti.
• Jalankan aplikasi dengan dukungan penelusuran kesalahan di IDEs.
• Satu langkah melalui kode.
• Lanjutkan eksekusi kode dengan pintasan keyboard di IDEs.
• Di jendela Lokal , amati nilai variabel lokal.
• Lihat tumpukan panggilan, termasuk rantai panggilan antara JavaScript dan .NET.
• Gunakan server simbol untuk penelusuran kesalahan, dikonfigurasi oleh preferensi Visual Studio.

Skenario yang tidak didukung meliputi:

• Debug dalam skenario non-lokal (misalnya, Subsistem Windows untuk Linux (WSL) atau Visual Studio Codespaces).
• Debug di Firefox dari Visual Studio atau Visual Studio Code.

Prasyarat

Bagian ini menjelaskan prasyarat untuk penelusuran kesalahan.

Prasyarat browser

Versi terbaru browser berikut:

• Google Chrome
• Microsoft Edge
• Firefox (hanya alat pengembang browser)

Pastikan firewall atau proksi tidak memblokir komunikasi dengan proksi debug (NodeJS proses). Untuk informasi selengkapnya, lihat bagian Konfigurasi firewall.

Catatan

Apple Safari di macOS saat ini tidak didukung.

Prasyarat IDE

Versi terbaru Visual Studio atau Visual Studio Code diperlukan.

Prasyarat Visual Studio Code

Visual Studio Code memerlukan C# Dev Kit untuk Visual Studio Code (Memulai C# di VISUAL Code). Di Marketplace Ekstensi Visual Studio Code, filter daftar ekstensi dengan "c# dev kit" untuk menemukan ekstensi:

Menginstal C# Dev Kit secara otomatis menginstal ekstensi tambahan berikut:

• Alat Penginstalan .NET
• C#
• IntelliCode untuk C# Dev Kit

Jika Anda mengalami peringatan atau kesalahan, Anda dapat membuka masalah (microsoft/vscode-dotnettools repositori GitHub) yang menjelaskan masalah tersebut.

Prasyarat konfigurasi aplikasi

Panduan dalam sub bagian ini berlaku untuk penelusuran kesalahan sisi klien.

Properties/launchSettings.json Buka file proyek startup. Konfirmasikan keberadaan properti berikut inspectUri di setiap profil peluncuran simpul profiles file. Jika properti berikut tidak ada, tambahkan ke setiap profil:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

Properti inspectUri :

• Memungkinkan IDE mendeteksi bahwa aplikasi adalah aplikasi Blazor .
• Menginstruksikan infrastruktur penelusuran kesalahan skrip untuk terhubung ke browser melalui Blazorproksi debugging.

Nilai tempat penampung untuk protokol WebSocket (wsProtocol), host (url.hostname), port (url.port), dan URI inspektur pada browser yang diluncurkan (browserInspectUri) disediakan oleh kerangka kerja.

Paket

Blazor Web Apps: Microsoft.AspNetCore.Components.WebAssembly.Server: Mereferensikan paket internal (Microsoft.NETCore.BrowserDebugHost.Transport) untuk rakitan yang berbagi host debug browser.

Blazor WebAssemblyMandiri : Microsoft.AspNetCore.Components.WebAssembly.DevServer: Server pengembangan untuk digunakan saat membangun Blazor aplikasi. WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging Memanggil secara internal untuk menambahkan middleware untuk men-debug Blazor WebAssembly aplikasi di dalam alat pengembang Chromium.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Men-debug Blazor Aplikasi Web dalam IDE

Visual Studio

Contoh di bagian ini mengasumsikan bahwa Anda telah membuat Blazor Aplikasi Web dengan mode render interaktif Auto (Server dan WebAssembly) dan lokasi interaktivitas per komponen.

1. Buka aplikasi.
2. Atur currentCount++; titik henti pada baris dalam Counter komponen (Pages/Counter.razor) proyek klien (.Client).
3. Tekan F5 untuk menjalankan aplikasi di debugger.
4. Di browser, navigasikan ke Counter halaman di /counter. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.
5. Di Visual Studio, periksa nilai currentCount bidang di jendela Lokal .
6. Tekan F5 untuk melanjutkan eksekusi.

Titik henti juga dapat ditemui dalam proyek server dalam komponen sisi server yang dirender secara statis dan interaktif.

1. Hentikan debugger.

2. Tambahkan komponen berikut ke aplikasi server. Komponen menerapkan mode render Server Interaktif (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Atur titik henti currentCount++; pada baris dalam Counter2 komponen.

4. Tekan F5 untuk menjalankan aplikasi di debugger.

5. Di browser, navigasikan ke Counter2 halaman di /counter-2. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.

6. Tekan F5 untuk melanjutkan eksekusi.

Titik henti tidak terpukul selama pengaktifan aplikasi sebelum proksi debug berjalan. Ini termasuk titik henti dalam Program file dan titik henti dalam OnInitialized{Async} metode siklus hidup komponen yang dimuat oleh halaman pertama yang diminta dari aplikasi.

Visual Studio Code

Contoh di bagian ini mengasumsikan bahwa Anda telah membuat Blazor Aplikasi Web dengan mode render Auto interaktif (Server dan WebAssembly) dan lokasi interaktivitas per komponen.

1. Buka aplikasi di Visual Studio Code dengan membuka folder solusi, yang merupakan folder yang berisi folder server dan .Client proyek.
2. Atur currentCount++; titik henti pada baris dalam Counter komponen (Pages/Counter.razor) proyek klien (.Client).
3. Buka panel Jalankan dan Debug dan pilih tombol Jalankan dan Debug . Atau, tekan F5 (Mulai Penelusuran Kesalahan). Pilih C# debugger di palet perintah di bagian atas UI. Pilih profil default untuk proyek server (misalnya, C#:BlazorSample [Default Configuration]).
4. Di browser, navigasikan ke Counter halaman di /counter. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.
5. Pilih tombol Lanjutkan di UI atau tekan F5 (Lanjutkan) untuk melanjutkan eksekusi.

Titik henti juga dapat ditemui dalam proyek server.

1. Hentikan penelusuran kesalahan dengan memilih tombol Hentikan atau tekan Shift+F5 pada keyboard.

2. Tambahkan komponen berikut ke aplikasi server. Komponen mengadopsi mode render Server Interaktif (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Atur titik henti currentCount++; pada baris dalam Counter2 komponen.

4. Pilih tombol Mulai Penelusuran Kesalahan di UI atau tekan F5 (Mulai Debugging) untuk menjalankan aplikasi di debugger.

5. Di browser, navigasikan ke Counter2 halaman di /counter-2. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.

6. Pilih tombol Lanjutkan di UI atau tekan F5 (Lanjutkan) untuk melanjutkan eksekusi.

Titik henti tidak terpukul selama pengaktifan aplikasi sebelum proksi debug berjalan. Ini termasuk titik henti dalam Program file dan titik henti dalam OnInitialized{Async} metode siklus hidup komponen yang dimuat oleh halaman pertama yang diminta dari aplikasi.

Mulai Tanpa Debugging [Ctrl+F5 (Windows) atau ⌘+F5 (macOS)] tidak didukung. Saat aplikasi dijalankan dalam konfigurasi Debug, debugging overhead selalu menghasilkan pengurangan performa kecil.

Men-debug Blazor WebAssembly aplikasi di IDE

Visual Studio

1. Buka aplikasi.
2. Atur currentCount++; titik henti pada baris dalam Counter komponen (Pages/Counter.razor).
3. Tekan F5 untuk menjalankan aplikasi di debugger.
4. Di browser, navigasikan ke Counter halaman di /counter. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.
5. Di Visual Studio, periksa nilai currentCount bidang di jendela Lokal .
6. Tekan F5 untuk melanjutkan eksekusi.

Titik henti tidak terpukul selama pengaktifan aplikasi sebelum proksi debug berjalan. Ini termasuk titik henti dalam Program file dan titik henti dalam OnInitialized{Async} metode siklus hidup komponen yang dimuat oleh halaman pertama yang diminta dari aplikasi.

Visual Studio Code

1. Buka folder aplikasi di Visual Studio Code.
2. Atur currentCount++; titik henti pada baris dalam Counter komponen (Pages/Counter.razor).
3. Buka panel Jalankan dan Debug dan pilih tombol Jalankan dan Debug . Atau, tekan F5 (Mulai Penelusuran Kesalahan). Pilih C# debugger di palet perintah di bagian atas UI. Pilih profil default (misalnya, C#:BlazorSample [Default Configuration]).
4. Tekan F5 untuk menjalankan aplikasi di debugger.
5. Aplikasi mandiri diluncurkan, dan browser penelusuran kesalahan dibuka.
6. Di browser, navigasikan ke Counter halaman di /counter. Tunggu beberapa detik agar proksi debug dimuat dan dijalankan. Pilih tombol Klik saya untuk menekan titik henti.
7. Tekan F5 untuk melanjutkan eksekusi.

Titik henti tidak terpukul selama pengaktifan aplikasi sebelum proksi debug berjalan. Ini termasuk titik henti dalam Program file dan titik henti dalam OnInitialized{Async} metode siklus hidup komponen yang dimuat oleh halaman pertama yang diminta dari aplikasi.

Mulai Tanpa Debugging [Ctrl+F5 (Windows) atau ⌘+F5 (macOS)] tidak didukung. Saat aplikasi dijalankan dalam konfigurasi Debug, debugging overhead selalu menghasilkan pengurangan performa kecil.

Dukungan debugger

Penelusuran kesalahan diaktifkan untuk runtime saat dukungan debugger diaktifkan dengan <DebuggerSupport>{VALUE}</DebuggerSupport>, di mana {VALUE} tempat penampung berada true atau false.

Secara default, Blazor kerangka kerja menonaktifkan dukungan debugger untuk semua konfigurasi non-Debug. Untuk mengaktifkan dukungan debugger untuk konfigurasi non-Debug, tambahkan <DebuggerSupport> properti ke file proyek aplikasi.

Dalam contoh berikut, dukungan debugger diaktifkan untuk konfigurasi "DebugCustom" kustom:

<DebuggerSupport Condition="'$(Configuration)' == 'DebugCustom'">true</DebuggerSupport>

Untuk informasi selengkapnya, lihat Blazor WebAssembly konfigurasi debugger kustom (dotnet/runtime #96239).

Lampirkan ke sesi penelusuran kesalahan Visual Studio Code yang sudah ada

Untuk melampirkan ke aplikasi yang sedang berjalan Blazor , buka .vscode/launch.json file dan ganti {URL} tempat penampung dengan URL tempat aplikasi berjalan:

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Opsi peluncuran Visual Studio Code

Opsi konfigurasi peluncuran dalam tabel berikut didukung untuk blazorwasm jenis debug (.vscode/launch.json).

Opsi	Deskripsi
browser	Browser yang akan diluncurkan untuk sesi penelusuran kesalahan. Atur ke edge atau chrome. Default ke edge.
cwd	Direktori kerja untuk meluncurkan aplikasi di bawah.
request	Gunakan launch untuk meluncurkan dan melampirkan sesi penelusuran kesalahan ke Blazor WebAssembly aplikasi atau attach untuk melampirkan sesi penelusuran kesalahan ke aplikasi yang sudah berjalan.
timeout	Jumlah milidetik untuk menunggu sesi debugging dilampirkan. Default ke 30.000 milidetik (30 detik).
trace	Digunakan untuk menghasilkan log dari JS debugger. Atur ke true untuk menghasilkan log.
url	URL yang akan dibuka di browser saat men-debug.
webRoot	Menentukan jalur absolut server web. Harus diatur jika aplikasi dilayani dari sub-rute.

Debug Blazor WebAssembly dengan Google Chrome atau Microsoft Edge

Panduan di bagian ini menerapkan aplikasi penelusuran kesalahan Blazor WebAssembly di:

• Google Chrome berjalan di Windows atau macOS.
• Microsoft Edge berjalan di Windows.

1. Jalankan aplikasi di shell perintah dengan dotnet run.

2. Luncurkan browser dan navigasikan ke URL aplikasi.

3. Mulai penelusuran kesalahan jarak jauh dengan menekan:

   • Shift+Alt+d di Windows.
   • Shift+⌘+d di macOS.

   Browser harus berjalan dengan penelusuran kesalahan jarak jauh diaktifkan, yang bukan default. Jika penelusuran kesalahan jarak jauh dinonaktifkan, halaman kesalahan tab browser yang tidak dapat di-debug dirender dengan instruksi untuk meluncurkan browser dengan port debugging terbuka. Ikuti instruksi untuk browser Anda.

   Setelah mengikuti instruksi untuk mengaktifkan penelusuran kesalahan jarak jauh, aplikasi akan terbuka di jendela browser baru. Mulai penelusuran kesalahan jarak jauh dengan menekan kombinasi HotKey di jendela browser baru:

   • Shift+Alt+d di Windows.
   • Shift+⌘+d di macOS.

   Tab browser alat pengembang jendela baru terbuka memperlihatkan gambar aplikasi yang dihantui.

   Catatan

   Jika Anda mengikuti instruksi untuk membuka tab browser baru dengan penelusuran kesalahan jarak jauh diaktifkan, Anda dapat menutup jendela browser asli, membiarkan jendela kedua terbuka dengan tab pertama yang menjalankan aplikasi dan tab kedua yang menjalankan debugger.

4. Setelah beberapa saat, tab Sumber menampilkan daftar rakitan dan halaman .NET aplikasi.

5. Buka file:// nodenya. Dalam kode komponen (.razor file) dan file kode C# (.cs), titik henti yang Anda tetapkan terpukul saat kode dijalankan di tab browser aplikasi (tab awal dibuka setelah memulai penelusuran kesalahan jarak jauh). Setelah titik henti tertembak, langkah tunggal (F10) melalui kode atau melanjutkan (F8) eksekusi kode secara normal di tab debugging.

Untuk penelusuran kesalahan browser berbasis Chromium, Blazor menyediakan proksi penelusuran kesalahan yang mengimplementasikan Protokol Chrome DevTools dan menambah protokol dengan . Informasi khusus NET. Saat penelusuran kesalahan pintasan keyboard ditekan, Blazor arahkan ke Chrome DevTools di proksi. Proksi terhubung ke jendela browser yang ingin Anda debug (karenanya perlu mengaktifkan penelusuran kesalahan jarak jauh).

Men-debug Blazor WebAssembly aplikasi dengan Firefox

Panduan di bagian ini menerapkan aplikasi penelusuran kesalahan Blazor WebAssembly di Firefox yang berjalan di Windows.

Men-debug Blazor WebAssembly aplikasi dengan Firefox memerlukan konfigurasi browser untuk penelusuran kesalahan jarak jauh dan menyambungkan ke browser menggunakan alat pengembang browser melalui proksi debugging .NET WebAssembly.

Catatan

Penelusuran kesalahan di Firefox dari Visual Studio saat ini tidak didukung.

Untuk men-debug Blazor WebAssembly aplikasi di Firefox selama pengembangan:

1. Mengonfigurasi Firefox:
   • Buka about:config di tab browser baru. Baca dan tutup peringatan yang muncul.
   • Aktifkan devtools.debugger.remote-enabled dengan mengatur nilainya ke True.
   • Aktifkan devtools.chrome.enabled dengan mengatur nilainya ke True.
   • Nonaktifkan devtools.debugger.prompt-connection dengan mengatur nilainya ke False.
2. Tutup semua instans Firefox.
3. Jalankan aplikasi di shell perintah dengan dotnet run.
4. Buka kembali browser Firefox dan navigasikan ke aplikasi.
5. Buka about:debugging di tab browser baru. Biarkan tab ini terbuka.
6. Kembali ke tab tempat aplikasi berjalan. Mulai penelusuran kesalahan jarak jauh dengan menekan Shift+Alt+d.
7. Di tab Debugger , buka file sumber aplikasi yang ingin Anda debug di bawah simpul file:// dan atur titik henti. Misalnya, atur titik henti pada currentCount++; baris dalam IncrementCount metode Counter komponen (Pages/Counter.razor).
8. Navigasi ke Counter halaman komponen (/counter) di tab browser aplikasi dan pilih tombol penghitung untuk menekan titik henti.
9. Tekan F5 untuk melanjutkan eksekusi di tab penelusuran kesalahan.

Putuskan pengecualian yang tidak tertangani

Debugger tidak melanggar pengecualian yang tidak tertangani secara default karena Blazor menangkap pengecualian yang tidak ditangani oleh kode pengembang.

Untuk memutuskan pengecualian yang tidak tertangani:

• Buka pengaturan pengecualian debugger (Debug>Pengaturan Pengecualian Windows>) di Visual Studio.
• Atur pengaturan Pengecualian JavaScript berikut ini:
  • Semua Pengecualian
  • Pengecualian Tidak Tertangkap

Peta sumber browser

Peta sumber browser memungkinkan browser untuk memetakan file yang dikompilasi kembali ke file sumber aslinya dan biasanya digunakan untuk penelusuran kesalahan sisi klien. Namun, Blazor saat ini tidak memetakan C# langsung ke JavaScript/WASM. Sebaliknya, Blazor apakah interpretasi IL dalam browser, sehingga peta sumber tidak relevan.

Konfigurasi Firewall

Jika firewall memblokir komunikasi dengan proksi debug, buat aturan pengecualian firewall yang mengizinkan komunikasi antara browser dan NodeJS proses.

Peringatan

Modifikasi konfigurasi firewall harus dilakukan dengan hati-hati untuk menghindari pembuatan kerentanan keamanan. Terapkan panduan keamanan dengan hati-hati, ikuti praktik keamanan terbaik, dan hormati peringatan yang dikeluarkan oleh produsen firewall.

Mengizinkan komunikasi terbuka dengan proses:NodeJS

• Membuka server Node ke koneksi apa pun, tergantung pada kemampuan dan konfigurasi firewall.
• Mungkin berisiko tergantung pada jaringan Anda.
• Hanya direkomendasikan pada mesin pengembang.

Jika memungkinkan, hanya izinkan komunikasi terbuka dengan NodeJS proses pada jaringan tepercaya atau privat.

Untuk panduan konfigurasi Windows Firewall , lihat Membuat Program Masuk atau Aturan Layanan. Untuk informasi selengkapnya, lihat Windows Defender Firewall dengan Keamanan Tingkat Lanjut dan artikel terkait dalam kumpulan dokumentasi Windows Firewall.

Pecahkan masalah

Jika Anda mengalami kesalahan, tips berikut ini dapat membantu:

• Hapus titik henti:
  • Google Chrome: Di tab Debugger , buka alat pengembang di browser Anda. Di konsol, jalankan localStorage.clear() untuk menghapus titik henti apa pun.
  • Microsoft Edge: Di tab Aplikasi , buka Penyimpanan lokal. Klik kanan situs dan pilih Hapus.
• Konfirmasikan bahwa Anda telah menginstal dan mempercayai sertifikat pengembangan ASP.NET Core HTTPS. Untuk informasi selengkapnya, lihat Menerapkan HTTPS di ASP.NET Core.
• Visual Studio memerlukan opsi Aktifkan penelusuran kesalahan JavaScript untuk ASP.NET (Chrome dan Edge) di Opsi>Alat>Men-debug>Umum. Ini adalah pengaturan default untuk Visual Studio. Jika penelusuran kesalahan tidak berfungsi, konfirmasikan bahwa opsi dipilih.
• Jika lingkungan Anda menggunakan proksi HTTP, pastikan bahwa localhost disertakan dalam pengaturan bypass proksi. Ini dapat dilakukan dengan mengatur NO_PROXY variabel lingkungan di:
  • File launchSettings.json untuk proyek.
  • Pada tingkat variabel lingkungan pengguna atau sistem agar diterapkan ke semua aplikasi. Saat menggunakan variabel lingkungan, mulai ulang Visual Studio agar perubahan diterapkan.
• Pastikan firewall atau proksi tidak memblokir komunikasi dengan proksi debug (NodeJS proses). Untuk informasi selengkapnya, lihat bagian Konfigurasi firewall.

Titik henti tidak tertembak OnInitialized{Async}

Proksi Blazor penelusuran kesalahan kerangka kerja tidak diluncurkan secara instan pada startup aplikasi, sehingga titik henti dalam OnInitialized{Async} metode siklus hidup mungkin tidak terpukul. Sebaiknya tambahkan penundaan di awal isi metode untuk memberikan proksi debug beberapa waktu untuk diluncurkan sebelum titik henti tertembak. Anda dapat menyertakan penundaan berdasarkan if arahan kompilator untuk memastikan bahwa penundaan tidak ada untuk build rilis aplikasi.

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Batas waktu Visual Studio (Windows)

Jika Visual Studio melemparkan pengecualian bahwa adaptor debug gagal diluncurkan yang menyebutkan bahwa batas waktu tercapai, Anda dapat menyesuaikan batas waktu dengan pengaturan Registri:

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

Tempat {TIMEOUT} penampung dalam perintah sebelumnya berada dalam milidetik. Misalnya, satu menit ditetapkan sebagai 60000.