dotnet-dsrouter

Este artigo se aplica a: ✔️ SDK do .NET 6.0 e versões posteriores

Instalar

Para instalar a versão mais recente do dotnet-dsrouter, use o comando dotnet tool install:

dotnet tool install --global dotnet-dsrouter

Sinopse

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

Descrição

dotnet-dsrouter conecta ferramentas de diagnóstico como dotnet-trace e dotnet-counters a aplicativos .NET em execução no Android, iOS e tvOS, independentemente de estarem em execução como emulador, simulador ou no próprio dispositivo. As ferramentas de diagnóstico usam a IPC (comunicação entre processos) local (Pipe Nomeado, Soquete de Domínio Unix) para se conectar e se comunicar com um runtime do .NET. Os aplicativos .NET em execução em ambientes de área restrita em emuladores, simuladores ou dispositivos precisam de maneiras alternativas de comunicação. dotnet-dsrouter se injeta entre ferramentas de diagnóstico existentes e aplicativos móveis .NET e cria uma representação local do aplicativo. dotnet-dsrouter habilita as ferramentas de diagnóstico a se comunicarem com um runtime .NET remoto, como se estivesse em execução no computador local.

A comunicação entre as ferramentas de diagnóstico e dotnet-dsrouter usa o mesmo IPC (Pipe Nomeado, Soquete de Domínio Unix) empregado na conexão com um runtime .NET local. dotnet-dsrouter usa TCP/IP na comunicação com o runtime .NET remoto e dá suporte a vários cenários de conectividade distintos para lidar com diferentes necessidades e requisitos usados por diversas plataformas. dotnet-dsrouter também implementa suporte adicional para simplificar a configuração de conectividade ao executar em emulador, simulador ou dispositivo físico anexado por USB.

O uso detalhado de dotnet-dsrouter com aplicativos móveis é descrito pelos respectivos SDKs do .NET. Este documento inclui apenas alguns exemplos de como executar ferramentas de diagnóstico em aplicativos .NET em execução no Android. Para obter detalhes aprofundados sobre configuração e cenários, confira Rastreamento de Diagnóstico.

Opções

• -?|-h|--help

  Mostra a ajuda da linha de comando.

• --version

  Exibe a versão do utilitário dotnet-dsrouter.

Comandos

dotnet-dsrouter cliente-servidor

Inicie um servidor de diagnóstico de aplicativo .NET roteando o servidor IPC local e o cliente TCP remoto. O roteador é configurado usando um cliente IPC (conectando o servidor IPC da ferramenta de diagnóstico) e um servidor TCP/IP (que aceita o cliente TCP do runtime).

Sinopse

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

Opções

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

  Especifica o endereço IPC do servidor de diagnóstico da ferramenta (argumento --diagnostic-port). O roteador conecta o servidor IPC da ferramenta de diagnóstico ao estabelecer uma nova rota entre o runtime e a ferramenta de diagnóstico.

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

  Especifica o endereço TCP/IP do roteador usando o formato [host]:[port]. O roteador pode associar uma (127.0.0.1, [::1], 0.0.0.0, [::], endereço IPv4, endereço IPv6, nome do host) ou todas (*) as interfaces. Inicia o runtime usando a variável de ambiente DOTNET_DiagnosticPorts e conecta o servidor TCP do roteador durante a inicialização.

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

  Desligue automaticamente o roteador se nenhum runtime se conectar a ele antes do tempo limite especificado (em segundos). Se não for especificado, o roteador não vai disparar o desligamento automático.

• -v, --verbose <verbose>

  Habilita o log detalhado (debug|trace).

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

  Habilita o encaminhamento de porta. Os valores são Android ou iOS para TcpClient, e somente Android para TcpServer. Defina ANDROID_SDK_ROOT antes de usar essa opção no Android.

dotnet-dsrouter server-server

Inicie um servidor de diagnóstico de aplicativo .NET roteando o cliente IPC local e o cliente TCP remoto. O roteador é configurado usando um servidor IPC (ao qual se conecta pelas ferramentas de diagnóstico) e um servidor TCP/IP (que aceita o cliente TCP do runtime).

