Freigeben über

dotnet-dsrouter

  • Artikel

Dieser Artikel gilt für: ✔️ .NET 6.0 SDK und höhere Versionen

Installieren

Verwenden Sie zum Installieren der neuesten Releaseversion des NuGet-Pakets dotnet-dsrouter den Befehl dotnet tool install:

dotnet tool install --global dotnet-dsrouter

Übersicht

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

Beschreibung

dotnet-dsrouter verbindet Diagnosetools wie dotnet-trace und dotnet-counters mit .NET-Anwendungen, die unter Android, iOS und tvOS ausgeführt werden, unabhängig davon, ob sie als Emulator, Simulator oder auf dem Gerät selbst ausgeführt werden. Diagnosetools verwenden die lokale Kommunikation zwischen Prozessen (IPC) (Named Pipe, Unix Domain Socket), um eine Verbindung mit einer .NET-Runtime herzustellen und mit ihr zu kommunizieren. .NET-Anwendungen, die in Sandboxumgebungen auf Emulatoren, Simulatoren und Geräten ausgeführt werden, benötigen alternative Kommunikationsmöglichkeiten. dotnet-dsrouter fügt sich selbst zwischen vorhandenen Diagnosetools und mobilen .NET-Anwendungen ein und erstellt eine lokale Darstellung der Anwendung. dotnet-dsrouter ermöglicht Diagnosetools die Kommunikation mit einer .NET-Remoteruntime, als ob diese auf dem lokalen Computer ausgeführt würde.

Die Kommunikation zwischen Diagnosetools und dotnet-dsrouter verwendet die gleiche IPC (Named Pipe, Unix Domain Socket), die beim Herstellen einer Verbindung mit einer lokalen .NET-Runtime verwendet wird. dotnet-dsrouter verwendet TCP/IP in der Kommunikation mit der .NET-Remoteruntime und unterstützt verschiedene Konnektivitätsszenarien, um verschiedene Anforderungen zu erfüllen, die von verschiedenen Plattformen gestellt werden. dotnet-dsrouter implementiert außerdem zusätzliche Unterstützung, um die Konnektivitätskonfiguration zu vereinfachen, wenn die Ausführung in einem Emulator, in einem Simulator bzw. auf einem physischen Gerät erfolgt, das über USB angeschlossen ist.

Hinweis

dotnet-dsrouter ist für Entwicklung und Tests vorgesehen, und es wird dringend empfohlen, dotnet-dsrouter über eine Loopbackschnittstelle (z. B. 127.0.0.1, [::1]) auszuführen. Die Konnektivitätsfeatures und Portweiterleitungsfunktionen von dotnet-dsrouter verarbeiten alle Szenarien mit dem lokalen Emulator, Simulator oder physischen Gerät, das über USB verbunden ist.

Warnung

Das Binden des TCP-Serverendpunkts an etwas anderes außer der Loopbackschnittstelle (localhost, 127.0.0.1 oder [::1]) wird nicht empfohlen. Alle Verbindungen mit dem TCP-Serverendpunkt sind nicht authentifiziert und unverschlüsselt. dotnet-dsrouter ist für die Entwicklung vorgesehen und sollte nur in Entwicklungs- und Testumgebungen ausgeführt werden.

Die detaillierte Verwendung von dotnet-dsrouter zusammen mit mobilen Anwendungen wird in den jeweiligen .NET SDKs beschrieben. Dieses Dokument enthält nur einige Beispiele zum Ausführen von Diagnosetools für eine .NET-Anwendung, die unter Android ausgeführt wird. Ausführliche Informationen zu Konfiguration und Szenarien finden Sie unter Diagnoseablaufverfolgung.

Optionen

  • -?|-h|--help

    Zeigt die Hilfe für die Befehlszeile an.

  • --version

    Hiermit wird die Version des dotnet-dsrouter-Hilfsprogramms angezeigt.

Befehle

Befehl
dotnet-dsrouter client-server
dotnet-dsrouter server-server
dotnet-dsrouter server-client
dotnet-dsrouter client-client

dotnet-dsrouter client-server

