dotnet-dsrouter

本文适用于：✔️ .NET 6.0 SDK 及更高版本

安装

若要安装最新版 dotnet-dsrouter NuGet 包，请使用 dotnet tool install 命令：

dotnet tool install --global dotnet-dsrouter

摘要

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

说明

dotnet-dsrouter 将 dotnet-trace 和 dotnet-counters 等诊断工具连接到在 Android、iOS 和 tvOS 上运行的 .NET 应用程序，无论它们是作为仿真器、模拟器还是在设备本身上运行。 诊断工具使用本地进程间通信 (IPC)（命名管道、Unix 域套接字）来连接 .NET 运行时并与之通信。 在仿真器、模拟器和设备上的沙盒环境中运行的 .NET 应用程序需要通过其他方式进行通信。 dotnet-dsrouter 将自身注入到现有诊断工具和 .NET 移动应用程序之间，并创建应用程序的本地表示形式。 dotnet-dsrouter 使诊断工具能够与远程 .NET 运行时进行通信，就好像它一直在本地计算机上运行一样。

诊断工具和 dotnet-dsrouter 之间的通信使用连接到本地 .NET 运行时所用的同一 IPC（命名管道、Unix 域套接字）。 dotnet-dsrouter 在与远程 .NET 运行时进行通信时使用 TCP/IP，并支持多种不同的连接场景来处理不同平台使用的不同需求和要求。 dotnet-dsrouter 还实现了额外的支持，可以简化在仿真器、模拟器和通过 USB 连接的物理设备上运行时的连接配置。

注意

dotnet-dsrouter 用于开发和测试，强烈建议通过环回接口（例如 127.0.0.1、[::1]）运行 dotnet-dsrouter。 dotnet-dsrouter 的连接特性和端口转发功能可以应对使用本地仿真器、模拟器或通过 USB 连接的物理设备的所有场景。

警告

不建议将 TCP 服务器终结点绑定到除环回接口（localhost、127.0.0.1 或 [::1]）以外的任何项。 任何指向 TCP 服务器终结点的连接都将未经身份验证和加密。 dotnet-dsrouter 用于开发，只应在开发和测试环境中运行。

dotnet-dsrouter 与移动应用程序的详细用法由各自的 .NET SDK 概述。 本文档只包含几个示例，说明如何针对 Android 上运行的 .NET 应用程序运行诊断工具。 若要深入了解配置和场景，请参阅诊断跟踪。

选项

• -?|-h|--help

  显示命令行帮助。

• --version

  显示 dotnet-dsrouter 实用工具的版本。

命令

Command
dotnet-dsrouter client-server
dotnet-dsrouter server-server
dotnet-dsrouter server-client
dotnet-dsrouter client-client

dotnet-dsrouter client-server

启动一个 .NET 应用程序诊断服务器来路由本地 IPC 服务器和远程 TCP 客户端。 路由器使用 IPC 客户端（连接诊断工具 IPC 服务器）和 TCP/IP 服务器（接受运行时 TCP 客户端）进行配置。

摘要

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

选项

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

  指定诊断工具诊断服务器 IPC 地址（--diagnostic-port 参数）。 在运行时和诊断工具之间建立新的路由时，路由器连接到诊断工具 IPC 服务器。

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

  使用格式 [host]:[port] 指定路由器 TCP/IP 地址。 路由器可以绑定一个（127.0.0.1、[::1]、0.0.0.0、[::]、IPv4 地址、IPv6 地址、主机名）或全部 (*) 的接口。 使用 DOTNET_DiagnosticPorts 环境变量启动运行时，并在启动期间连接路由器 TCP 服务器。

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

  如果在指定的超时时间（秒）之前没有运行时连接到路由器，则自动关闭路由器。 如果不指定，则路由器不会触发自动关闭。

• -v, --verbose <verbose>

  启用详细日志记录（调试|跟踪）。

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

  启用端口转发。 对于 TcpClient，值为 Android 或 iOS，而对于 TcpServer，值仅为 Android。 请确保在 Android 上使用此选项之前设置 ANDROID_SDK_ROOT。