Sinopse

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

Opções

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

  Endereço IPC do servidor de diagnóstico a ser roteado. O roteador aceita conexões IPC de ferramentas de diagnóstico que estabelecem uma nova rota entre o runtime e a ferramenta de diagnóstico. Se não for especificado, o roteador usará o caminho padrão do servidor de diagnóstico IPC.

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

  O endereço TCP/IP do roteador no formato [host]:[port]. O roteador pode associar uma (127.0.0.1, [::1], 0.0.0.0, [::], endereço IPv4, endereço IPv6, nome do host) ou todas (*) as interfaces. Inicie o runtime usando a variável de ambiente DOTNET_DiagnosticPorts, conectando o servidor TCP do roteador durante a inicialização.

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

  Desligue automaticamente o roteador se nenhum runtime se conectar a ele antes do tempo limite especificado (em segundos). Se não for especificado, o roteador não vai disparar o desligamento automático.

• -v, --verbose <verbose>

  Habilita o log detalhado (debug|trace).

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

  Habilita o encaminhamento de porta. Os valores são Android ou iOS para TcpClient, e somente Android para TcpServer. Defina ANDROID_SDK_ROOT antes de usar essa opção no Android.

dotnet-dsrouter server-client

Inicie um servidor de diagnóstico de aplicativo .NET roteando o cliente IPC local e o servidor TCP remoto. O roteador é configurado usando um servidor IPC (ao qual se conecta pelas ferramentas de diagnóstico) e um cliente TCP/IP (que se conecta ao servidor TCP do runtime).

Sinopse

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

Opções

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

  Endereço IPC do servidor de diagnóstico a ser roteado. O roteador aceita conexões IPC de ferramentas de diagnóstico que estabelecem uma nova rota entre o runtime e a ferramenta de diagnóstico. Se não for especificado, o roteador usará o caminho padrão do servidor de diagnóstico IPC.

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

  O endereço TCP/IP do runtime no formato [host]:[port]. O roteador pode conectar 127.0.0.1, [::1], endereço IPv4, endereço IPv6 e endereços de nome do host. Inicie o runtime usando a variável de ambiente DOTNET_DiagnosticPorts para configurar o ouvinte.

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

  Desligue automaticamente o roteador se nenhum runtime se conectar a ele antes do tempo limite especificado (em segundos). Se não for especificado, o roteador não vai disparar o desligamento automático.

• -v, --verbose <verbose>

  Habilita o log detalhado (debug|trace).

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

  Habilita o encaminhamento de porta. Os valores são Android ou iOS para TcpClient, e somente Android para TcpServer. Defina ANDROID_SDK_ROOT antes de usar essa opção no Android.

dotnet-dsrouter client-client

Inicie um servidor de diagnóstico de aplicativo .NET roteando o servidor IPC local e o servidor TCP remoto. O roteador é configurado usando um cliente IPC (conectando o servidor IPC da ferramenta de diagnóstico) e um cliente TCP/IP (que se conecta ao servidor TCP do runtime).

Sinopse

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

Opções

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

  Endereço IPC do servidor de diagnóstico da ferramenta de diagnóstico (--diagnostic-port argument). O roteador conecta o servidor IPC da ferramenta de diagnóstico ao estabelecer uma nova rota entre o runtime e a ferramenta de diagnóstico.

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

  O endereço TCP/IP do runtime no formato [host]:[port]. O roteador pode conectar 127.0.0.1, [::1], endereço IPv4, endereço IPv6 e endereços de nome do host. Inicie o runtime usando a variável de ambiente DOTNET_DiagnosticPorts para configurar o ouvinte.

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

  Desligue automaticamente o roteador se nenhum runtime se conectar a ele antes do tempo limite especificado (em segundos). Se não for especificado, o roteador não vai disparar o desligamento automático.

• -v, --verbose <verbose>

  Habilita o log detalhado (debug|trace).

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

  Habilita o encaminhamento de porta. Os valores são Android ou iOS para TcpClient, e somente Android para TcpServer. Defina ANDROID_SDK_ROOT antes de usar essa opção no Android.

