Diagnoseschnittstellen

Dieser Artikel bezieht sich auf: ✔️ .NET Core 3.1 und höhere Versionen

Die .NET-Runtime macht einen Dienstendpunkt verfügbar, der anderen Prozessen das Senden von Diagnosebefehlen und das Empfangen von Antworten über einen IPC-Kanal ermöglicht. Dieser Endpunkt wird als Diagnoseport bezeichnet. Befehle können zu folgenden Zwecken an den Diagnoseport gesendet werden:

• Erfassen eines Speicherabbilds
• Starten Sie eine EventPipe-Ablaufverfolgung .
• Fordern Sie die zum Starten der App verwendete Befehlszeile an.

Der Diagnoseport unterstützt je nach Plattform unterschiedliche Transporte. Derzeit verwenden sowohl die CoreCLR- als auch mono-Laufzeitimplementierungen Named Pipes unter Windows und Unix Domain Sockets unter Linux und macOS. Die Mono-Laufzeitimplementierung unter Android, iOS und tvOS verwendet TCP/IP. Der Kanal verwendet ein benutzerdefiniertes binäres Protokoll. Die meisten Entwickler interagieren nie direkt mit dem zugrunde liegenden Kanal und Protokoll, sondern verwenden stattdessen GUI- oder CLI-Tools, die in ihrem Auftrag kommunizieren. Beispielsweise abstrahieren die dotnet-dump- und dotnet-trace-Tools das Senden von Protokollbefehlen, um Dumps zu erfassen und Ablaufverfolgungen zu starten. Für Entwickler, die benutzerdefinierte Tools schreiben möchten, stellt das Microsoft.Diagnostics.NETCore.Client NuGet-Paket eine .NET-API-Abstraktion des zugrunde liegenden Transports und Protokolls bereit.

Sicherheitsüberlegungen

Der Diagnoseport macht vertrauliche Informationen zu einer ausgeführten Anwendung verfügbar. Wenn ein nicht vertrauenswürdiger Benutzer Zugriff auf diesen Kanal erhält, könnte er den detaillierten Programmstatus beobachten, einschließlich aller geheimen Schlüssel, die sich im Speicher befinden, und die Ausführung des Programms willkürlich ändern. Auf der CoreCLR-Laufzeit ist der Standarddiagnoseport so konfiguriert, dass nur über dasselbe Benutzerkonto zugegriffen werden kann, auf das die App oder ein Konto mit Superbenutzerberechtigungen gestartet wurde. Wenn Ihr Sicherheitsmodell anderen Prozessen mit denselben Anmeldeinformationen des Benutzerkontos nicht vertraut, können Sie alle Diagnoseports deaktivieren, indem Sie die Umgebungsvariable DOTNET_EnableDiagnostics=0festlegen. Diese Einstellung blockiert die Verwendung externer Tools wie .NET-Debugging oder eines der dotnet-*-Diagnosetools.

Standard-Diagnoseport

Unter Windows, Linux und macOS ist für die Laufzeit standardmäßig ein Diagnoseport an einem bekannten Endpunkt geöffnet. Dies ist der Port, mit dem die dotnet-*-Diagnosetools automatisch verbunden sind, wenn sie nicht explizit für die Verwendung eines alternativen Ports konfiguriert wurden. Der Endpunkt lautet:

• Windows – benannte Pipe \\.\pipe\dotnet-diagnostic-{pid}
• Linux und macOS - Unix Domain Socket {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} ist die Prozess-ID, die in dezimal geschrieben wurde, {temp} ist die TMPDIR Umgebungsvariable oder der Wert /tmp , wenn TMPDIR nicht definiert/leer ist, und {disambiguation_key} ist die Startzeit des Prozesses, der in dezimal geschrieben wurde. Auf macOS und NetBSD ist die Startzeit des Prozesses die Anzahl der Sekunden seit der Unix-Epochenzeit. Auf allen anderen Plattformen ist es seit der Startzeit jiffies.

Anhalten des Runtimes beim Start

Standardmäßig führt die Laufzeit verwalteten Code aus, sobald er gestartet wird, unabhängig davon, ob diagnosetools mit dem Diagnoseport verbunden sind. Manchmal ist es nützlich, die Ausführung verwalteten Codes zu verzögern, bis ein Diagnosetool verbunden ist, um das anfängliche Programmverhalten zu beobachten. Das Festlegen der Umgebungsvariable DOTNET_DefaultDiagnosticPortSuspend=1 bewirkt, dass die Laufzeit wartet, bis ein Tool eine Verbindung mit dem Standardport herstellt. Wenn nach mehreren Sekunden kein Tool angefügt ist, druckt die Laufzeit eine Warnmeldung an die Konsole, in der erläutert wird, dass sie noch auf das Anfügen eines Tools wartet.

Konfigurieren zusätzlicher Diagnoseports

Hinweis

Dies funktioniert nur für Apps mit .NET 5 oder höher.

Sowohl die Mono- als auch die CoreCLR-Laufzeiten können benutzerdefiniert konfigurierte Diagnoseports in der connect Rolle verwenden. Mono unterstützt auch benutzerdefinierte TCP/IP-Ports in der listen Rolle, wenn sie mit dotnet-dsrouter unter Android oder iOS verwendet werden. Diese benutzerdefinierten Ports sind zusätzlich zum Standardport verfügbar. Es gibt einige häufige Gründe, warum benutzerdefinierte Ports nützlich sind:

• Unter Android, iOS und tvOS gibt es keinen Standardport, sodass die Konfiguration eines Ports für die Verwendung von Diagnosetools erforderlich ist.
• In Umgebungen mit Containern oder Firewalls sollten Sie eine vorhersagbare Endpunktadresse einrichten, die nicht basierend auf der Prozess-ID variiert, wie es der Standardport tut. Anschließend kann der benutzerdefinierte Port explizit zu einer Zulassungsliste hinzugefügt oder über einige Sicherheitsgrenzen hinweg proxiziert werden.
• Für Überwachungstools ist es nützlich, dass das Tool auf einen Endpunkt horcht, und die Laufzeitumgebung versucht aktiv, eine Verbindung zu ihm herzustellen. Dadurch wird vermieden, dass das Überwachungstool kontinuierlich nach neuen Apps fragt. In Umgebungen, in denen auf den Standarddiagnoseport nicht zugegriffen werden kann, wird es auch vermieden, den Monitor mit einem benutzerdefinierten Endpunkt für jede überwachte App zu konfigurieren.

In jedem Kommunikationskanal zwischen einem Diagnosetool und der .NET-Laufzeit muss eine Seite der Listener sein und auf die andere Seite warten, um eine Verbindung herzustellen. Die Laufzeit kann so konfiguriert werden, dass sie für jeden Port in der connect Rolle fungiert. Die Mono-Laufzeit kann auch so konfiguriert werden, dass sie für jeden Port in der listen Rolle fungiert. Ports können auch unabhängig konfiguriert werden, um beim Start angehalten zu werden und darauf zu warten, dass ein Diagnosetool einen Fortsetzungsbefehl erteilt. Wenn die entfernte Gegenstelle nicht zuhört oder die Verbindung verloren geht, wiederholen Ports, die für die Verbindung konfiguriert sind, ihre Verbindungsversuche auf unbestimmte Zeit. Die App unterbricht den verwalteten Code jedoch nicht automatisch, während sie darauf wartet, die Verbindung herzustellen. Wenn die App warten soll, bis eine Verbindung hergestellt wird, verwenden Sie die Option zum Anhalten beim Start.

Benutzerdefinierte Ports werden mithilfe der DOTNET_DiagnosticPorts Umgebungsvariablen konfiguriert. Diese Variable sollte auf eine durch Semikolons getrennte Liste mit Portbeschreibungen festgelegt werden. Jede Portbeschreibung besteht aus einer Endpunktadresse und optionalen Modifikatoren, die die Rolle der Laufzeit connect oder listen steuern und festlegen, ob die Laufzeit beim Start angehalten werden soll. Unter Windows ist die Endpunktadresse der Name einer benannten Pipe ohne das \\.\pipe\ Präfix. Unter Linux und macOS ist es der vollständige Pfad zu einem Unix Domain Socket. Unter Android, iOS und tvOS ist die Adresse eine IP und ein Port. Beispiel:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Die Laufzeit stellt eine Verbindung zur benannten Pipe \\.\pipe\my_diag_port1 her.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux und macOS) Die Laufzeit verbindet sich sowohl mit den Unix-Domain-Sockets /foo/tool1.socket als auch mit /foo/tool2.socket.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS und tvOS) Die Laufzeit stellt eine Verbindung mit IP 127.0.0.1 am Port 9000 bereit.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux und macOS) Dieses Beispiel hat den nosuspend Modifizierer. Die Laufzeit versucht, eine Verbindung mit unix Domain Socket /foo/tool1.socket herzustellen, die ein externes Tool erstellt. Zusätzliche Diagnoseports führen normalerweise dazu, dass die Laufzeit beim Start angehalten wird, um auf einen Fortsetzungsbefehl zu warten, nosuspend führt jedoch dazu, dass die Laufzeit nicht wartet.

Die vollständige Syntax für einen Port lautet address[,(listen|connect)][,(suspend|nosuspend)]. connect ist die Standardeinstellung, wenn weder connect noch listen angegeben sind (und listen wird nur vom Mono-Runtime unter Android oder iOS unterstützt). suspend ist die Standardeinstellung, wenn weder suspend noch nosuspend angegeben wird.

Verwendung in dotnet-Diagnosetools

Tools wie dotnet-dump, dotnet-counters und dotnet-trace unterstützen collect- oder monitor-Verben, die an eine .NET-App über den Diagnoseport kommunizieren.

• Wenn diese Tools das --processId Argument verwenden, berechnet das Tool automatisch die Standardadresse des Diagnoseports und stellt eine Verbindung mit ihr bereit.
• Wenn Sie das --diagnostic-port Argument angeben, lauscht das Tool an der angegebenen Adresse, und Sie sollten die DOTNET_DiagnosticPorts Umgebungsvariable verwenden, um Ihre App für die Verbindung zu konfigurieren. Ein vollständiges Beispiel mit Dotnet-Zählern finden Sie unter Verwenden des Diagnoseports.

Verwenden Sie ds-router als Proxy für den Diagnoseport

Alle dotnet-*-Diagnosetools sind dafür ausgelegt, sich mit einem Diagnoseport zu verbinden, der eine lokale Named Pipe oder ein Unix Domain Socket ist. Mono wird häufig auf isolierter Hardware oder in Emulatoren ausgeführt, die einen Proxy über TCP benötigen, um darauf zugreifen zu können. Das dotnet-dsrouter-Tool kann eine lokale Named Pipe oder Unix Domain Socket auf TCP umleiten, sodass die Tools in diesen Umgebungen genutzt werden können. Weitere Informationen finden Sie unter dotnet-dsrouter.