dotnet-dsrouter

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

Installer

Pour installer la dernière version de version du dotnet-dsrouter package NuGet, utilisez la commande installation de l’outil dotnet :

dotnet tool install --global dotnet-dsrouter

Synopsis

dotnet-dsrouter [-?, -h, --help] [--version] <command>

Description

La commande dotnet-dsrouter connecte des outils de diagnostic tels que dotnet-trace et dotnet-counters aux applications .NET s’exécutant sur Android, iOS et tvOS, qu’ils s’exécutent en tant qu’émulateur, simulateur ou sur l’appareil lui-même. Les outils de diagnostic utilisent la communication interprocessus local (IPC) (canal nommé, socket de domaine Unix) pour se connecter et communiquer avec un runtime .NET. Les applications .NET qui s’exécutent dans des environnements en bac à sable (sandbox) sur des émulateurs, des simulateurs et des appareils ont besoin d’autres moyens de communiquer. Le dotnet-dsrouter s’injecte entre les outils de diagnostic existants et les applications mobiles .NET et crée une représentation locale de l’application. Le dotnet-dsrouter permet aux outils de diagnostic de communiquer avec un runtime .NET distant comme s’il s’exécutait sur l’ordinateur local.

La communication entre les outils de diagnostic et dotnet-dsrouter utilise le même IPC (canal nommé, socket de domaine Unix) que celui utilisé lors de la connexion à un runtime .NET local. dotnet-dsrouter utilise TCP/IP dans sa communication avec le runtime .NET distant et prend en charge plusieurs scénarios de connectivité différents pour gérer différents besoins et exigences utilisés par différentes plateformes. dotnet-dsrouter implémente également une prise en charge supplémentaire pour simplifier la configuration de la connectivité lors de l’exécution dans l’émulateur, le simulateur et sur un appareil physique attaché via USB.

Notes

dotnet-dsrouter est destiné au développement et aux tests et il est fortement recommandé d’exécuter dotnet-dsrouter sur l’interface de bouclage (par exemple, 127.0.0.1, [::1]). Les fonctionnalités de connectivité et de transfert de port de dotnet-dsrouter gèrent tous les scénarios utilisant un émulateur local, un simulateur ou un appareil physique connecté via USB.

Avertissement

Lier le point de terminaison du serveur TCP à quelque chose d’autre que l’interface de bouclage (localhost, 127.0.0.1 ou [::1]) n’est pas recommandé. Toutes les connexions au point de terminaison de serveur TCP ne sont ni authentifiées ni chiffrées. dotnet-dsrouter est destiné au développement et ne doit être exécuté que dans les environnements de développement et de test.

L’utilisation détaillée de dotnet-dsrouter conjointement avec les applications mobiles est décrite par les kits de développement logiciel (SDK) .NET respectifs. Ce document n’inclut que quelques exemples sur l’exécution d’outils de diagnostic sur une application .NET exécutée sous Android. Pour plus d’informations détaillées sur la configuration et les scénarios, consultez Suivi des diagnostics.

Options

• -?|-h|--help

  Affiche l’aide de la ligne de commande.

• --version

  Affiche la version de l’utilitaire dotnet-dsrouter.

Commandes

Commande
dotnet-dsrouter client-server
dotnet-dsrouter server-server
dotnet-dsrouter server-client
dotnet-dsrouter client-client

dotnet-dsrouter client-server

Démarrez un serveur de diagnostics d’application .NET qui achemine le serveur IPC local et le client TCP distant. Le routeur est configuré à l’aide d’un client IPC (serveur IPC de l’outil de diagnostic de connexion) et d’un serveur TCP/IP (acceptant le client TCP du runtime).

Synopsis

dotnet-dsrouter client-server
    [-ipcc|--ipc-client <ipcClient>]
    [-tcps|--tcp-server <tcpServer>]
    [-rt|--runtime-timeout <timeout>]
    [-v|--verbose <level>]
    [-fp|--forward-port <platform>]

Options

• -ipcc, --ipc-client <ipcClient>

  Spécifie l’adresse IPC du serveur de diagnostic de l’outil de diagnostic (argument --diagnostic-port). Le routeur se connecte au serveur IPC de l’outil de diagnostic lors de l’établissement d’un nouvel itinéraire entre le runtime et l’outil de diagnostic.