Usando o dotnet-trace, coletar o rastreamento de inicialização de um aplicativo .NET em execução no Android

Às vezes, pode ser útil coletar o rastreamento de inicialização de um aplicativo. As etapas a seguir ilustram o processo para fazer isso em um aplicativo .NET em execução no Android. Como dotnet-dsrouter é executado usando o encaminhamento de porta, o mesmo cenário funciona em aplicativos em execução em um emulador local e em um dispositivo físico anexado por USB. Certifique-se de definir ANDROID_SDK_ROOT antes de usar essa opção ou dotnet-dsrouter não conseguirá localizar adb necessário para configurar o encaminhamento de porta.

• Iniciar dotnet-dsrouter no modo server-server:

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

• Definir variável de ambiente DOTNET_DiagnosticPorts usando AndroidEnvironment:

  Crie um arquivo no mesmo diretório que .csproj usando um nome como app.env, adicione variáveis de ambiente ao arquivo DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend e inclua o seguinte ItemGroup em .csproj:

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

  Também é possível definir DOTNET_DiagnosticPorts usando adb shell setprop:

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

• Crie e inicie o aplicativo usando o SDK do Android do .NET e habilite o rastreamento passando /p:AndroidEnableProfiler=true para o MSBuild. Como o aplicativo foi configurado para suspender na inicialização, ele se conectará novamente ao ouvinte TCP/IP do dotnet-dsrouter em execução em 127.0.0.1:9000 e aguardará a conexão das ferramentas de diagnóstico antes de retomar a execução do aplicativo.

• Inicie dotnet-trace no modo de coleta, conectando-se ao servidor IPC dotnet-dsrouter, ~/mylocalport:

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

dotnet-trace iniciará uma sessão de rastreamento e retomará o aplicativo, que então continuará a ser executado. Um fluxo de eventos será iniciado do aplicativo móvel, passando por dotnet-dsrouter até o arquivo nettrace de dotnet-trace. Ao terminar o rastreamento, pressione Enter para encerrar a sessão de rastreamento e verificar se o arquivo nettrace inclui todos os dados necessários antes que o aplicativo seja fechado.

É possível executar várias sessões de rastreamento no mesmo aplicativo em execução ao longo do tempo, deixar dotnet-dsrouter em execução e executar novamente dotnet-trace quando uma nova sessão de rastreamento for necessária.

dotnet-dsrouter pode ser deixado em execução em segundo plano e reutilizado se um aplicativo estiver configurado para se conectar usando o endereço e porta dele.

dotnet-dsrouter é vinculado a um aplicativo em execução de cada vez. Se houver necessidade de rastrear vários aplicativos diferentes ao mesmo tempo, cada aplicativo precisará usar uma instância própria de dotnet-dsrouter, configurando um par exclusivo de endereços IPC, TCP/IP em dotnet-dsrouter, e configurar instâncias de aplicativo diferentes para se conectar novamente à instância exclusiva de dotnet-dsrouter.

Se o dotnet-dsrouter for executado com --forward-port direcionado ao servidor Android e adb, emulador ou dispositivo for reiniciado, todas as instâncias dotnet-dsrouter também precisarão ser reiniciadas para restaurar as regras de encaminhamento de porta.

Quando terminar de usar dotnet-dsrouter, pressione Q ou Ctrl + C para sair do aplicativo.

Coletar um rastreamento usando o dotnet-trace de um aplicativo .NET em execução no Android

Se não houver necessidade de coletar um rastreamento durante a inicialização do aplicativo, é possível iniciar o aplicativo no modo nosuspend, o que significa que o tempo de execução não será bloqueado na inicialização aguardando a conexão das ferramentas de diagnóstico antes de retomar a execução. A maior parte do cenário descrito acima também se aplica a esse modo, basta substituir suspend por nosuspend na variável de ambiente DOTNET_DiagnosticPorts para iniciar o aplicativo no modo nosuspend.

Confira também

• Rastreamento de MAUI do .NET
• Rastreamento de diagnóstico do .NET no dispositivo móvel