Port diagnostik

Artikel
09/22/2023

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.
Memulai jejak EventPipe.
Minta baris perintah yang digunakan untuk meluncurkan aplikasi.

Port diagnostik mendukung transportasi yang berbeda tergantung pada platform. Saat ini implementasi runtime CoreCLR dan Mono menggunakan Named Pipes pada Windows dan Unix Domain Sockets di Linux dan macOS. Implementasi runtime Mono di Android, iOS, dan tvOS menggunakan TCP/IP. Saluran ini 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 abstrak mengirim perintah protokol untuk menangkap cadangan dan memulai jejak. Untuk pengembang yang ingin menulis alat kustom, paket NuGet Microsoft.Diagnostics.NETCore.Client menyediakan abstraksi API .NET dari transportasi dan protokol yang mendasar.

Pertimbangan keamanan

Port diagnostik memaparkan 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 penelusuran kesalahan .NET atau alat diagnostik dotnet-*.

Catatan

.NET 6 menstandarkan pada prefiks DOTNET_ daripada COMPlus_ untuk variabel lingkungan yang mengonfigurasi perilaku run-time .NET. Namun, prefiks COMPlus_ akan terus berfungsi. Jika Anda menggunakan versi runtime .NET sebelumnya, Anda masih harus menggunakan prefiks COMPlus_ untuk variabel lingkungan.

Port diagnostik default

Di Windows, Linux, dan macOS, runtime bahasa umum memiliki satu port diagnostik yang terbuka secara default di titik akhir terkenal. Ini adalah port yang terhubung ke alat diagnostik dotnet-* secara otomatis ketika belum dikonfigurasi secara eksplisit untuk menggunakan port alternatif. Titik akhirnya adalah:

Windows - Pipa yang Dinamai \\.\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 variabel lingkungan TMPDIR atau nilai /tmp jika TMPDIR tidak terdefinisi/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. Terkadang berguna untuk memiliki runtime tunggu untuk menjalankan kode terkelola sampai setelah alat diagnostik terhubung, untuk mengamati perilaku program awal. Mengatur DOTNET_DefaultDiagnosticPortSuspend=1 variabel lingkungan menyebabkan runtime bahasa umum menunggu hingga alat tersambung ke port default. Jika tidak ada alat yang dilampirkan setelah beberapa detik, runtime mencetak pesan peringatan ke konsol yang menjelaskan bahwa itu masih menunggu alat untuk dilampirkan.

Mengonfigurasi port diagnostik tambahan

Catatan

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 peran tersebut connect . Mono juga mendukung port TCP/IP kustom dalam peran tersebut listen , 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 diproksikan di beberapa batas keamanan.
Untuk alat pemantauan, alat ini berguna untuk mendengarkan alat di titik akhir, dan runtime bahasa umum secara aktif mencoba menyambungkannya. Ini menghindari kebutuhan alat pemantauan untuk terus melakukan polling untuk aplikasi baru yang dimulai. Di lingkungan tempat port diagnostik default tidak dapat diakses, port tersebut juga menghindari perlunya mengonfigurasi monitor dengan titik akhir kustom untuk setiap aplikasi yang dipantau.

Di setiap saluran komunikasi antara alat diagnostik dan runtime bahasa umum .NET, satu sisi harus menjadi pendengar dan menunggu sisi lain terhubung. Runtime dapat dikonfigurasi untuk bertindak dalam connect peran untuk port apa pun. (Runtime Mono juga dapat dikonfigurasi untuk bertindak dalam listen peran untuk port apa pun.) Port juga dapat dikonfigurasi secara independen untuk ditangguhkan saat startup, menunggu alat diagnostik mengeluarkan perintah resume. Port yang dikonfigurasi untuk menyambungkan mengulangi upaya koneksi mereka tanpa batas waktu 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 variabel lingkungan DOTNET_DiagnosticPorts. 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 runtime connect atau listen peran dan jika runtime harus ditangguhkan saat startup. Pada Windows, alamat titik akhir adalah nama pipa yang dinamai tanpa prefiks \\.\pipe\. Di Linux dan macOS, ini adalah jalur lengkap ke Unix Domain Socket. Di Android, iOS, dan tvOS, alamatnya adalah IP dan port. Misalnya:

DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Runtime bahasa umum tersambung ke \\.\pipe\my_diag_port1 pipa yang dinamai.
DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux dan macOS) Runtime bahasa umum terhubung ke Unix Domain Sockets /foo/tool1.socket dan /foo/tool2.socket.
DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS, dan tvOS) Runtime bahasa umum terhubung ke IP 127.0.0.1 pada port 9000.
DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux dan macOS) Contoh ini memiliki pengubah nosuspend . Runtime mencoba menyambungkan ke Unix Domain Socket /foo/tool1.socket yang dibuat alat eksternal. Port diagnostik tambahan biasanya akan menyebabkan runtime ditangguhkan saat startup menunggu perintah resume, tetapi nosuspend menyebabkan runtime bahasa umum tidak 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 yang ditentukan.

Penggunaan dalam alat diagnostik dotnet

Alat seperti dotnet-dump, dotnet-counters, dan dotnet-trace semua dukungan collect atau monitor kata kerja yang berkomunikasi ke 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 argumen --diagnostic-port, alat mendengarkan di alamat yang diberikan dan Anda harus menggunakan variabel lingkungan DOTNET_DiagnosticPorts untuk mengonfigurasi aplikasi Anda untuk tersambung. Untuk contoh lengkap dengan penghitung dotnet, lihat Menggunakan Port Diagnostik.

Gunakan 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-proksi Pipa yang Dinamai atau Unix Domain Socket lokal ke TCP sehingga alat dapat digunakan di lingkungan tersebut. Untuk informasi selengkapnya, lihat dotnet-dsrouter.

Bagikan melalui