Ports de diagnostic

Cet article s’applique à : ✔️ .NET Core 3.1 et versions ultérieures

Le runtime .NET expose un point de terminaison de service qui permet à d’autres processus d’envoyer des commandes de diagnostic et de recevoir des réponses sur un canal IPC. Ce point de terminaison est appelé port de diagnostic. Les commandes peuvent être envoyées au port de diagnostic vers :

• Capturez une image mémoire.
• Démarrez une trace EventPipe.
• Demandez la ligne de commande utilisée pour lancer l’application.

Le port de diagnostic prend en charge différents transports en fonction de la plateforme. Actuellement, les implémentations CoreCLR et Mono runtime utilisent des canaux nommés sur Windows et des sockets de domaine Unix sur Linux et macOS. L’implémentation du runtime Mono sur Android, iOS et tvOS utilise TCP/IP. Le canal utilise un protocole binaire personnalisé. La plupart des développeurs n’interagissent jamais directement avec le canal et le protocole sous-jacents, mais utilisent plutôt des outils GUI ou CLI qui communiquent en leur nom. Par exemple, les outils dotnet-dump et dotnet-trace résument l’envoi de commandes de protocole pour capturer des vidages et démarrer des traces. Pour les développeurs qui souhaitent écrire des outils personnalisés, le package NuGet Microsoft.Diagnostics.NETCore.Client fournit une abstraction d’API .NET du transport et du protocole sous-jacents.

Considérations relatives à la sécurité

Le port de diagnostic expose des informations sensibles sur une application en cours d’exécution. Si un utilisateur non approuvé accède à ce canal, il peut observer l’état détaillé du programme, y compris les secrets en mémoire et modifier arbitrairement l’exécution du programme. Sur le runtime CoreCLR, le port de diagnostic par défaut est configuré pour être accessible uniquement par le même compte d’utilisateur qui a lancé l’application ou par un compte disposant d’autorisations super-utilisateur. Si votre modèle de sécurité n’approuve pas d’autres processus avec les mêmes informations d’identification de compte d’utilisateur, vous pouvez désactiver tous les ports de diagnostic en définissant la variable DOTNET_EnableDiagnostics=0d’environnement. Ce paramètre bloque votre capacité à utiliser des outils externes tels que le débogage .NET ou l’un des outils de diagnostic dotnet-*.

Port de diagnostic par défaut

Sur Windows, Linux et macOS, le runtime dispose d’un port de diagnostic ouvert par défaut sur un point de terminaison connu. Il s’agit du port auquel les outils de diagnostic dotnet-* se connectent automatiquement lorsqu’ils n’ont pas été configurés explicitement pour utiliser un autre port. Le point de terminaison est :

• Windows - Tube nommé \\.\pipe\dotnet-diagnostic-{pid}
• Linux et macOS - Socket de domaine Unix {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} est l’ID de processus écrit en décimal, {temp} est la TMPDIR variable d’environnement ou la valeur /tmp si TMPDIR elle n’est pas définie/vide, et {disambiguation_key} est l’heure de début du processus écrite en décimale. Sur macOS et NetBSD, l'heure de début du processus est le nombre de secondes depuis le début de l'époque UNIX. Sur toutes les autres plateformes, il s’agit de jiffies depuis le temps de démarrage.

Suspendre le runtime au démarrage

Par défaut, le runtime exécute du code managé dès qu’il démarre, quel que soit l’outil de diagnostic connecté au port de diagnostic. Parfois, il est utile d’attendre que le runtime exécute du code managé jusqu’à ce qu’un outil de diagnostic soit connecté, pour observer le comportement initial du programme. La définition de la variable DOTNET_DefaultDiagnosticPortSuspend=1 d’environnement entraîne l’attente du runtime jusqu’à ce qu’un outil se connecte au port par défaut. Si aucun outil n’est attaché après plusieurs secondes, le runtime imprime un message d’avertissement dans la console expliquant qu’il attend toujours qu’un outil s’attache.

Configurer des ports de diagnostic supplémentaires

Les environnements d'exécution Mono et CoreCLR peuvent utiliser des ports de diagnostic configurés sur mesure dans le rôle connect. Mono prend également en charge les ports TCP/IP personnalisés dans le listen rôle, lorsqu’il est utilisé avec dotnet-dsrouter sur Android ou iOS. Ces ports personnalisés sont en plus du port par défaut qui reste disponible. Il existe quelques raisons courantes pour lesquelles les ports personnalisés sont utiles :