Startet einen .NET-Anwendungsdiagnoseserver, der den lokalen IPC-Server und den TCP-Remoteclient weiterleitet. Der Router wird mithilfe eines IPC-Clients (Verbindung mit dem IPC-Server des Diagnosetools) und eines TCP/IP-Servers (der den TCP-Laufzeitclient akzeptiert) konfiguriert.

Übersicht

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

Optionen

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

    Gibt die IPC-Adresse des Diagnoseservers des Diagnosetools an (--diagnostic-port-Argument). Der Router stellt eine Verbindung mit dem IPC-Server des Diagnosetools her, wenn eine neue Route zwischen Runtime und Diagnosetool eingerichtet wird.

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

    Gibt die TCP/IP-Adresse des Routers im Format [host]:[port] an. Der Router kann eine Schnittstelle (127.0.0.1, [::1], 0.0.0.0, [::], IPv4-Adresse, IPv6-Adresse, Hostname) oder alle Schnittstellen (*) binden. Startet die Runtime unter Verwendung der Umgebungsvariable DOTNET_DiagnosticPorts und stellt während des Starts eine Verbindung mit dem TCP-Server des Routers her.

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

    Fährt den Router automatisch herunter, wenn vor Ablauf des angegebenen Timeouts (Sekunden) keine Runtime eine Verbindung herstellt. Wenn keine Angabe erfolgt, löst der Router kein automatisches Herunterfahren aus.

  • -v, --verbose <verbose>

    Aktiviert die ausführliche Protokollierung (debug|trace).

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

    Aktiviert die Portweiterleitung. Die Werte lauten Android oder iOS für TcpClient und nur Android für TcpServer. Stellen Sie sicher, dass Sie ANDROID_SDK_ROOT festlegen, bevor Sie diese Option unter Android verwenden.

dotnet-dsrouter server-server

Startet einen .NET-Anwendungsdiagnoseserver, der den lokalen IPC-Client und den TCP-Remoteclient weiterleitet. Der Router wird mithilfe eines IPC-Servers (Verbindung über Diagnosetools) und eines TCP/IP-Servers (der den TCP-Laufzeitclient akzeptiert) konfiguriert.

Übersicht

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

Optionen

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

    : Die weiterzuleitende IPC-Adresse des Diagnoseservers. Der Router akzeptiert IPC-Verbindungen von Diagnosetools, die eine neue Route zwischen der Runtime und dem Diagnosetool einrichten. Wenn keine Werte angegeben werden, verwendet der Router den Standardpfad des IPC-Diagnoseservers.

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

    Die TCP/IP-Adresse des Routers im Format [host]:[port]. Der Router kann eine Schnittstelle (127.0.0.1, [::1], 0.0.0.0, [::], IPv4-Adresse, IPv6-Adresse, Hostname) oder alle Schnittstellen (*) binden. Starten Sie die Runtime mithilfe der Umgebungsvariablen DOTNET_DiagnosticPorts, und verbinden Sie den TCP-Routerserver während des Starts.

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

    Fährt den Router automatisch herunter, wenn vor Ablauf des angegebenen Timeouts (Sekunden) keine Runtime eine Verbindung herstellt. Wenn keine Angabe erfolgt, löst der Router kein automatisches Herunterfahren aus.

  • -v, --verbose <verbose>

    Aktiviert die ausführliche Protokollierung (debug|trace).

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

    Aktiviert die Portweiterleitung. Die Werte lauten Android oder iOS für TcpClient und nur Android für TcpServer. Stellen Sie sicher, dass Sie ANDROID_SDK_ROOT festlegen, bevor Sie diese Option unter Android verwenden.

dotnet-dsrouter server-client

Startet einen .NET-Anwendungsdiagnoseserver, der den lokalen IPC-Client und den TCP-Remoteserver weiterleitet. Der Router wird mithilfe eines IPC-Servers (Verbindung über Diagnosetools) und eines TCP/IP-Clients (Verbindung mit dem TCP-Laufzeitserver) konfiguriert.

Übersicht

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