dotnet-dsrouter server-server

启动一个 .NET 应用程序诊断服务器来路由本地 IPC 客户端和远程 TCP 客户端。 路由器使用 IPC 服务器（通过诊断工具连接）和 TCP/IP 服务器（接受运行时 TCP 客户端）进行配置。

摘要

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

选项

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

  ：要路由的诊断服务器 IPC 地址。 路由器接受来自诊断工具的 IPC 连接，在运行时和诊断工具之间建立新的路由。 如果不指定，路由器将使用默认的 IPC 诊断服务器路径。

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

  使用 [host]:[port] 格式的路由器 TCP/IP 地址。 路由器可以绑定一个（127.0.0.1、[::1]、0.0.0.0、[::]、IPv4 地址、IPv6 地址、主机名）或全部 (*) 的接口。 使用 DOTNET_DiagnosticPorts 环境变量启动运行时，在启动期间连接路由器 TCP 服务器。

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

  如果在指定的超时时间（秒）之前没有运行时连接到路由器，则自动关闭路由器。 如果不指定，则路由器不会触发自动关闭。

• -v, --verbose <verbose>

  启用详细日志记录（调试|跟踪）。

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

  启用端口转发。 对于 TcpClient，值为 Android 或 iOS，而对于 TcpServer，值仅为 Android。 请确保在 Android 上使用此选项之前设置 ANDROID_SDK_ROOT。

dotnet-dsrouter server-client

启动一个 .NET 应用程序诊断服务器来路由本地 IPC 客户端和远程 TCP 服务器。 路由器使用 IPC 服务器（通过诊断工具连接）和 TCP/IP 客户端（连接运行时 TCP 服务器）进行配置。

摘要

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

选项

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

  ：要路由的诊断服务器 IPC 地址。 路由器接受来自诊断工具的 IPC 连接，在运行时和诊断工具之间建立新的路由。 如果不指定，路由器将使用默认的 IPC 诊断服务器路径。

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

  使用 [host]:[port] 格式的运行时 TCP/IP 地址。 路由器可以连接 127.0.0.1、[::1]、IPv4 地址、IPv6 地址、主机名地址。 使用 DOTNET_DiagnosticPorts 环境变量启动运行时以设置侦听器。

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

  如果在指定的超时时间（秒）之前没有运行时连接到路由器，则自动关闭路由器。 如果不指定，则路由器不会触发自动关闭。

• -v, --verbose <verbose>

  启用详细日志记录（调试|跟踪）。

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

  启用端口转发。 对于 TcpClient，值为 Android 或 iOS，而对于 TcpServer，值仅为 Android。 请确保在 Android 上使用此选项之前设置 ANDROID_SDK_ROOT。

dotnet-dsrouter client-client

启动一个 .NET 应用程序诊断服务器来路由本地 IPC 服务器和远程 TCP 服务器。 路由器使用 IPC 客户端（连接诊断工具 IPC 服务器）和 TCP/IP 客户端（连接运行时 TCP 服务器）进行配置。

摘要

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

选项

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

  ：诊断工具诊断服务器 IPC 地址 (--diagnostic-port argument)。 在运行时和诊断工具之间建立新的路由时，路由器连接到诊断工具 IPC 服务器。

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

  使用 [host]:[port] 格式的运行时 TCP/IP 地址。 路由器可以连接 127.0.0.1、[::1]、IPv4 地址、IPv6 地址、主机名地址。 使用 DOTNET_DiagnosticPorts 环境变量启动运行时以设置侦听器。

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

  如果在指定的超时时间（秒）之前没有运行时连接到路由器，则自动关闭路由器。 如果不指定，则路由器不会触发自动关闭。

• -v, --verbose <verbose>

  启用详细日志记录（调试|跟踪）。

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

  启用端口转发。 对于 TcpClient，值为 Android 或 iOS，而对于 TcpServer，值仅为 Android。 请确保在 Android 上使用此选项之前设置 ANDROID_SDK_ROOT。

