Diagnosztikai portok

Ez a cikk a .NET Core 3.1 és újabb verzióira ✔️ vonatkozik

A .NET-futtatókörnyezet egy szolgáltatásvégpontot tesz elérhetővé, amely lehetővé teszi más folyamatok számára a diagnosztikai parancsok küldését és a válaszok fogadását egy IPC-csatornán keresztül. Ezt a végpontot diagnosztikai portnak nevezzük. Parancsok küldhetők a diagnosztikai portra a következő címre:

• Memóriakép rögzítése.
• Indítsa el az EventPipe-nyomkövetést.
• Kérje le az alkalmazás elindításához használt parancssort.

A diagnosztikai port platformtól függően különböző átviteleket támogat. A CoreCLR és a Mono futtatókörnyezeti implementációk jelenleg nevesített csöveket használnak Windowson és Unix Domain Socketsen Linuxon és macOS rendszeren. Az Androidon, iOS-en és tvOS-en futó Mono futtatókörnyezeti implementáció TCP/IP-t használ. A csatorna egyéni bináris protokollt használ. A fejlesztők többsége soha nem fogja közvetlenül használni a mögöttes csatornát és protokollt, hanem a nevükben kommunikáló GUI- vagy CLI-eszközöket fog használni. A dotnet-dump és dotnet-trace eszközök például absztrakt protokollparancsokat küldenek a memóriaképek rögzítéséhez és a nyomkövetések elindításához. Az egyéni eszközök írására vágyó fejlesztők számára a Microsoft.Diagnostics.NETCore.Client NuGet csomag .NET API-absztrakciót biztosít az alapul szolgáló átvitelről és protokollról.

Biztonsági szempontok

A diagnosztikai port bizalmas információkat tesz közzé egy futó alkalmazásról. Ha egy nem megbízható felhasználó hozzáfér ehhez a csatornához, megfigyelheti a program részletes állapotát, beleértve a memóriában lévő titkos kulcsokat is, és tetszőlegesen módosíthatja a program végrehajtását. A CoreCLR-futtatókörnyezetben az alapértelmezett diagnosztikai port úgy van konfigurálva, hogy csak ugyanaz a felhasználói fiók legyen elérhető, amely elindította az alkalmazást, vagy egy felügyelői engedélyekkel rendelkező fiók. Ha a biztonsági modell nem bízik meg más folyamatokban ugyanazzal a felhasználói fiók hitelesítő adataival, letilthatja az összes diagnosztikai portot a környezeti változó DOTNET_EnableDiagnostics=0beállításával. Ez a beállítás letiltja a külső eszközök, például a .NET hibakeresés vagy a dotnet-* diagnosztikai eszközök használatát.

Feljegyzés

A .NET 6 az előtagon DOTNET_ szabványosítja a .NET futásidejű viselkedést konfiguráló környezeti változók helyett COMPlus_ . Az COMPlus_ előtag azonban továbbra is működni fog. Ha a .NET-futtatókörnyezet egy korábbi verzióját használja, akkor is használja a COMPlus_ környezeti változók előtagját.

Alapértelmezett diagnosztikai port

Windows, Linux és macOS rendszeren a futtatókörnyezetben alapértelmezés szerint egy diagnosztikai port nyílik meg egy jól ismert végponton. Ez az a port, amelyhez a dotnet-* diagnosztikai eszközök automatikusan csatlakoznak, ha nincsenek explicit módon konfigurálva alternatív port használatára. A végpont a következő:

• Windows – Elnevezett cső \\.\pipe\dotnet-diagnostic-{pid}
• Linux és macOS – Unix Domain Socket {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} az a folyamatazonosító, amely decimálisan van megírva, {temp} a TMPDIR környezeti változó vagy az érték /tmp , ha TMPDIR nincs definiálva/üres, és {disambiguation_key} a folyamat kezdési időpontja decimálisan van megírva. MacOS és NetBSD esetén a folyamat kezdési ideje a UNIX-korszak óta eltelt másodpercek száma. Minden más platformon ez a rendszerindítási idő óta jiffies.

A futtatókörnyezet felfüggesztése indításkor

A futtatókörnyezet alapértelmezés szerint azonnal végrehajtja a felügyelt kódot, függetlenül attól, hogy bármely diagnosztikai eszköz csatlakozott-e a diagnosztikai porthoz. Néha hasznos lehet, ha a futtatókörnyezet megvárja a felügyelt kód futtatását, amíg egy diagnosztikai eszköz csatlakozik, hogy megfigyelje a program kezdeti viselkedését. A környezeti változó DOTNET_DefaultDiagnosticPortSuspend=1 beállítása miatt a futtatókörnyezet megvárja, amíg egy eszköz csatlakozik az alapértelmezett porthoz. Ha néhány másodperc után nincs eszköz csatlakoztatva, a futtatókörnyezet egy figyelmeztető üzenetet nyomtat ki a konzolra, amely elmagyarázza, hogy még mindig vár egy eszköz csatolására.

További diagnosztikai portok konfigurálása

Feljegyzés

Ez csak .NET 5 vagy újabb verziót futtató alkalmazások esetén működik.

A Mono és a CoreCLR futtatókörnyezet egyaránt használhat egyéni konfigurált diagnosztikai portokat a connect szerepkörben. A Mono az egyéni TCP/IP-portokat is támogatja a listen szerepkörben, ha a dotnet-dsrouterrel használják Androidon vagy iOS-en. Ezek az egyéni portok a továbbra is elérhető alapértelmezett porton kívül vannak. Az egyéni portok hasznosnak bizonyulnak néhány gyakori okból:

• Android, iOS és tvOS rendszeren nincs alapértelmezett port, ezért a diagnosztikai eszközök használatához szükség van egy port konfigurálására.
• Tárolókkal vagy tűzfalakkal rendelkező környezetekben célszerű lehet olyan kiszámítható végpontcímet beállítani, amely az alapértelmezett porthoz hasonlóan nem változik a folyamatazonosítótól függően. Ezután az egyéni port explicit módon hozzáadható egy engedélyezési listához, vagy bizonyos biztonsági határokon átnyúlva.
• A monitorozási eszközök esetében hasznos, ha az eszköz figyel egy végpontot, és a futtatókörnyezet aktívan próbál csatlakozni hozzá. Így nem kell a monitorozási eszköznek folyamatosan lekérdeznie az új alkalmazásokat. Olyan környezetekben, ahol az alapértelmezett diagnosztikai port nem érhető el, a monitort nem kell egyéni végponttal konfigurálni minden monitorozott alkalmazáshoz.

A diagnosztikai eszköz és a .NET-futtatókörnyezet közötti kommunikációs csatornák mindegyikében az egyik oldalnak figyelőnek kell lennie, és várnia kell, amíg a másik oldal csatlakozik. A futtatókörnyezet konfigurálható úgy, hogy bármely connect port szerepkörében működjön. (A Mono futtatókörnyezet úgy is konfigurálható, hogy bármely port szerepkörében listen működjön.) A portok egymástól függetlenül is konfigurálhatók úgy, hogy indításkor felfüggesztődjenek, és arra várnak, hogy egy diagnosztikai eszköz kiadjon egy folytatási parancsot. A csatlakozásra konfigurált portok határozatlan időre megismételik a csatlakozási kísérleteket, ha a távoli végpont nem figyel, vagy ha a kapcsolat megszakad. Az alkalmazás azonban nem függeszti fel automatikusan a felügyelt kódot, miközben a kapcsolat létrehozására vár. Ha azt szeretné, hogy az alkalmazás megvárja a kapcsolat létrehozását, használja a felfüggesztést az indításkor.

Az egyéni portok a DOTNET_DiagnosticPorts környezeti változó használatával vannak konfigurálva. Ezt a változót a portleírások pontosvesszővel tagolt listájára kell állítani. Minden portleírás egy végpontcímből és választható módosítókból áll, amelyek vezérli a futtatókörnyezet connect vagy listen a szerepkör használatát, és hogy a futtatókörnyezetnek felfüggesztenie kell-e az indítást. Windows rendszeren a végpont címe egy elnevezett cső neve az \\.\pipe\ előtag nélkül. Linux és macOS rendszeren ez a Unix Domain Socket teljes elérési útja. Android, iOS és tvOS rendszeren a cím egy IP-cím és egy port. Példa:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) A futtatókörnyezet a nevesített csőhöz \\.\pipe\my_diag_port1csatlakozik.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux és macOS) A futtatókörnyezet a Unix Domain Sockets /foo/tool1.socket és /foo/tool2.socketa .
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS és tvOS) A futtatókörnyezet a 9000-s porton csatlakozik a 127.0.0.1 IP-címhez.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux és macOS) Ez a példa rendelkezik a nosuspend módosítóval. A futtatókörnyezet megpróbál csatlakozni a külső eszköz által létrehozott Unix Domain Sockethez /foo/tool1.socket . A további diagnosztikai portok általában azt okozzák, hogy a futtatókörnyezet indításkor felfüggesztve vár egy folytatási parancsra, de nosuspend a futtatókörnyezet nem várakozik.

A portok teljes szintaxisa: address[,(listen|connect)][,(suspend|nosuspend)]. connect az alapértelmezett, ha egyik sem connect vagy listen nincs megadva (és listen csak az Android vagy iOS rendszerű Mono futtatókörnyezet támogatja). suspend az alapértelmezett érték, ha egyik sem suspend vagy nosuspend nincs megadva.

Használat a dotnet diagnosztikai eszközeiben

Olyan eszközök, mint a dotnet-dump, a dotnet-counters és a dotnet-trace minden olyan támogatás collect vagy monitor ige, amely a diagnosztikai porton keresztül kommunikál egy .NET-alkalmazással.

• Ha ezek az eszközök az --processId argumentumot használják, az eszköz automatikusan kiszámítja az alapértelmezett diagnosztikai portcímet, és csatlakozik hozzá.
• Az argumentum megadásakor az --diagnostic-port eszköz figyeli a megadott címet, és a DOTNET_DiagnosticPorts környezeti változó használatával konfigurálja az alkalmazást a csatlakozásra. A dotnet-számlálókkal kapcsolatos teljes példáért lásd : A diagnosztikai port használata.

A diagnosztikai port proxyjának használata a ds-router használatával

Az összes dotnet-* diagnosztikai eszköz várhatóan egy helyi nevesített cső vagy Unix Domain Socket nevű diagnosztikai porthoz csatlakozik. A Mono gyakran izolált hardvereken vagy olyan emulátorokon fut, amelyeknek TCP-n keresztüli proxyra van szükségük ahhoz, hogy elérhetőek legyenek. A dotnet-dsrouter eszköz proxyzhat egy helyi nevesített csövet vagy Unix Domain Socketet a TCP-hez, hogy az eszközök használhatók legyenek ezekben a környezetekben. További információ: dotnet-dsrouter.