• -tcps, --tcp-server <tcpServer>

  Spécifie l’adresse TCP/IP du routeur au format [host]:[port]. Le routeur peut lier une interface (127.0.0.1, [::1], 0.0.0.0, [::], adresse IPv4, adresse IPv6, nom d’hôte) ou toutes les interfaces (*). Lance le runtime à l’aide de la variable d’environnement DOTNET_DiagnosticPorts et connecte le serveur TCP du routeur au démarrage.

• -rt, --runtime-timeout <runtimeTimeout>

  Arrête automatiquement le routeur si aucun runtime ne s’y connecte avant le délai d’expiration spécifié (en secondes). S’il n’est pas spécifié, le routeur ne déclenche pas d’arrêt automatique.

• -v, --verbose <verbose>

  Active la journalisation détaillée (débogage|suivi).

• -fp, --forward-port <forwardPort>

  Active le transfert de port. Les valeurs sont Android ou iOS pour TcpClient et uniquement Android pour TcpServer. Veillez à définir ANDROID_SDK_ROOT avant d’utiliser cette option sur Android.

dotnet-dsrouter server-server

Démarrez un serveur de diagnostics d’application .NET qui achemine le client IPC local et le client TCP distant. Le routeur est configuré à l’aide d’un serveur IPC (qui se connecte aux outils de diagnostic) et d’un serveur TCP/IP (qui accepte le client TCP du runtime).

Synopsis

dotnet-dsrouter server-server
    [-ipcs|--ipc-server <ipcServer>]
    [-tcps|--tcp-server <tcpServer>]
    [-rt|--runtime-timeout <timeout>]
    [-v|--verbose <level>]
    [-fp|--forward-port <platform>]

Options

• -ipcs, --ipc-server <ipcServer>

  Adresse IPC du serveur de diagnostics à acheminer. Le routeur accepte les connexions IPC des outils de diagnostic qui établissent un nouvel itinéraire entre le runtime et l’outil de diagnostic. S’il n’est pas spécifié, le routeur utilise le chemin du serveur de diagnostics IPC par défaut.

• -tcps, --tcp-server <tcpServer>

  Adresse TCP/IP du routeur au format [host]:[port]. Le routeur peut lier une interface (127.0.0.1, [::1], 0.0.0.0, [::], adresse IPv4, adresse IPv6, nom d’hôte) ou toutes les interfaces (*). Lancez le runtime à l’aide d’une variable d’environnement DOTNET_DiagnosticPorts, en connectant le serveur TCP du routeur au démarrage.

• -rt, --runtime-timeout <runtimeTimeout>

  Arrête automatiquement le routeur si aucun runtime ne s’y connecte avant le délai d’expiration spécifié (en secondes). S’il n’est pas spécifié, le routeur ne déclenche pas d’arrêt automatique.

• -v, --verbose <verbose>

  Active la journalisation détaillée (débogage|suivi).

• -fp, --forward-port <forwardPort>

  Active le transfert de port. Les valeurs sont Android ou iOS pour TcpClient et uniquement Android pour TcpServer. Veillez à définir ANDROID_SDK_ROOT avant d’utiliser cette option sur Android.

dotnet-dsrouter server-client

Démarrez un serveur de diagnostics d’application .NET qui achemine le client IPC local et le serveur TCP distant. Le routeur est configuré à l’aide d’un serveur IPC (qui se connecte aux outils de diagnostic) et d’un client TCP/IP (qui se connecte au serveur TCP du runtime).

Synopsis

dotnet-dsrouter server-client
    [-ipcs|--ipc-server <ipcServer>]
    [-tcpc|--tcp-client <tcpClient>]
    [-rt|--runtime-timeout <timeout>]
    [-v|--verbose <level>]
    [-fp|--forward-port <platform>]

Options

• -ipcs, --ipc-server <ipcServer>

  Adresse IPC du serveur de diagnostics à acheminer. Le routeur accepte les connexions IPC des outils de diagnostic qui établissent un nouvel itinéraire entre le runtime et l’outil de diagnostic. S’il n’est pas spécifié, le routeur utilise le chemin du serveur de diagnostics IPC par défaut.

