dotnet-dsrouter

Эта статья относится к: ✔️ пакету SDK для .NET 6.0 и более поздних версий

Install

Чтобы установить последнюю версию пакета dotnet-dsrouterNuGet, используйте команду dotnet tool install.

dotnet tool install --global dotnet-dsrouter

Synopsis

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

Description

dotnet-dsrouter подключает средства диагностики, такие как dotnet-trace и dotnet-counters к приложениям .NET, работающим в Android, iOS и tvOS в качестве эмулятора, симулятора или на самом устройстве. Средства диагностики выполняют локальный внутрипроцессный обмен данными (IPC) (именованный канал, сокет домена Unix) для подключения к среде выполнения .NET и взаимодействия с ней. Приложениям .NET, работающим в изолированных средах в эмуляторах, симуляторах и устройствах, требуются альтернативные способы обмена данными. dotnet-dsrouter внедряется между существующими средствами диагностики и мобильными приложениями .NET для создания локального представления приложения. dotnet-dsrouter позволяет средствам диагностики взаимодействовать с удаленной средой выполнения .NET, как при выполнении на локальном компьютере.

Обмен данными между средствами диагностики и dotnet-dsrouter осуществляется с помощью того же механизма IPC (именованный канал, сокет домена Unix), который используется, когда подключаются к локальной среде выполнения .NET. dotnet-dsrouter использует TCP/IP для взаимодействия с удаленной средой выполнения .NET и поддерживает несколько разных сценариев подключения с учетом разных требований разных платформ. dotnet-dsrouter также реализует дополнительную поддержку, чтобы упростить настройку подключения при работе в эмуляторе, симуляторе и на физическом устройстве, подключенном по USB.

Note

dotnet-dsrouter используется для разработки и тестирования, поэтому настоятельно рекомендуется запускать dotnet-dsrouter через интерфейс с возвратом цикла (например, 127.0.0.1, [::1]). Функции подключения и возможности переадресации портов dotnet-dsrouter поддерживают все сценарии с использованием локального эмулятора, симулятора или физического устройства с подключением через USB.

Warning

Выполнять привязку конечной точки TCP-сервера к чему-либо, кроме интерфейса с возвратом цикла (localhost, 127.0.0.1 или [::1]), не рекомендуется. Любые подключения к конечной точке TCP-сервера не будут проходить проверку подлинности и не будут шифроваться. dotnet-dsrouter предназначен для использования в разработке и должен запускаться только в средах разработки и тестирования.

Особенности использования dotnet-dsrouter вместе с мобильными приложениями определяются в документации по соответствующим пакетам SDK для .NET. Этот документ будет включать только несколько примеров того, как запускать средства диагностики для приложения .NET, работающего в Android. Подробные сведения о конфигурации и сценариях см. в статье, посвященной диагностической трассировке.

Options

• -?|-h|--help

  Показать справку в командной строке.

• --version

  Отображает версию утилиты dotnet-dsrouter.

Commands

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

dotnet-dsrouter клиент-сервер

Запустите сервер диагностики приложения .NET с маршрутизацией локального IPC-сервера и удаленного TCP-клиента. Маршрутизатор настраивается с использованием IPC-клиента (для соединения с IPC-сервером диагностического инструмента) и TCP/IP-сервера (для приема TCP-клиента во время выполнения).

Synopsis

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

