共用方式為

dotnet-dsrouter

  • 發行項

此文章適用於：✔️ .NET 6.0 SDK 與更新版本

安裝

若要安裝最新發行版本的 dotnet-dsrouter NuGet 套件，請使用 dotnet 工具安裝命令：

dotnet tool install --global dotnet-dsrouter

概要

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

描述

dotnet-dsrouter 會將診斷工具 (例如 dotnet-trace 和 dotnet-counters) 連線到 Android、iOS 和 tvOS 上執行的 .NET 應用程式，且不論這些應用程式是以模擬器 (emulator)、模擬器 (simulator) 或裝置本身的形式執行。 診斷工具會使用本機處理序間通訊 (IPC) (具名管道、Unix 網域通訊端) 來連線 .NET 執行階段並與之通訊。 在模擬器 (emulator)、模擬器 (simulator) 和裝置上沙箱環境中執行的 .NET 應用程式需要替代通訊方式。 dotnet-dsrouter 本身會在現有的診斷工具和 .NET 行動應用程式之間插入，並建立應用程式的本機表示法。 dotnet-dsrouter 可讓診斷工具與遠端 .NET 執行階段通訊，就像其已在本機電腦上執行一樣。

診斷工具和 dotnet-dsrouter 之間通訊使用的 IPC (具名管道、Unix 網域通訊端)，與連線到本機 .NET 執行階段時所使用的相同。 dotnet-dsrouter 會在其與遠端 .NET 執行階段的通訊中使用 TCP/IP，並支援數個不同的連線案例，以處理不同平台所使用的不同需求。 當執行於模擬器 (emulator)、模擬器 (simulator) 和透過 USB 連結的實體裝置時，dotnet-dsrouter 也會實作額外支援來簡化連線設定。

注意

dotnet-dsrouter 適用於開發和測試，強烈建議您透過回送介面 (例如 127.0.0.1、[::1]) 執行 dotnet-dsrouter。 dotnet-dsrouter 的連線功能和連接埠轉送功能可處理所有使用模擬器 (emulator)、模擬器 (simulator) 和實體裝置 (透過 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

啟動可路由本機 IPC 伺服器和遠端 TCP 用戶端的 .NET 應用程式診斷伺服器。 路由器會使用 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

啟動可路由本機 IPC 用戶端和遠端 TCP 用戶端的 .NET 應用程式診斷伺服器。 路由器會使用 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

啟動可路由本機 IPC 用戶端和遠端 TCP 伺服器的 .NET 應用程式診斷伺服器。 路由器會使用 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

啟動可路由本機 IPC 伺服器和遠端 TCP 伺服器的 .NET 應用程式診斷伺服器。 路由器會使用 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 執行個體。

如果搭配以 Android 和 adb 伺服器為目標的 --forward-port 執行 dotnet-dsrouter，當模擬器或裝置重新啟動時，所有 dotnet-dsrouter 執行個體都必須重新啟動，才能還原連接埠轉送規則。

使用 dotnet-dsrouter 完成作業時，請按 Q 或 Ctrl + C 結束應用程式。

注意

dotnet-dsrouter 在 Windows 上執行時，會針對其 IPC 通道使用具名管道。 在 Windows 上執行時，將 ~/mylocalport 取代為上述範例中的 mylocalport。

注意

TCP/IP 連接埠 9000 只是範例。 您可以使用任何免費的 TCP/IP 連接埠。

注意

Unix 網域通訊端 ~/mylocalport 只是一個範例。 您可以使用任何免費的 Unix 網域通訊端檔案路徑。

在 Android 上執行的 .NET 應用程式中，使用 dotnet-trace 收集追蹤

如果不需要在應用程式啟動期間收集追蹤，則可以在 nosuspend 模式中啟動應用程式，這表示執行階段不會在啟動時封鎖，以等待診斷工具連線，然後再繼續執行。 上述大部分的案例也適用於此模式，只要在 DOTNET_DiagnosticPorts 環境變數中將 suspend 取代為 nosuspend，即可在 nosuspend 模式中啟動應用程式。

另請參閱