• -tcpc, --tcp-client <tcpClient>

  Adresse TCP/IP du runtime au format [host]:[port]. Le routeur peut connecter 127.0.0.1, [::1], adresse IPv4, adresse IPv6, adresses de nom d’hôte. Lancez le runtime à l’aide de la variable d’environnement DOTNET_DiagnosticPorts pour configurer l’écouteur.

• -rt, --runtime-timeout <runtimeTimeout>

  Arrête automatiquement le routeur si aucun runtime ne s’y connecte avant le délai d’expiration spécifié (en secondes). S’il n’est pas spécifié, le routeur ne déclenche pas d’arrêt automatique.

• -v, --verbose <verbose>

  Active la journalisation détaillée (débogage|suivi).

• -fp, --forward-port <forwardPort>

  Active le transfert de port. Les valeurs sont Android ou iOS pour TcpClient et uniquement Android pour TcpServer. Veillez à définir ANDROID_SDK_ROOT avant d’utiliser cette option sur Android.

dotnet-dsrouter client-client

Démarrez un serveur de diagnostics d’application .NET qui achemine le serveur IPC local et le client TCP distant. Le routeur est configuré à l’aide d’un client IPC (qui se connecte au serveur IPC de l’outil de diagnostic) et d’un client TCP/IP (qui accepte le serveur TCP du runtime).

Synopsis

dotnet-dsrouter client-client
    [-ipcc|--ipc-client <ipcClient>]
    [-tcpc|--tcp-client <tcpClient>]
    [-rt|--runtime-timeout <timeout>]
    [-v|--verbose <level>]
    [-fp|--forward-port <platform>]

Options

• -ipcc, --ipc-client <ipcClient>

  Adresse IPC du serveur de diagnostic de l’outil de diagnostic (--diagnostic-port argument). Le routeur se connecte au serveur IPC de l’outil de diagnostic lors de l’établissement d’un nouvel itinéraire entre le runtime et l’outil de diagnostic.

• -tcpc, --tcp-client <tcpClient>

  Adresse TCP/IP du runtime au format [host]:[port]. Le routeur peut connecter 127.0.0.1, [::1], adresse IPv4, adresse IPv6, adresses de nom d’hôte. Lancez le runtime à l’aide de la variable d’environnement DOTNET_DiagnosticPorts pour configurer l’écouteur.

• -rt, --runtime-timeout <runtimeTimeout>

  Arrête automatiquement le routeur si aucun runtime ne s’y connecte avant le délai d’expiration spécifié (en secondes). S’il n’est pas spécifié, le routeur ne déclenche pas d’arrêt automatique.

• -v, --verbose <verbose>

  Active la journalisation détaillée (débogage|suivi).

• -fp, --forward-port <forwardPort>

  Active le transfert de port. Les valeurs sont Android ou iOS pour TcpClient et uniquement Android pour TcpServer. Veillez à définir ANDROID_SDK_ROOT avant d’utiliser cette option sur Android.

Collecter une trace de démarrage à l’aide de dotnet-trace à partir d’une application .NET s’exécutant sur Android

Il peut parfois être utile de collecter une trace d’une application à partir de son démarrage. Les étapes suivantes illustrent le processus pour le faire, en ciblant une application .NET s’exécutant sur Android. Étant donné que dotnet-dsrouter est exécuté à l’aide du transfert de port, le même scénario fonctionne sur les applications s’exécutant sur un émulateur local et sur un appareil physique attaché via USB. Veillez à définir ANDROID_SDK_ROOT avant d’utiliser cette option ou dotnet-dsrouter ne sera pas en mesure de trouver adb nécessaire pour configurer le transfert de port.

• Lancez dotnet-dsrouter en mode serveur-serveur :

  dotnet-dsrouter server-server -ipcs ~/mylocalport -tcps 127.0.0.1:9000 --forward-port Android &
  