从 Android 上运行的 .NET 应用程序中使用 dotnet-trace 收集启动跟踪

有时，从应用程序启动中收集应用程序的跟踪可能很有用。 以下步骤说明了以 Android 上运行的 .NET 应用程序为目标执行此操作的过程。 由于 dotnet-dsrouter 是使用端口转发来运行的，因此相同的方案适用于在本地仿真器和通过 USB 连接的物理设备上运行的应用程序。 请确保在使用此选项之前设置 ANDROID_SDK_ROOT，否则 dotnet-dsrouter 将无法找到设置端口转发所需的 adb。

• 在服务器-服务器模式下启动 dotnet-dsrouter：

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

• 使用 AndroidEnvironment 设置 DOTNET_DiagnosticPorts 环境变量：

  使用 app.env 之类的名称在与 .csproj 相同的目录中创建一个文件，将环境变量添加到文件 DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend 中，并将以下 ItemGroup 包含到 .csproj 中：

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

  也可以使用 adb shell setprop 设置 DOTNET_DiagnosticPorts：

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

• 使用 .NET Android SDK 构建和启动应用程序，并通过将 /p:AndroidEnableProfiler=true 传递给 MSBuild 来启用跟踪。 由于应用已配置为在启动时挂起，因此它将连接回 127.0.0.1:9000 上运行的 dotnet-dsrouter TCP/IP 侦听器，并在等待诊断工具连接后再恢复应用程序执行。

• 在收集模式下启动 dotnet-trace，连接到 dotnet-dsrouter IPC 服务器、~/mylocalport：

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

dotnet-trace 将启动跟踪会话并恢复现在将继续执行的应用程序。 事件流将开始从移动应用经由 dotnet-dsrouter 流向 dotnet-trace nettrace 文件。 完成跟踪后，按 Enter 以确保跟踪会话已正确关闭，同时确保 nettrace 文件在应用程序关闭之前包含所有需要的数据。

可以在一段时间内针对同一运行中的应用程序运行多个跟踪会话，让 dotnet-dsrouter 保持运行状态，并在需要新的跟踪会话时重新运行 dotnet-trace。

dotnet-dsrouter 可以留在后台运行，如果一个应用程序被配置为使用其地址和端口进行连接，则可以重复使用。

dotnet-dsrouter 在任何时候都与一个正在运行的应用程序绑定。 如果需要同时跟踪多个不同的应用程序，每个应用程序需要使用自己的 dotnet-dsrouter 实例，通过在 dotnet-dsrouter 中设置一个唯一的 IPC、TCP/IP 地址对，并配置不同的应用程序实例来连接回其唯一的 dotnet-dsrouter 实例。

如果 dotnet-dsrouter 与面向 Android 的 --forward-port 一起运行，并且 adb 服务器、仿真器或设备重启，则所有 dotnet-dsrouter 实例也需要重启并恢复端口转发规则。

使用 dotnet-dsrouter 完成操作后，按 Q 或 Ctrl + C 退出应用程序。

注意

在 Windows 上运行 dotnet-dsrouter 时，它将为其 IPC 通道使用命名管道。 在 Windows 上运行时，请将上述示例中的 ~/mylocalport 替换为 mylocalport。

注意

TCP/IP 端口 9000 只是一个示例。 可以使用任何免费的 TCP/IP 端口。

注意

Unix 域套接字 ~/mylocalport 只是一个示例。 可以使用任何免费的 Unix 域套接字文件路径。

从 Android 上运行的 .NET 应用程序中使用 dotnet-trace 收集跟踪

如果在应用程序启动期间无需收集跟踪，则可以在 nosuspend 模式下启动应用程序，这意味着运行时不会在启动时阻塞，而是等待诊断工具连接后再恢复执行。 上面描述的大多数情况也适用于这种模式，只需将 DOTNET_DiagnosticPorts 环境变量中的 suspend 替换为 nosuspend 即可在 nosuspend 模式下启动应用程序。

另请参阅

• Android .NET 跟踪
• .NET MAUI 跟踪
• 移动设备上的 .NET 诊断跟踪