Diagnostické porty

Tento článek se vztahuje na: ✔️ .NET Core 3.1 a novější verze

Modul runtime .NET zveřejňuje koncový bod služby, který umožňuje jiným procesům odesílat diagnostické příkazy a přijímat odpovědi přes kanál IPC. Tento koncový bod se nazývá diagnostický port. Příkazy se dají odeslat na port diagnostiky do:

• Zachyťte výpis paměti.
• Spusťte trasování EventPipe .
• Požádejte o příkazový řádek použitý ke spuštění aplikace.

Diagnostický port podporuje různé přenosy v závislosti na platformě. V současné době implementace CoreCLR i Mono runtime používají pojmenované kanály ve Windows a Unix Domain Sockets v Linuxu a macOS. Implementace runtime modulu Mono v systémech Android, iOS a tvOS používá protokol TCP/IP. Kanál používá vlastní binární protokol. Většina vývojářů nebude nikdy přímo komunikovat s podkladovým kanálem a protokolem, ale místo toho bude používat grafické uživatelské rozhraní nebo nástroje rozhraní příkazového řádku, které komunikují jejich jménem. Například nástroje dotnet-dump a dotnet-trace abstrahují odesílání příkazů protokolu za účelem zachycení výpisů a spuštění trasování. Pro vývojáře, kteří chtějí psát vlastní nástroje, balíček NuGet Microsoft.Diagnostics.NETCore.Client poskytuje abstrakci rozhraní .NET API základního přenosu a protokolu.

Bezpečnostní aspekty

Diagnostický port zveřejňuje citlivé informace o spuštěné aplikaci. Pokud nedůvěryhodný uživatel získá přístup k tomuto kanálu, může sledovat podrobný stav programu, včetně všech tajných kódů, které jsou v paměti, a libovolně upravit provádění programu. V modulu runtime CoreCLR je výchozí diagnostický port nakonfigurovaný tak, aby byl přístupný jenom pomocí stejného uživatelského účtu, který spustil aplikaci nebo účet s oprávněními superuživatele. Pokud váš model zabezpečení nedůvěřuje jiným procesům se stejnými přihlašovacími údaji uživatelského účtu, můžete zakázat všechny diagnostické porty nastavením proměnné DOTNET_EnableDiagnostics=0prostředí . Toto nastavení zablokuje možnost používat externí nástroje, jako je ladění .NET nebo jakýkoli z diagnostických nástrojů dotnet-*.

Výchozí diagnostický port

V systému Windows, Linux a macOS má modul runtime ve výchozím nastavení otevřený jeden diagnostický port v dobře známém koncovém bodu. Jedná se o port, ke kterému se diagnostické nástroje dotnet-* připojují automaticky, když nejsou explicitně nakonfigurované tak, aby používaly alternativní port. Koncový bod je:

• Windows – pojmenovaný kanál \\.\pipe\dotnet-diagnostic-{pid}
• Linux a macOS – Unix Domain Socket {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} je ID procesu napsané v desítkové soustavě, {temp} je TMPDIR proměnná prostředí nebo hodnota /tmp , pokud TMPDIR není definována nebo prázdná, a {disambiguation_key} jedná se o počáteční čas procesu napsaný v desítkové soustavě. V systémech macOS a NetBSD je počáteční čas procesu počet sekund od epochy UNIX. Na všech ostatních platformách je to od doby spuštění jiffies.

Pozastavení modulu runtime při spuštění

Modul runtime ve výchozím nastavení spustí spravovaný kód hned po spuštění bez ohledu na to, jestli se k diagnostickému portu připojily nějaké diagnostické nástroje. Někdy je užitečné, aby modul runtime čekal na spuštění spravovaného kódu až po připojení diagnostického nástroje, aby bylo možné sledovat chování počátečního programu. Nastavení proměnné DOTNET_DefaultDiagnosticPortSuspend=1 prostředí způsobí, že modul runtime počká, dokud se nástroj připojí k výchozímu portu. Pokud po několika sekundách není žádný nástroj připojený, modul runtime vypíše do konzoly upozornění s vysvětlením, že stále čeká na připojení nástroje.

Konfigurace dalších diagnostických portů

Poznámka:

Funguje to jenom pro aplikace, na kterých běží .NET 5 nebo novější.

Moduly Mono a CoreCLR runtime mohou v roli connect používat vlastní nakonfigurované diagnostické porty. Mono také podporuje vlastní porty TCP/IP v listen roli při použití s dotnet-dsrouter v Androidu nebo iOSu. Tyto vlastní porty jsou navíc k výchozímu portu, který zůstává dostupný. Existují některé běžné důvody, proč jsou vlastní porty užitečné:

• V Androidu, iOSu a tvOSu není žádný výchozí port, takže konfigurace portu je nezbytná pro použití diagnostických nástrojů.
• V prostředích s kontejnery nebo branami firewall můžete chtít nastavit předvídatelnou adresu koncového bodu, která se nemění podle ID procesu, na rozdíl od výchozího portu. Pak lze vlastní port explicitně přidat do seznamu povolených nebo přesměrovat přes určitou bezpečnostní hranici.
• Pro monitorovací nástroje je užitečné, aby nástroj naslouchal síťovému koncovému bodu a modul runtime se k němu aktivně pokouší připojit. Tím se zabrání potřebě, aby nástroj pro monitorování neustále dotazoval na spuštění nových aplikací. V prostředích, kde není výchozí diagnostický port přístupný, se také vyhne nutnosti konfigurovat monitorování s vlastním koncovým bodem pro každou monitorovanou aplikaci.

V každém komunikačním kanálu mezi diagnostickým nástrojem a modulem runtime .NET musí být jedna strana naslouchající a čekat na připojení druhé strany. Modul runtime je možné nakonfigurovat tak, aby fungoval v connect roli pro libovolný port. (Modul runtime Mono lze také nakonfigurovat tak, aby fungoval v listen roli pro libovolný port.) Porty je také možné nezávisle nakonfigurovat tak, aby se pozastavily při spuštění, a čekat na vydání příkazu pro obnovení diagnostickým nástrojem. Porty nakonfigurované pro připojení opakují pokusy o připojení po neomezenou dobu, pokud vzdálený koncový bod nenaslouchá nebo dojde ke ztrátě připojení. Aplikace ale při čekání na navázání připojení automaticky nespusí spravovaný kód. Pokud chcete, aby aplikace čekala na navázání připojení, použijte možnost pozastavení při spuštění.

Vlastní porty se konfigurují pomocí proměnné prostředí DOTNET_DiagnosticPorts. Tato proměnná by měla být nastavena na seznam popisů portů oddělených středníkem. Každý popis portu se skládá z adresy koncového bodu a volitelných modifikátorů, které určují roli connect nebo listen modulu runtime a zda by se runtime měl při spuštění pozastavit. Ve Windows je adresa koncového bodu název pojmenovaného kanálu bez předpony \\.\pipe\ . V Linuxu a macOS je to úplná cesta k rozhraní UNIX Domain Socket. V Androidu, iOSu a tvOSu je adresa IP a port. Například:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Runtime se připojí k pojmenovanému kanálu \\.\pipe\my_diag_port1.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux a macOS) Modul runtime se připojuje k rozhraní UNIX Domain Sockets /foo/tool1.socket i /foo/tool2.socket.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 – (Android, iOS a tvOS) Modul runtime se připojí k IP adrese 127.0.0.1 na portu 9000.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend – (Linux a macOS) Tento příklad má nosuspend modifikátor. Modul runtime se pokusí připojit k rozhraní Unix Domain Socket /foo/tool1.socket, které vytvoří externí nástroj. Další diagnostické porty by normálně způsobily pozastavení modulu runtime při spuštění čekání na příkaz resume, ale nosuspend způsobí, že modul runtime nečeká.

Úplná syntaxe portu je address[,(listen|connect)][,(suspend|nosuspend)]. connect je výchozí, pokud není zadána connect ani listen (a listen je podporována pouze runtimem Mono na Androidu nebo iOS). suspend je výchozí hodnota, pokud suspend není zadána nebo nosuspend není zadána.

Použití diagnostických nástrojů v dotnetu

Nástroje jako dotnet-dump, dotnet-counters a dotnet-trace podporují příkazy collect nebo monitor, které komunikují s aplikacemi .NET prostřednictvím diagnostického portu.

• Pokud tyto nástroje používají --processId argument, nástroj automaticky vypočítá výchozí adresu portu diagnostiky a připojí se k němu.
• Při zadávání argumentu --diagnostic-port nástroj naslouchá na dané adrese a k konfiguraci připojení aplikace byste měli použít proměnnou DOTNET_DiagnosticPorts prostředí. Úplný příklad použití dotnet-counters najdete v části Použití diagnostického portu.

Použijte ds-router pro proxyování diagnostického portu

Všechny diagnostické nástroje dotnet-* očekávají připojení k diagnostickému portu, což je místní pojmenovaný kanál nebo Unix doménová soket. Mono často běží na izolovaném hardwaru nebo v emulátorech, které potřebují proxy přes protokol TCP, aby byly přístupné. Nástroj dotnet-dsrouter může proxyovat místní pojmenovaný kanál nebo Unixový doménový socket na TCP, aby bylo možné nástroje používat v těchto prostředích. Další informace najdete v tématu dotnet-dsrouter.