dotnet-dsrouter

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

安装

若要安装最新版 dotnet-dsrouterdotnet-dsrouter,请使用 dotnet tool install 命令:

dotnet tool install --global dotnet-dsrouter

摘要

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

说明

dotnet-dsrouterdotnet-tracedotnet-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-dsrouterdotnet-dsrouter 的连接特性和端口转发功能可以应对使用本地仿真器、模拟器或通过 USB 连接的物理设备的所有场景。

警告

不建议将 TCP 服务器终结点绑定到除环回接口(localhost127.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,值为 AndroidiOS,而对于 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,值为 AndroidiOS,而对于 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,值为 AndroidiOS,而对于 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,值为 AndroidiOS,而对于 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 完成操作后,按 QCtrl + 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 模式下启动应用程序。

另请参阅