Diagnostikportar

Artikel
09/22/2023

Den här artikeln gäller för: ✔️ .NET Core 3.1 och senare versioner

.NET-körningen exponerar en tjänstslutpunkt som gör att andra processer kan skicka diagnostikkommandon och ta emot svar via en IPC-kanal. Den här slutpunkten kallas för en diagnostikport. Kommandon kan skickas till diagnostikporten för att:

Samla in en minnesdump.
Starta en EventPipe-spårning .
Begär den kommandorad som används för att starta appen.

Diagnostikporten stöder olika transporter beroende på plattform. För närvarande använder både CoreCLR- och Mono-körningsimplementeringar namngivna pipes i Windows och Unix Domain Sockets i Linux och macOS. Mono-körningsimplementeringen på Android, iOS och tvOS använder TCP/IP. Kanalen använder ett anpassat binärt protokoll. De flesta utvecklare interagerar aldrig direkt med den underliggande kanalen och protokollet, utan använder i stället GUI- eller CLI-verktyg som kommunicerar åt dem. Till exempel abstraherar dotnet-dump - och dotnet-trace-verktygen och skickar protokollkommandon för att samla in dumpar och starta spårningar. För utvecklare som vill skriva anpassade verktyg tillhandahåller NuGet-paketet Microsoft.Diagnostics.NETCore.Client en .NET API-abstraktion av den underliggande transporten och protokollet.

Säkerhetsfrågor

Diagnostikporten exponerar känslig information om ett program som körs. Om en ej betrodd användare får åtkomst till den här kanalen kan de observera detaljerat programtillstånd, inklusive eventuella hemligheter som finns i minnet, och godtyckligt ändra körningen av programmet. På CoreCLR-körningen är standarddiagnostikporten konfigurerad att endast vara tillgänglig för samma användarkonto som startade appen eller med ett konto med superanvändarbehörighet. Om din säkerhetsmodell inte litar på andra processer med samma autentiseringsuppgifter för användarkontot kan du inaktivera alla diagnostikportar genom att ange miljövariabeln DOTNET_EnableDiagnostics=0. Den här inställningen blockerar möjligheten att använda externa verktyg, till exempel .NET-felsökning eller något av diagnostikverktygen dotnet-*.

Kommentar

.NET 6 standardiserar på prefixet DOTNET_ i stället COMPlus_ för för miljövariabler som konfigurerar .NET-körningsbeteende. Prefixet COMPlus_ fortsätter dock att fungera. Om du använder en tidigare version av .NET-körningen bör du fortfarande använda prefixet COMPlus_ för miljövariabler.

Standarddiagnostikport

I Windows, Linux och macOS har körningen en diagnostikport öppen som standard på en välkänd slutpunkt. Det här är den port som dotnet-*-diagnostikverktygen ansluter till automatiskt när de inte uttryckligen har konfigurerats för att använda en alternativ port. Slutpunkten är:

Windows – namngiven pipe \\.\pipe\dotnet-diagnostic-{pid}
Linux och macOS – Unix Domain Socket {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} är process-ID:t skrivet med decimaltecken, {temp} är TMPDIR miljövariabeln eller värdet /tmp om TMPDIR det är odefinierat/tomt och {disambiguation_key} är processens starttid skriven i decimal. På macOS och NetBSD är processens starttid antal sekunder sedan UNIX-epoktiden. På alla andra plattformar är det jiffies sedan starttiden.

Pausa körningen vid start

Som standard kör körningen hanterad kod så snart den startar, oavsett om några diagnostikverktyg har anslutit till diagnostikporten. Ibland är det bra att vänta med att köra hanterad kod tills ett diagnostikverktyg har anslutits för att observera det inledande programbeteendet. Om du ställer in miljövariabeln DOTNET_DefaultDiagnosticPortSuspend=1 väntar körningen tills ett verktyg ansluter till standardporten. Om inget verktyg är anslutet efter flera sekunder skriver körningen ut ett varningsmeddelande till konsolen som förklarar att det fortfarande väntar på att ett verktyg ska anslutas.

Konfigurera ytterligare diagnostikportar

Kommentar

Detta fungerar endast för appar som kör .NET 5 eller senare.

Både Mono- och CoreCLR-körningen kan använda anpassade konfigurerade diagnostikportar i connect rollen. Mono stöder också anpassade TCP/IP-portar i rollen, när de listen används med dotnet-dsrouter på Android eller iOS. Dessa anpassade portar är utöver den standardport som fortfarande är tillgänglig. Det finns några vanliga orsaker till att anpassade portar är användbara:

På Android, iOS och tvOS finns det ingen standardport, så det är nödvändigt att konfigurera en port för att använda diagnostikverktyg.
I miljöer med containrar eller brandväggar kanske du vill konfigurera en förutsägbar slutpunktsadress som inte varierar beroende på process-ID som standardporten gör. Sedan kan den anpassade porten uttryckligen läggas till i en lista över tillåtna eller över vissa säkerhetsgränser.
För övervakningsverktyg är det användbart att låta verktyget lyssna på en slutpunkt, och körningen försöker aktivt ansluta till den. Detta gör att du inte behöver övervakningsverktyget för att kontinuerligt söka efter nya appar som startar. I miljöer där standarddiagnostikporten inte är tillgänglig undviker den också att behöva konfigurera övervakaren med en anpassad slutpunkt för varje övervakad app.

I varje kommunikationskanal mellan ett diagnostikverktyg och .NET-körningen måste den ena sidan vara lyssnaren och vänta tills den andra sidan ansluter. Körningen kan konfigureras för att fungera i connect rollen för valfri port. (Mono-körningen kan också konfigureras för att fungera i listen rollen för valfri port.) Portar kan också konfigureras separat så att de pausas vid start och väntar på att ett diagnostikverktyg ska utfärda ett återuppta-kommando. Portar som konfigurerats för att ansluta upprepar sina anslutningsförsök på obestämd tid om fjärrslutpunkten inte lyssnar eller om anslutningen går förlorad. Men appen pausar inte automatiskt hanterad kod i väntan på att upprätta anslutningen. Om du vill att appen ska vänta tills en anslutning har upprättats använder du alternativet Pausa vid start.

Anpassade portar konfigureras med hjälp av DOTNET_DiagnosticPorts miljövariabeln. Den här variabeln ska anges till en semikolonavgränsad lista med portbeskrivningar. Varje portbeskrivning består av en slutpunktsadress och valfria modifierare som styr körningens connect eller listen rollen och om körningen ska pausas vid start. I Windows är slutpunktsadressen namnet på ett namngivet rör utan prefixet \\.\pipe\ . I Linux och macOS är det den fullständiga sökvägen till en Unix Domain Socket. På Android, iOS och tvOS är adressen en IP-adress och port. Till exempel:

DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Körningen ansluter till det namngivna röret \\.\pipe\my_diag_port1.
DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket – (Linux och macOS) Körningen ansluter till både Unix Domain Sockets /foo/tool1.socket och /foo/tool2.socket.
DOTNET_DiagnosticPorts=127.0.0.1:9000 – (Android, iOS och tvOS) Körningen ansluter till IP 127.0.0.1 på port 9000.
DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend – (Linux och macOS) Det här exemplet har nosuspend modifieraren. Körningen försöker ansluta till Unix Domain Socket /foo/tool1.socket som ett externt verktyg skapar. Ytterligare diagnostikportar skulle normalt göra att körningen pausas vid start i väntan på ett återuppta-kommando, men nosuspend gör att körningen inte väntar.

Den fullständiga syntaxen för en port är address[,(listen|connect)][,(suspend|nosuspend)]. connect är standardvärdet om inget av connect dem eller listen anges (och listen stöds endast av Mono-körningen på Android eller iOS). suspend är standardvärdet om inget av suspend dem eller nosuspend anges.

Användning i dotnet-diagnostikverktyg

Verktyg som dotnet-dump, dotnet-counters och dotnet-trace alla stöd collect eller monitor verb som kommunicerar till en .NET-app via diagnostikporten.

När dessa verktyg använder --processId argumentet beräknar verktyget automatiskt standardadressen för diagnostikporten och ansluter till den.
När du anger --diagnostic-port argumentet lyssnar verktyget på den angivna adressen och du bör använda DOTNET_DiagnosticPorts miljövariabeln för att konfigurera appen att ansluta. Ett fullständigt exempel med dotnet-counters finns i Använda diagnostikporten.

Använda ds-router för att proxyhantera diagnostikporten

Alla dotnet-* diagnostikverktyg förväntar sig att ansluta till en diagnostikport som är en lokal namngiven pipe eller Unix Domain Socket. Mono körs ofta på isolerad maskinvara eller i emulatorer som behöver en proxy över TCP för att bli tillgänglig. Verktyget dotnet-dsrouter kan proxya en lokal namngiven pipe eller Unix Domain Socket till TCP så att verktygen kan användas i dessa miljöer. Mer information finns i dotnet-dsrouter.

Dela via