Optionen

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

    : Die weiterzuleitende IPC-Adresse des Diagnoseservers. Der Router akzeptiert IPC-Verbindungen von Diagnosetools, die eine neue Route zwischen der Runtime und dem Diagnosetool einrichten. Wenn keine Werte angegeben werden, verwendet der Router den Standardpfad des IPC-Diagnoseservers.

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

    Die TCP/IP-Adresse der Runtime im Format [host]:[port]. Router können eine Verbindung mit 127.0.0.1, [::1], der IPv4-Adresse, der IPv6-Adresse und den Hostnamenadressen herstellen. Startet die Runtime mithilfe der Umgebungsvariable DOTNET_DiagnosticPorts zum Einrichten des Listeners.

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

    Fährt den Router automatisch herunter, wenn vor Ablauf des angegebenen Timeouts (Sekunden) keine Runtime eine Verbindung herstellt. Wenn keine Angabe erfolgt, löst der Router kein automatisches Herunterfahren aus.

  • -v, --verbose <verbose>

    Aktiviert die ausführliche Protokollierung (debug|trace).

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

    Aktiviert die Portweiterleitung. Die Werte lauten Android oder iOS für TcpClient und nur Android für TcpServer. Stellen Sie sicher, dass Sie ANDROID_SDK_ROOT festlegen, bevor Sie diese Option unter Android verwenden.

dotnet-dsrouter client-client

Startet einen .NET-Anwendungsdiagnoseserver, der den lokalen IPC-Server und den TCP-Remoteserver weiterleitet. Der Router wird mithilfe eines IPC-Clients (Verbindung mit dem IPC-Server des Diagnosetools) und eines TCP/IP-Clients (Verbindung mit dem TCP-Laufzeitserver) konfiguriert.

Übersicht

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

Optionen

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

    : Die IPC-Adresse des Diagnoseservers des Diagnosetools (--diagnostic-port argument). Der Router stellt eine Verbindung mit dem IPC-Server des Diagnosetools her, wenn eine neue Route zwischen Runtime und Diagnosetool eingerichtet wird.

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

    Die TCP/IP-Adresse der Runtime im Format [host]:[port]. Router können eine Verbindung mit 127.0.0.1, [::1], der IPv4-Adresse, der IPv6-Adresse und den Hostnamenadressen herstellen. Startet die Runtime mithilfe der Umgebungsvariable DOTNET_DiagnosticPorts zum Einrichten des Listeners.

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

    Fährt den Router automatisch herunter, wenn vor Ablauf des angegebenen Timeouts (Sekunden) keine Runtime eine Verbindung herstellt. Wenn keine Angabe erfolgt, löst der Router kein automatisches Herunterfahren aus.

  • -v, --verbose <verbose>

    Aktiviert die ausführliche Protokollierung (debug|trace).

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

    Aktiviert die Portweiterleitung. Die Werte lauten Android oder iOS für TcpClient und nur Android für TcpServer. Stellen Sie sicher, dass Sie ANDROID_SDK_ROOT festlegen, bevor Sie diese Option unter Android verwenden.

Erfassen einer Startablaufverfolgung mit dotnet-trace aus einer .NET-Anwendung, die unter Android ausgeführt wird

Manchmal kann es nützlich sein, eine Ablaufverfolgung einer Anwendung ab ihrem Start zu erfassen. Die folgenden Schritte veranschaulichen dies für eine .NET-Anwendung, die unter Android ausgeführt wird. Da dotnet-dsrouter mithilfe von Portweiterleitung ausgeführt wird, funktioniert das gleiche Szenario für Anwendungen, die in einem lokalen Emulator und auf einem physischen Gerät ausgeführt werden, das über USB angeschlossen ist. Stellen Sie sicher, dass Sie ANDROID_SDK_ROOT festlegen, bevor Sie diese Option verwenden. Andernfalls wird adb zum Einrichten der Portweiterleitung von dotnet-dsrouter nicht gefunden.

  • Starten Sie dotnet-dsrouter im server-server-Modus:

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

  • Legen Sie die DOTNET_DiagnosticPorts-Umgebungsvariable mit AndroidEnvironment fest:

    Erstellen Sie eine Datei im gleichen Verzeichnis wie die CSPROJ-Datei mit einem Namen wie app.env, DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend fügen Sie der Datei Umgebungsvariablen hinzu, und fügen Sie die folgende ItemGroup in die CSPROJ-Datei ein:

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

    Sie können auch DOTNET_DiagnosticPorts mit adb shell setprop festlegen:

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

  • Erstellen und starten Sie die Anwendung mit dem .NET Android SDK, und aktivieren Sie Ablaufverfolgung, indem Sie /p:AndroidEnableProfiler=true an MSBuild übergeben. Da die App so konfiguriert wurde, dass sie beim Start angehalten wird, stellt sie erneut eine Verbindung mit dem dotnet-dsrouter TCP/IP-Listener her, der unter 127.0.0.1:9000 ausgeführt wird, und wartet, bis Diagnosetools eine Verbindung herstellen, bevor die Anwendungsausführung fortgesetzt wird.

  • Starten Sie dotnet-trace im Erfassungsmodus, und stellen Sie eine Verbindung mit dem dotnet-dsrouter IPC-Server (~/mylocalport) her:

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