• Définir la variable d’environnement DOTNET_DiagnosticPorts en utilisant AndroidEnvironment :

  Créez un fichier dans le même répertoire que .csproj en utilisant un nom tel que app.env, ajoutez des variables d’environnement dans le fichier DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend et incluez les éléments suivants ItemGroup dans .csproj :

  <ItemGroup Condition="'$(AndroidEnableProfiler)'=='true'">
    <AndroidEnvironment Include="app.env" />
  </ItemGroup>
  

  Il est également possible de définir DOTNET_DiagnosticPorts en utilisant adb shell setprop :

  adb shell setprop debug.mono.profile '127.0.0.1:9000,suspend'
  

• Générez et lancez l’application à l’aide du Kit de développement logiciel (SDK) Android .NET, puis activez le suivi en passant /p:AndroidEnableProfiler=true à MSBuild. Étant donné que l’application a été configurée pour être suspendue au démarrage, elle se reconnecte à l’écouteur dotnet-dsrouter TCP/IP en cours d’exécution sur 127.0.0.1:9000 et attend que les outils de diagnostic se connectent avant de reprendre l’exécution de l’application.

• Démarrez dotnet-trace en mode collecte, en vous connectant au serveur IPC dotnet-dsrouter, ~/mylocalport :

    dotnet-trace collect --diagnostic-port ~/mylocalport,connect
  

dotnet-trace démarre une session de suivi et reprend l’application qui va maintenant continuer à s’exécuter. Un flux d’événements commence à circuler de l’application mobile via dotnet-dsrouter jusqu’au fichier nettrace dotnet-trace. Une fois le suivi terminé, appuyez sur Entrée pour vous assurer que la session de suivi est correctement fermée, ce qui garantit que le fichier nettrace inclut toutes les données nécessaires avant la fermeture de l’application.

Il est possible d’exécuter plusieurs sessions de suivi sur la même application en cours d’exécution au fil du temps, de laisser dotnet-dsrouter en cours d’exécution et de réexécuter dotnet-trace lorsqu’une nouvelle session de suivi est nécessaire.

dotnet-dsrouter peut être laissé en cours d’exécution en arrière-plan et réutilisé si une application est configurée pour se connecter à l’aide de son adresse et de son port.

dotnet-dsrouter est lié à une application en cours d’exécution à tout moment. S’il est nécessaire de suivre plusieurs applications différentes en même temps, chaque application doit utiliser sa propre instance dotnet-dsrouter, en configurant une paire d’adresses IP/TCP unique dans dotnet-dsrouter et en configurant différentes instances d’application pour se reconnecter à son instance unique dotnet-dsrouter .

Si dotnet-dsrouter est exécuté avec --forward-port qui cible Android et le serveur adb, l’émulateur ou l’appareil redémarre, toutes les instances dotnet-dsrouter doivent également être redémarrées pour restaurer les règles de transfert de port.

Lorsque vous avez terminé d’utiliser dotnet-dsrouter, appuyez sur Q ou Ctrl + C pour quitter l’application.

Notes

Lors de l’exécution de dotnet-dsrouter sous Windows, il utilise des canaux nommés pour son canal IPC. Remplacez ~/mylocalport par mylocalport dans les exemples ci-dessus lors de l’exécution sous Windows.

Notes

Le port TCP/IP 9000 n’est qu’un exemple. Tout port TCP/IP gratuit peut être utilisé.

Notes

Le socket de domaine Unix ~/mylocalport n’est qu’un exemple. Tout chemin de fichier de socket de domaine Unix gratuit peut être utilisé.

Collecter une trace à l’aide de dotnet-trace à partir d’une application .NET s’exécutant sur Android

S’il n’est pas nécessaire de collecter une trace au démarrage de l’application, il est possible de lancer l’application en mode nosuspend, ce qui signifie que le runtime ne bloque pas au démarrage en attendant que les outils de diagnostic se connectent avant de reprendre l’exécution. La plupart du scénario décrit ci-dessus s’applique également à ce mode, remplacez simplement suspend par nosuspend dans la variable d’environnement DOTNET_DiagnosticPorts pour lancer l’application en mode nosuspend.

Voir aussi

• Suivi Android .NET
• Suivi MAUI .NET
• Suivi de diagnostics .NET sur mobile