dotnet-dsrouter

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

安装

可采用两种方法来下载和安装 dotnet-dsrouter：

dotnet 全局工具：

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

dotnet tool install --global dotnet-dsrouter

直接下载：

下载与平台相匹配的工具可执行文件：

(OS)

平台

Windows

x86 或 x64

macOS

x64

Linux

x64

摘要

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="'