dotnet-dsrouter
Este artigo se aplica a: ✔️ SDK do .NET 6.0 e versões posteriores
Instalar
Para instalar a última versão do dotnet-dsrouterpacote NuGet, 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.
Observação
dotnet-dsrouter se destina ao desenvolvimento e teste e é altamente recomendável executar dotnet-dsrouter sobre a interface de loopback (por exemplo, 127.0.0.1, [::1]). Os recursos de conectividade e de encaminhamento de porta de dotnet-dsrouter gerenciam todos os cenários usando emulador, simulador ou dispositivo físico local conectado por USB.
Aviso
Associar o ponto de extremidade do servidor TCP a qualquer coisa que não seja a interface do loopback (localhost, 127.0.0.1 ou [::1]) não é recomendável. Todas as conexões com o ponto de extremidade do servidor TCP não serão autenticadas e nem criptografadas. dotnet-dsrouter destina-se ao uso na etapa de desenvolvimento e só deve ser executado em ambientes de desenvolvimento e teste.
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|--helpMostra a ajuda da linha de comando.
--versionExibe a versão do utilitário
dotnet-dsrouter.
Comandos
| Comando |
|---|
| dotnet-dsrouter client-server |
| dotnet-dsrouter server-server |
| dotnet-dsrouter server-client |
| dotnet-dsrouter client-client |
dotnet-dsrouter client-server
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 ambienteDOTNET_DiagnosticPortse 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
AndroidouiOSparaTcpClient, e somenteAndroidparaTcpServer. DefinaANDROID_SDK_ROOTantes 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 ambienteDOTNET_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
AndroidouiOSparaTcpClient, e somenteAndroidparaTcpServer. DefinaANDROID_SDK_ROOTantes 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 conectar127.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 ambienteDOTNET_DiagnosticPortspara 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
AndroidouiOSparaTcpClient, e somenteAndroidparaTcpServer. DefinaANDROID_SDK_ROOTantes 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 conectar127.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 ambienteDOTNET_DiagnosticPortspara 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
AndroidouiOSparaTcpClient, e somenteAndroidparaTcpServer. DefinaANDROID_SDK_ROOTantes 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_DiagnosticPortsusandoAndroidEnvironment:Crie um arquivo no mesmo diretório que .csproj usando um nome como
app.env, adicione variáveis de ambiente ao arquivoDOTNET_DiagnosticPorts=127.0.0.1:9000,suspende inclua o seguinteItemGroupem .csproj:<ItemGroup Condition="'$(AndroidEnableProfiler)'=='true'"> <AndroidEnvironment Include="app.env" /> </ItemGroup>Também é possível definir
DOTNET_DiagnosticPortsusandoadb 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=truepara o MSBuild. Como o aplicativo foi configurado para suspender na inicialização, ele se conectará novamente ao ouvinte TCP/IP dodotnet-dsrouterem execução em127.0.0.1:9000e aguardará a conexão das ferramentas de diagnóstico antes de retomar a execução do aplicativo.Inicie
dotnet-traceno modo de coleta, conectando-se ao servidor IPCdotnet-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.
Observação
Ao executar dotnet-dsrouter no Windows, ele usará Pipes Nomeados para o canal IPC. Substitua ~/mylocalport por mylocalport nos exemplos acima ao executar no Windows.
Observação
A porta TCP/IP 9000 é apenas um exemplo. Qualquer porta TCP/IP gratuita pode ser usada.
Observação
O Soquete de Domínio Unix ~/mylocalport é apenas um exemplo. Qualquer caminho de arquivo gratuito do Soquete de Domínio Unix pode ser usado.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de