• Sur Android, iOS et tvOS, il n’existe aucun port par défaut. La configuration d’un port est donc nécessaire pour utiliser les outils de diagnostic.
• Dans les environnements avec des conteneurs ou des pare-feu, vous pouvez configurer une adresse de point de terminaison prévisible qui ne varie pas en fonction de l’ID de processus comme le port par défaut. Ensuite, le port personnalisé peut être explicitement ajouté à une liste d'autorisation ou redirigé par un proxy à travers une frontière de sécurité.
• Pour les outils de surveillance, il est utile que l'outil écoute sur un point de terminaison, et que le runtime tente activement de s'y connecter. Cela évite d’avoir besoin de l’outil de surveillance pour sonder continuellement les applications qui démarrent. Dans les environnements où le port de diagnostic par défaut n’est pas accessible, il évite également de devoir configurer le moniteur avec un point de terminaison personnalisé pour chaque application surveillée.

Dans chaque canal de communication entre un outil de diagnostic et le runtime .NET, un côté doit être l’écouteur et attendre que l’autre côté se connecte. Le runtime peut être configuré pour agir dans le connect rôle pour n’importe quel port. (Le runtime Mono peut également être configuré pour agir dans le listen rôle pour n’importe quel port.) Les ports peuvent également être configurés indépendamment pour interrompre au démarrage, en attendant qu’un outil de diagnostic émette une commande de reprise. Les ports configurés pour se connecter répètent indéfiniment leurs tentatives de connexion si le point de terminaison distant n’écoute pas ou si la connexion est perdue. Toutefois, l’application ne suspend pas automatiquement le code managé en attendant d’établir cette connexion. Si vous souhaitez que l’application attende l’établissement d’une connexion, utilisez l’option suspendre au démarrage.

Les ports personnalisés sont configurés à l’aide de la variable d’environnement DOTNET_DiagnosticPorts . Cette variable doit être définie sur une liste délimitée par des points-virgules des descriptions de port. Chaque description de port se compose d'une adresse de point de terminaison et de modificateurs facultatifs qui contrôlent le rôle du runtime et indiquent si ce dernier doit être suspendu au démarrage. Sur Windows, l’adresse du point de terminaison est le nom d’un canal nommé sans le \\.\pipe\ préfixe. Sur Linux et macOS, il s’agit du chemin complet d’un socket de domaine Unix. Sur Android, iOS et tvOS, l’adresse est une adresse IP et un port. Par exemple:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) Le runtime se connecte au canal \\.\pipe\my_diag_port1nommé .
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux et macOS) Le runtime se connecte aux sockets /foo/tool1.socket de domaine Unix et /foo/tool2.socket.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS et tvOS) Le runtime se connecte à IP 127.0.0.1 sur le port 9000.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux et macOS) Cet exemple a le nosuspend modificateur. Le runtime tente de se connecter au socket /foo/tool1.socket de domaine Unix qu’un outil externe crée. Des ports de diagnostic supplémentaires provoqueraient normalement la suspension du runtime au démarrage en attente d’une commande de reprise, mais nosuspend fait que le runtime n’attend pas.

La syntaxe complète d’un port est address[,(listen|connect)][,(suspend|nosuspend)]. connect est la valeur par défaut si ni connect ni listen ne sont spécifiés (et listen n’est prise en charge que par le runtime Mono sur Android ou iOS). suspend est la valeur par défaut si ni suspend ni nosuspend ne sont spécifiés.

Utilisation dans les outils de diagnostic dotnet

Les outils tels que dotnet-dump, dotnet-counters et dotnet-trace prennent tous en charge des verbes collect ou monitor qui communiquent avec une application .NET via le port de diagnostic.

• Lorsque ces outils utilisent l’argument --processId , l’outil calcule automatiquement l’adresse de port de diagnostic par défaut et se connecte à celui-ci.
• Lorsque vous spécifiez l’argument --diagnostic-port , l’outil écoute à l’adresse donnée et vous devez utiliser la DOTNET_DiagnosticPorts variable d’environnement pour configurer votre application pour se connecter. Pour obtenir un exemple complet avec dotnet-counters, consultez Utilisation du port de diagnostic.

Utiliser ds-router pour proxyr le port de diagnostic

Tous les outils de diagnostic dotnet-* s’attendent à se connecter à un port de diagnostic qui est un canal nommé local ou un socket de domaine Unix. Mono s’exécute souvent sur du matériel isolé ou dans des émulateurs qui ont besoin d’un proxy sur TCP pour devenir accessible. L’outil dotnet-dsrouter peut proxyer un canal nommé local ou un socket de domaine Unix vers TCP afin que les outils puissent être utilisés dans ces environnements. Pour plus d’informations, consultez dotnet-dsrouter.