dotnet-trace startet eine Ablaufverfolgungssitzung und setzt die Anwendung fort, die nun weiter ausgeführt wird. Ein Ereignisdatenstrom fließt von der mobilen Anwendung über dotnet-dsrouter in die dotnet-trace NETTRACE-Datei. Wenn die Ablaufverfolgung abgeschlossen ist, drücken Sie die EINGABETASTE, um sicherzustellen, dass die Ablaufverfolgungssitzung ordnungsgemäß geschlossen und sichergestellt wird, dass die NETTRACE-Datei alle erforderlichen Daten enthält, bevor die Anwendung geschlossen wird.

Es ist möglich, im Laufe der Zeit mehrere Ablaufverfolgungssitzungen für ein und dieselbe ausgeführte Anwendung auszuführen. Behalten Sie die Ausführung von dotnet-dsrouter bei, und führen Sie dotnet-trace erneut aus, wenn eine neue Ablaufverfolgungssitzung erforderlich ist.

dotnet-dsrouter kann im Hintergrund weiterhin ausgeführt und wiederverwendet werden, wenn eine Anwendung so konfiguriert ist, dass eine Verbindung mithilfe der Adresse und des Ports herstellt.

dotnet-dsrouter ist jederzeit an eine ausgeführte Anwendung gebunden. Wenn mehrere verschiedene Anwendungen gleichzeitig überwacht werden müssen, muss jede Anwendung eine eigene dotnet-dsrouter-Instanz verwenden, indem ein eindeutiges IPC-TCP/IP-Adresspaar in dotnet-dsrouter eingerichtet und verschiedene Anwendungsinstanzen konfiguriert werden, um eine Verbindung mit der eindeutigen dotnet-dsrouter-Instanz herzustellen.

Wenn dotnet-dsrouter mit --forward-port für Android ausgeführt wird und adb-Server, -Emulator oder -Gerät neu gestartet werden, müssen alle dotnet-dsrouter-Instanzen ebenfalls neu gestartet werden, um die Portweiterleitungsregeln wiederherzustellen.

Wenn Sie mit der Verwendung von dotnet-dsrouter fertig sind, drücken Sie Q oder STRG + C, um die Anwendung zu beenden.

Hinweis

Bei der Ausführung von dotnet-dsrouter unter Windows werden Named Pipes für den IPC-Kanal verwendet. Ersetzen Sie ~/mylocalport in den Beispielen oben durch mylocalport, wenn die Ausführung unter Windows erfolgt.

Hinweis

TCP/IP-Port 9000 ist nur ein Beispiel. Es kann ein beliebiger freier TCP/IP-Port verwendet werden.

Hinweis

Unix Domain Socket ~/mylocalport ist nur ein Beispiel. Jeder freie Unix Domain Socket-Dateipfad kann verwendet werden.

Erfassen einer Ablaufverfolgung mit dotnet-trace aus einer .NET-Anwendung, die unter Android ausgeführt wird

Wenn während des Anwendungsstarts keine Ablaufverfolgung erfasst werden muss, ist es möglich, die Anwendung im nosuspend-Modus zu starten. Das bedeutet, dass die Runtime beim Start nicht blockiert wird, weil sie darauf wartet, dass Diagnosetools eine Verbindung herstellen, bevor die Ausführung fortgesetzt wird. Der Großteil des oben beschriebenen Szenarios gilt auch für diesen Modus. Ersetzen Sie suspend einfach durch nosuspend in der DOTNET_DiagnosticPorts-Umgebungsvariablen, um die Anwendung im nosuspend-Modus zu starten.

Siehe auch