Port diagnostik

Artikel ini berlaku untuk: ✔️ .NET Core 3.1 dan versi yang lebih baru

Runtime .NET mengekspos titik akhir layanan yang memungkinkan proses lain mengirim perintah diagnostik dan menerima respons melalui saluran IPC. Titik akhir ini disebut port diagnostik. Perintah dapat dikirim ke port diagnostik untuk:

• Ambil crash dump memori.
• Mulai penelusuran EventPipe.
• Minta baris perintah yang digunakan untuk meluncurkan aplikasi.

Port diagnostik mendukung berbagai jenis transport tergantung pada platform. Saat ini implementasi runtime CoreCLR dan Mono menggunakan Named Pipes di Windows dan Unix Domain Sockets di Linux dan macOS. Implementasi runtime Mono di Android, iOS, dan tvOS menggunakan TCP/IP. Saluran menggunakan protokol biner kustom. Sebagian besar pengembang tidak akan pernah berinteraksi langsung dengan saluran dan protokol yang mendasar, melainkan akan menggunakan alat GUI atau CLI yang berkomunikasi atas nama mereka. Misalnya, alat dotnet-dump dan dotnet-trace menyederhanakan pengiriman perintah protokol untuk menangkap file dump dan memulai penelusuran. Untuk pengembang yang ingin menulis peralatan kustom, paket NuGet Microsoft.Diagnostics.NETCore.Client menyediakan abstraksi API .NET dari transport dan protokol yang mendasarinya.

Pertimbangan keamanan

Port diagnostik mengekspos informasi sensitif tentang aplikasi yang sedang berjalan. Jika pengguna yang tidak tepercaya mendapatkan akses ke saluran ini, mereka dapat mengamati status program terperinci, termasuk rahasia apa pun yang ada dalam memori, dan mengubah eksekusi program secara sewenang-wenang. Pada runtime CoreCLR, port diagnostik default dikonfigurasi untuk hanya dapat diakses oleh akun pengguna yang sama yang meluncurkan aplikasi atau oleh akun dengan izin pengguna super. Jika model keamanan Anda tidak mempercayai proses lain dengan kredensial akun pengguna yang sama, Anda dapat menonaktifkan semua port diagnostik dengan mengatur variabel DOTNET_EnableDiagnostics=0lingkungan . Pengaturan ini akan memblokir kemampuan Anda untuk menggunakan alat eksternal seperti debugging .NET atau alat diagnostik dotnet-*.

Port diagnostik default

Di Windows, Linux, dan macOS, runtime memiliki satu port diagnostik yang terbuka secara default di endpoint yang sudah dikenal. Ini adalah port yang secara otomatis dihubungkan oleh alat diagnostik dotnet-* ketika belum dikonfigurasi secara eksplisit untuk menggunakan port alternatif. Titik akhir adalah:

• Windows - Pipa Bernama \\.\pipe\dotnet-diagnostic-{pid}
• Linux dan macOS - Soket Domain Unix {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} adalah id proses yang ditulis dalam desimal, {temp} adalah TMPDIR variabel lingkungan atau nilai /tmp jika TMPDIR tidak ditentukan/kosong, dan {disambiguation_key} merupakan waktu mulai proses yang ditulis dalam desimal. Pada macOS dan NetBSD, waktu mulai proses adalah jumlah detik sejak waktu epoch UNIX. Pada semua platform lain, itu jiffies sejak waktu boot.

Menangguhkan runtime saat startup

Secara default, runtime menjalankan kode terkelola segera setelah dimulai, terlepas dari apakah ada alat diagnostik yang telah terhubung ke port diagnostik. Kadang-kadang sangat bermanfaat untuk menunda pelaksanaan kode terkelola sampai setelah alat diagnostik terhubung, untuk mengamati perilaku awal program. Mengatur variabel DOTNET_DefaultDiagnosticPortSuspend=1 lingkungan menyebabkan runtime menunggu hingga alat tersambung ke port default. Jika tidak ada alat yang terpasang setelah beberapa detik, runtime akan menampilkan pesan peringatan di konsol yang menyatakan bahwa masih menunggu alat tersebut terpasang.

Mengonfigurasi port diagnostik tambahan

Nota

Ini hanya berfungsi untuk aplikasi yang menjalankan .NET 5 atau yang lebih baru.

Runtime Mono dan CoreCLR dapat menggunakan port diagnostik kustom yang dikonfigurasi dalam perannya masing-masing connect. Mono juga mendukung port TCP/IP kustom listen dalam peran tersebut, saat digunakan dengan dotnet-dsrouter di Android atau iOS. Port kustom ini selain port default yang tetap tersedia. Ada beberapa alasan umum bahwa port kustom berguna:

• Di Android, iOS, dan tvOS tidak ada port default, jadi mengonfigurasi port diperlukan untuk menggunakan alat diagnostik.
• Di lingkungan dengan kontainer atau firewall, Anda mungkin ingin menyiapkan alamat titik akhir yang dapat diprediksi yang tidak bervariasi berdasarkan ID proses seperti yang dilakukan port default. Kemudian port kustom dapat secara eksplisit ditambahkan ke daftar izinkan atau diproksi di beberapa batas keamanan.
• Untuk alat pemantauan, alat ini berguna untuk mendengarkan di titik akhir, dan runtime secara aktif mencoba menyambungkannya. Ini menghindari perlunya alat pemantauan untuk terus memeriksa secara berkala aplikasi yang baru dimulai. Di lingkungan di mana port diagnostik default tidak dapat diakses, port ini juga menghindari perlunya mengonfigurasi monitor dengan titik akhir kustom untuk setiap aplikasi yang dipantau.

Di setiap saluran komunikasi antara alat diagnostik dan runtime .NET, satu sisi harus menjadi pendengar dan menunggu sisi lain terhubung. Runtime dapat dikonfigurasi untuk bertindak sebagai connect pada port apa pun. (Runtime Mono juga dapat dikonfigurasi untuk bertindak dalam peran listen untuk port apa pun.) Port juga dapat dikonfigurasi secara independen untuk menangguhkan saat startup, menunggu alat diagnostik mengeluarkan perintah resume. Port yang dikonfigurasi untuk menyambung akan berusaha untuk menghubungkan kembali tanpa henti jika titik akhir jarak jauh tidak mendengarkan atau jika koneksi hilang. Tetapi aplikasi tidak secara otomatis menangguhkan kode terkelola saat menunggu untuk membuat koneksi tersebut. Jika Anda ingin aplikasi menunggu koneksi dibuat, gunakan opsi tangguhkan saat startup.

Port kustom dikonfigurasi menggunakan DOTNET_DiagnosticPorts variabel lingkungan. Variabel ini harus diatur ke daftar deskripsi port yang dibatasi titik koma. Setiap deskripsi port terdiri dari alamat titik akhir dan pengubah opsional yang mengontrol peran runtime connect atau listen serta apakah runtime harus ditangguhkan pada awal proses startup. Di Windows, alamat titik akhir adalah nama pipa bernama tanpa awalan \\.\pipe\ . Di Linux dan macOS, ini adalah jalur lengkap ke Unix Domain Socket. Di Android, iOS, dan tvOS, alamatnya adalah IP dan port. Contohnya:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Runtime terhubung ke pipa bernama \\.\pipe\my_diag_port1.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux dan macOS) Runtime terhubung ke Soket /foo/tool1.socket Domain Unix dan /foo/tool2.socket.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS, dan tvOS) Runtime terhubung ke IP 127.0.0.1 pada port 9000.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux dan macOS) Contoh ini memiliki pengubah nosuspend . Runtime mencoba terhubung ke Unix Domain Socket /foo/tool1.socket yang dibuat oleh alat eksternal. Port diagnostik tambahan biasanya akan menyebabkan runtime ditangguhkan saat startup menunggu perintah untuk melanjutkan, tetapi nosuspend menyebabkan runtime tidak perlu menunggu.

Sintaks lengkap untuk port adalah address[,(listen|connect)][,(suspend|nosuspend)]. connect adalah default jika tidak ada connect atau listen ditentukan (dan listen hanya didukung oleh runtime Mono di Android atau iOS). suspend adalah default jika tidak ada suspend atau nosuspend ditentukan.

Penggunaan dalam alat diagnostik dotnet

Alat seperti dotnet-dump, dotnet-counters, dan dotnet-trace semuanya mendukung kata kerja collect atau monitor yang berkomunikasi dengan aplikasi .NET melalui port diagnostik.

• Saat alat-alat ini menggunakan --processId argumen , alat secara otomatis menghitung alamat port diagnostik default dan terhubung ke argumen tersebut.
• Saat menentukan --diagnostic-port argumen, alat mendengarkan di alamat yang diberikan dan Anda harus menggunakan DOTNET_DiagnosticPorts variabel lingkungan untuk mengonfigurasi aplikasi Anda untuk terhubung. Untuk contoh lengkap dengan "dotnet-counters", lihat Menggunakan Port Diagnostik.

Menggunakan ds-router untuk memproksi port diagnostik

Semua alat diagnostik dotnet-* mengharapkan untuk terhubung ke port diagnostik yang merupakan Pipa Bernama atau Soket Domain Unix lokal. Mono sering berjalan pada perangkat keras terisolasi atau di emulator yang memerlukan proksi melalui TCP agar dapat diakses. Alat dotnet-dsrouter dapat mem-proxy Name Pipe atau Unix Domain Socket lokal ke TCP sehingga alat dapat digunakan di lingkungan tersebut. Untuk informasi selengkapnya, lihat dotnet-dsrouter.