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-dsrouter は、Android、iOS、tvOS で実行されている dotnet-trace や dotnet-counters などの .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 ユーティリティのバージョンを表示します。

コマンド

コマンド
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 アドレスを指定します。 ルーターでは、1 つ (127.0.0.1、[::1]、0.0.0.0、[::]、IPv4 アドレス、IPv6 アドレス、ホスト名) またはすべて (*) のインターフェイスをバインドできます。 DOTNET_DiagnosticPorts 環境変数を使用してランタイムを起動し、起動時にルーターの TCP サーバーを接続します。

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

  指定されたタイムアウト (秒単位) の前にランタイムが接続されない場合は、ルーターを自動的にシャットダウンします。 指定されていない場合は、ルーターで自動シャットダウンがトリガーされません。

• -v, --verbose <verbose>

  詳細ログ記録 (debug|trace) を有効にします。

• -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 アドレス。 ルーターでは、1 つ (127.0.0.1、[::1]、0.0.0.0、[::]、IPv4 アドレス、IPv6 アドレス、ホスト名) またはすべて (*) のインターフェイスをバインドできます。 DOTNET_DiagnosticPorts 環境変数を使用してランタイムを起動し、起動時にルーターの TCP サーバーを接続します。

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

  指定されたタイムアウト (秒単位) の前にランタイムが接続されない場合は、ルーターを自動的にシャットダウンします。 指定されていない場合は、ルーターで自動シャットダウンがトリガーされません。

• -v, --verbose <verbose>

  詳細ログ記録 (debug|trace) を有効にします。

• -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>

  詳細ログ記録 (debug|trace) を有効にします。

• -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>

  詳細ログ記録 (debug|trace) を有効にします。

• -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 を設定してください。そうしないと、ポート フォワーディングを設定するのに必要な adb が dotnet-dsrouter で見つかりません。

• server-server モードで 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 を collect モードで開始し、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 はいつでも実行中の 1 つのアプリケーションに関連付けられています。 複数の異なるアプリケーションを同時にトレースする必要がある場合は、それぞれのアプリケーションで独自の dotnet-dsrouter インスタンスを使用する必要があります。これは、dotnet-dsrouter で一意の IPC と TCP/IP アドレスのペアを設定し、その一意の dotnet-dsrouter インスタンスに接続するために異なるアプリケーション インスタンスを構成することで行います。

dotnet-dsrouter が Android をターゲットとする --forward-port と一緒に実行されており、adb のサーバー、エミュレーター、またはデバイスが再起動される場合は、ポート フォワーディング規則を復元するために、すべての 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 モードでアプリケーションを起動するだけです。

こちらもご覧ください

• Android の .NET トレース
• .NET MAUI トレース
• モバイルでの .NET 診断トレース