Options

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

  Указывает IPC-адрес сервера диагностического средства (--diagnostic-portаргумент). Маршрутизатор подключается к серверу IPC инструмента диагностики при создании нового маршрута между исполняемой средой и инструментом диагностики.

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

  Указывает TCP/IP-адрес маршрутизатора с помощью формата [host]:[port]. Маршрутизатор может привязать один (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>

  Включает переадресацию портов. Значения могут быть Android или iOS для TcpClient, и только Android для TcpServer. Для Android опционально установите $ANDROID_HOME на допустимый путь к Android SDK.

dotnet-dsrouter server-server

Запустите сервер диагностики приложений .NET с маршрутизацией локального IPC-клиента и удаленного TCP-клиента. Маршрутизатор настраивается с использованием IPC-сервера (к которому подключаются диагностические средства) и сервера TCP/IP (принимающего подключения от TCP-клиентов в режиме выполнения).

Synopsis

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

Options

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

  Адрес IPC сервера диагностики для маршрутизации. Маршрутизатор принимает IPC-подключения от диагностических инструментов, устанавливая новый маршрут между средой выполнения и диагностическим инструментом. Если не задано иное, маршрутизатор будет использовать путь к серверу диагностики IPC по умолчанию.

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

  TCP/IP-адрес маршрутизатора в формате [host]:[port]. Маршрутизатор может привязать один (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>

  Включает переадресацию портов. Значения — это Android или iOS для TcpClient, и только Android для TcpServer. Для Android опционально установите $ANDROID_HOME на допустимый путь к Android SDK.

dotnet-dsrouter сервер-клиент

Запустите сервер диагностики приложений .NET с маршрутизацией локального IPC-клиента и удаленного TCP-сервера. Маршрутизатор настраивается с использованием IPC-сервера (к которому подключаются диагностические инструменты) и TCP/IP-клиента (подключаемого к TCP-серверу в среде выполнения).

Synopsis

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

Options

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

  IPC-адрес сервера диагностики для маршрута. Маршрутизатор принимает подключения IPC от диагностических инструментов, устанавливая новый маршрут между средой выполнения и инструментом диагностики. Если не указано, маршрутизатор будет использовать путь по умолчанию к диагностическому серверу IPC.

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

  TCP/IP-адрес среды выполнения в формате [host]:[port]. Маршрутизатор может подключить 127.0.0.1, [::1], IPv4-адрес, IPv6-адрес, имя хоста. Запустите среду выполнения с помощью DOTNET_DiagnosticPorts переменной среды для настройки прослушивателя.

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

  Автоматически отключает маршрутизатор, если среда выполнения не подключается к нему до заданного тайм-аута (в секундах). Если не указано, маршрутизатор не будет активировать автоматическое завершение работы.

• -v, --verbose <verbose>

  Включает подробное ведение журнала (отладка|трассировка).

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

  Включает переадресацию портов. Значения Android или iOS для TcpClient, а только Android для TcpServer. Для Android опционально установите $ANDROID_HOME на допустимый путь к Android SDK.

dotnet-dsrouter client-client

Запустите сервер диагностики приложения .NET с маршрутизацией локального IPC-сервера и удаленного TCP-сервера. Маршрутизатор настраивается с использованием IPC-клиента (с подключением IPC-сервера средства диагностики) и TCP/IP-клиента (с подключением TCP-сервера среды выполнения).

Synopsis

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

Options

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

  Средство диагностики адреса IPC сервера (--diagnostic-port argument). Маршрутизатор подключается к серверу IPC средства диагностики при установке нового маршрута между средой выполнения и средством диагностики.

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

  TCP/IP-адрес среды выполнения в формате [host]:[port]. Маршрутизатор может подключить 127.0.0.1, [::1], IPv4-адрес, IPv6-адрес, имя хоста. Запустите среду выполнения с помощью DOTNET_DiagnosticPorts переменной среды для настройки прослушивателя.

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

  Автоматически завершает работу маршрутизатора, если среда выполнения не подключается к нему до указанного времени ожидания (в секундах). Если не указано, маршрутизатор не будет активировать автоматическое завершение работы.

• -v, --verbose <verbose>

  Включает подробное логирование (отладка|трассировка).

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

  Включает переадресацию портов. Android или iOS для TcpClient, и только Android для TcpServer. Для Android опционально установите $ANDROID_HOME на допустимый путь к Android SDK.

Сбор трассировки запуска с помощью dotnet-trace из приложения .NET, работающего на Android

Иногда бывает полезно получить трассировку приложения с момента его запуска. Ниже показано, как выполнить эту процедуру для приложения .NET, работающего в Android. Так как dotnet-dsrouter запускается с использованием переадресации портов, тот же сценарий поддерживается для приложений, работающих в локальном эмуляторе и на физическом устройстве с подключением через USB. dotnet-dsrouter пытается автоматически найти пакет SDK для Android и adb необходим для настройки перенаправления портов. При необходимости укажите $ANDROID_HOME путь пакета SDK для Android.

• Запустите dotnet-dsrouter в режиме"сервер — сервер":

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

• Задайте переменную среды DOTNET_DiagnosticPorts, используя AndroidEnvironment:

  Создайте файл в том же каталоге, что и .csproj, используя такое имя, как app.env, добавьте переменные среды в файл DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend и включите ItemGroup в .csproj:

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

  Также можно задать DOTNET_DiagnosticPorts, используя adb shell setprop:

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

• Создайте и запустите приложение, используя .NET Android SDK, и активируйте трассировку, передав /p:AndroidEnableProfiler=true в MSBuild. Так как приложение настроено приостанавливать работу при запуске, оно снова подключится к запущенному прослушивателю TCP/IP dotnet-dsrouter, работающему в 127.0.0.1:9000, и будет ждать подключения средств диагностики, прежде чем возобновлять работу.

• Запустите dotnet-trace в режиме сбора с подключением к IPC-серверу dotnet-dsrouter (~/mylocalport):

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

dotnet-trace запустит сеанс трассировки и возобновит выполнение приложения, которое теперь продолжит исполнение. Поток событий начнет передаваться из мобильного приложения через dotnet-dsrouter в файл nettrace dotnet-trace. По завершении сбора трассировки нажмите клавишу ВВОД, чтобы убедиться, что сеанс трассировки правильно закрыт. Так в файл nettrace будут включены все необходимые данные, прежде чем приложение будет закрыто.

С течением времени можно запустить несколько сеансов трассировки для одного и того же работающего приложения, оставьте dotnet-dsrouter работающим и запустите dotnet-trace заново, когда нужен новый сеанс трассировки.

dotnet-dsrouter можно оставить работать в фоновом режиме и использовать повторно, если приложение настроено выполнять подключение с использованием его адреса и порта.

dotnet-dsrouter привязывается к одному запущенному приложению в любое время. Если есть необходимость отслеживать несколько разных приложений одновременно, каждое приложение должно использовать свой собственный экземпляр dotnet-dsrouter. Для этого задайте уникальное значение IPC и пары TCP/IP-адресов в dotnet-dsrouter, а также настройте разные экземпляры приложения для обратного подключения к уникальному экземпляру dotnet-dsrouter.

Если dotnet-dsrouter запускается с --forward-port нацеливанием на Android и adb сервер, эмулятор или устройство перезапускаются, необходимо также перезапустить все dotnet-dsrouter экземпляры, чтобы восстановить правила перенаправления портов.

По завершении использования dotnet-dsrouter нажмите клавишу Q или клавиши CTRL + C, чтобы выйти из приложения.

Note

Если dotnet-dsrouter запускается в операционной системе Windows, для IPC-канала будут использоваться именованные каналы. Измените ~/mylocalport на mylocalport в примерах выше при запуске в Windows.

Note

TCP/IP-порт 9000 используется для примера. Можно использовать любой свободный TCP/IP-порт.

Note

Сокет домена UNIX ~/mylocalport используется для примера. Можно использовать любой свободный путь к файлу сокета домена UNIX.

Сбор трассировки с помощью dotnet-trace из приложения .NET, работающего на Android

Если нет необходимости собирать трассировку при запуске приложения, можно запустить приложение в nosuspend режиме, что означает, что среда выполнения не будет блокирована при запуске в ожидании подключения диагностических инструментов перед продолжением выполнения. Большая часть описанного выше сценария применима и к этому режиму. Просто измените suspend на nosuspend в переменной среды DOTNET_DiagnosticPorts, чтобы запустить приложение в режиме nosuspend.

См. также

• Трассировка .NET MAUI
• Трассировка диагностики .NET на мобильных устройствах