Tanılama bağlantı noktaları

Bu makale şunlar için geçerlidir: ✔️ .NET Core 3.1 ve üzeri sürümler

.NET çalışma zamanı, diğer işlemlerin tanılama komutları göndermesine ve bir IPC kanalı üzerinden yanıt almasına olanak tanıyan bir hizmet uç noktası sunar. Bu uç nokta tanılama bağlantı noktası olarak adlandırılır. Komutlar tanılama bağlantı noktasına şu şekilde gönderilebilir:

• Bir bellek dökümü yakalayın.
• EventPipe izlemeyi başlatın.
• Uygulamayı başlatmak için kullanılan komut satırını isteyin.

Tanılama bağlantı noktası, platforma bağlı olarak farklı aktarımları destekler. Şu anda hem CoreCLR hem de Mono çalışma zamanı uygulamaları, Windows üzerinde Adlandırılmış Kanallar ve Linux ve macOS üzerinde Unix Etki Alanı Yuvaları'nı kullanır. Android, iOS ve tvOS'ta Mono çalışma zamanı uygulaması TCP/IP kullanır. Kanal özel bir ikili protokol kullanır. Geliştiricilerin çoğu hiçbir zaman temel kanal ve protokolle doğrudan etkileşim kurmaz, bunun yerine kendi adına iletişim kuran GUI veya CLI araçlarını kullanır. Örneğin, dotnet-dump ve dotnet-trace araçları, dökümleri yakalamak ve izlemeleri başlatmak için protokol komutlarını soyut gönderir. Özel araçlar yazmak isteyen geliştiriciler için Microsoft.Diagnostics.NETCore.Client NuGet paketi , temel alınan aktarım ve protokolün .NET API soyutlamasını sağlar.

Güvenlikle ilgili dikkat edilmesi gerekenler

Tanılama bağlantı noktası, çalışan bir uygulama hakkında hassas bilgileri kullanıma sunar. Güvenilmeyen bir kullanıcı bu kanala erişim kazanırsa, bellekteki gizli diziler de dahil olmak üzere ayrıntılı program durumunu gözlemleyebilir ve rastgele programın yürütülmesini değiştirebilir. CoreCLR çalışma zamanında, varsayılan tanılama bağlantı noktası yalnızca uygulamayı başlatan kullanıcı hesabı veya süper kullanıcı izinlerine sahip bir hesap tarafından erişilebilir olacak şekilde yapılandırılır. Güvenlik modeliniz aynı kullanıcı hesabı kimlik bilgilerine sahip diğer işlemlere güvenmiyorsa, ortam değişkenini DOTNET_EnableDiagnostics=0ayarlayarak tüm tanılama bağlantı noktalarını devre dışı bırakabilirsiniz. Bu ayar, .NET hata ayıklaması veya dotnet-* tanılama araçlarından herhangi biri gibi dış araçları kullanmanızı engeller.

Varsayılan tanılama bağlantı noktası

Windows, Linux ve macOS'ta çalışma zamanı, iyi bilinen bir uç noktada varsayılan olarak bir tanılama bağlantı noktası açar. Bu, dotnet-* tanılama araçlarının alternatif bir bağlantı noktası kullanacak şekilde açıkça yapılandırılmadığında otomatik olarak bağlandıkları bağlantı noktasıdır. Uç nokta:

• Windows - Adlandırılmış Kanal \\.\pipe\dotnet-diagnostic-{pid}
• Linux ve macOS - Unix Domain Socket {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} ondalık olarak yazılan işlem kimliğidir, {temp}TMPDIR ortam değişkeni veya TMPDIR tanımsız/boş ise /tmp değeri, ve {disambiguation_key} ondalık olarak yazılan işlem başlangıç saatidir. macOS ve NetBSD'de, işlemin başlama zamanı, UNIX epoch başlangıcından bu yana geçen saniye sayısıdır. Diğer tüm platformlarda, önyükleme zamanından bu yana geçen süre jiffies cinsindendir.

Başlangıçta çalışma zamanını askıya alma

Varsayılan olarak, herhangi bir tanılama aracının tanılama bağlantı noktasına bağlı olup olmadığına bakılmaksızın çalışma zamanı yönetilen kodu başlar başlamaz yürütür. Bazen, ilk program davranışını gözlemlemek için bir tanılama aracı bağlanana kadar çalışma zamanının yönetilen kodu çalıştırmayı beklemesi yararlı olabilir. Ortam değişkeninin DOTNET_DefaultDiagnosticPortSuspend=1 ayarlanması, çalışma zamanının bir araç varsayılan bağlantı noktasına bağlanana kadar beklemesine neden olur. Birkaç saniye sonra hiçbir araç eklenmezse, çalışma zamanı konsola hala bir aracın eklenmesini beklediğini açıklayan bir uyarı iletisi yazdırır.

Ek tanılama bağlantı noktalarını yapılandırma

Uyarı

Bu, yalnızca .NET 5 veya üzerini çalıştıran uygulamalar için çalışır.

Hem Mono hem de CoreCLR çalışma zamanları, connect rolünde özel yapılandırılmış tanılama bağlantı noktalarını kullanabilir. Mono, listen rolünde, Android veya iOS üzerinde dotnet-dsrouter ile kullanıldığında özel TCP/IP bağlantı noktalarını da destekler. Bu özel bağlantı noktaları, kullanılabilir durumda kalan varsayılan bağlantı noktasına ek olarak bulunur. Özel bağlantı noktalarının yararlı olmasının birkaç yaygın nedeni vardır:

• Android, iOS ve tvOS'ta varsayılan bağlantı noktası yoktur, bu nedenle tanılama araçlarını kullanmak için bir bağlantı noktası yapılandırmak gerekir.
• Kapsayıcıların veya güvenlik duvarlarının olduğu ortamlarda, varsayılan bağlantı noktasının yaptığı gibi işlem kimliğine göre değişmeyen öngörülebilir bir uç nokta adresi ayarlamak isteyebilirsiniz. Özel bağlantı noktası daha sonra açıkça izin verilenler listesine eklenebilir veya bazı güvenlik sınırları aşarak proxy üzerinden yönlendirilebilir.
• İzleme araçlarının, bir uç noktada dinleme yapması ve çalışma ortamının bununla etkin bir şekilde bağlantı kurmaya çalışması faydalıdır. Bu, izleme aracının yeni uygulamaların başlatılıp başlatılmadığını sürekli olarak yokllamasına gerek kalmadan çalışma sağlar. Varsayılan tanılama bağlantı noktasının erişilebilir olmadığı ortamlarda, izleyiciyi izlenen her uygulama için özel bir uç noktayla yapılandırma gereksiniminden de kaçınır.

Tanılama aracı ile .NET çalışma zamanı arasındaki her iletişim kanalında bir tarafın dinleyici olması ve diğer tarafın bağlanmasını beklemesi gerekir. Çalışma zamanı, herhangi bir bağlantı noktasında connect rolünü üstlenecek şekilde yapılandırılabilir. (Mono çalışma zamanı, herhangi bir bağlantı noktası için belirli bir rol üstlenecek şekilde de yapılandırılabilir.) Bağlantı noktaları, bir tanılama aracının devam etme komutu vermesini bekleyerek başlangıçta askıya alınacak şekilde bağımsız olarak yapılandırılabilir. Bağlanmak için yapılandırılan bağlantı noktaları, uzak uç nokta dinlenmiyorsa veya bağlantı kesilirse bağlantı girişimlerini süresiz olarak yineler. Ancak uygulama, bu bağlantının kurulmasını beklerken yönetilen kodu otomatik olarak askıya almaz. Uygulamanın bağlantı kurulmasını beklemesini istiyorsanız başlangıçta askıya alma seçeneğini kullanın.

Özel bağlantı noktaları ortam değişkeni kullanılarak DOTNET_DiagnosticPorts yapılandırılır. Bu değişken, bağlantı noktası açıklamalarının noktalı virgülle ayrılmış listesine ayarlanmalıdır. Her port açıklaması, bir uç nokta adresi ve isteğe bağlı değiştiricilerden oluşur. Çalışma zamanının connect rolünü ve çalışma zamanının listen başlangıçta askıya alınması gerekip gerekmediğini denetler. Windows'da uç nokta adresi, ön eki olmayan adlandırılmış bir kanalın \\.\pipe\ adıdır. Linux ve macOS'ta, bir Unix domain soketinin tam yoludur. Android, iOS ve tvOS'ta adres bir IP ve bağlantı noktasıdır. Örneğin:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Çalışma zamanı adlandırılmış kanala \\.\pipe\my_diag_port1 bağlanır.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux ve macOS) Çalışma zamanı hem Unix Etki Alanı Yuvaları /foo/tool1.socket hem de /foo/tool2.socket ile bağlantı kurar.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS ve tvOS) Çalışma zamanı, bağlantı noktası 9000'de IP 127.0.0.1'e bağlanır.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux ve macOS) Bu örnekte değiştirici vardır nosuspend . Çalışma zamanı, bir dış araç tarafından oluşturulan Unix Etki Alanı Yuvası /foo/tool1.socket ile bağlantı kurmaya çalışır. Ek tanılama bağlantı noktaları, devam komutunu beklerken başlatma sırasında normalde çalışma zamanının askıya alınmasına neden olur, ancak nosuspend, çalışma zamanının beklememesini sağlar.

Bir bağlantı noktasının tam söz dizimi şeklindedir address[,(listen|connect)][,(suspend|nosuspend)]. connect varsayılan değerdir, eğer ne connect ne de listen belirtilmediğinde (ve listen yalnızca Android veya iOS'ta Mono çalışma zamanı tarafından desteklenir). Ne suspend ne de nosuspend belirtilmezse, suspend varsayılan değerdir.

dotnet tanılama araçlarında kullanım

Dotnet-dump, dotnet-counters ve dotnet-trace gibi araçlar, tanılama portu aracılığıyla bir .NET uygulamasıyla iletişim kurmak için collect veya monitor fiillerini destekler.

• Bu araçlar --processId bağımsız değişkenini kullandığında, araç otomatik olarak varsayılan tanılama bağlantı noktası adresini hesaplar ve buna bağlanır.
• Bağımsız değişkeni `--diagnostic-port` belirtirken, araç verilen adresi dinler ve uygulamanızı bağlanacak şekilde yapılandırmak için `DOTNET_DiagnosticPorts` ortam değişkenini kullanmanız gerekir. dotnet-counters ile ilgili eksiksiz bir örnek için Tanılama Bağlantı Noktasını Kullanma örneğine bakınız.

Tanılama bağlantı noktasına proxy olarak ds-router kullanma

Tüm dotnet-* tanılama araçları yerel Adlandırılmış Boru veya Unix Etki Alanı Yuvası olan bir tanılama portuna bağlanmayı bekler. Mono genellikle yalıtılmış donanımlarda veya erişilebilir olması için TCP üzerinden ara sunucu gerektiren öykünücülerde çalışır. dotnet-dsrouter aracı, yerel Adlandırılmış Kanal veya Unix Etki Alanı Yuvası'ndan TCP'ye bağlantı aracılığı yaparak bu ortamlar için araçların kullanılmasına olanak tanır. Daha fazla bilgi için bkz. dotnet-dsrouter.