Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo se aplica a: ✔️ SDK do .NET 6.0 e versões posteriores
Install
Para instalar a versão mais recente do dotnet-dsrouterpacote NuGet, use o comando dotnet tool install:
dotnet tool install --global dotnet-dsrouter
Synopsis
dotnet-dsrouter [-?, -h, --help] [--version] <command>
Description
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 (Named Pipe, Unix Domain Socket) para se conectar e se comunicar com o .NET runtime. 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.
Note
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 redirecionamento de porta de dotnet-dsrouter gerenciam todos os cenários usando emulador ou simulador local ou dispositivo físico conectado por USB.
Warning
Não é recomendável a associação do ponto de extremidade do servidor TCP a qualquer coisa que não seja a interface do loopback (localhost, 127.0.0.1 ou [::1]). 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.
Commands
| Command |
|---|
| 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 (que conecta ao servidor IPC da ferramenta de diagnóstico) e um servidor TCP/IP (que aceita um cliente TCP em tempo de execução).
Synopsis
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>Desliga 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. Para Android, defina opcionalmente$ANDROID_HOMEcomo um caminho válido para o SDK do 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).
Synopsis
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 para roteamento do servidor de diagnóstico. 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. Para Android, defina opcionalmente$ANDROID_HOMEcomo um caminho válido para o SDK do 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).
Synopsis
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. Para Android, defina opcionalmente$ANDROID_HOMEcomo um caminho válido para o SDK do 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).
Synopsis
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. Para Android, defina opcionalmente$ANDROID_HOMEcomo um caminho válido para o SDK do 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 um aplicativo desde a sua inicialização. 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.
dotnet-dsrouter tenta localizar automaticamente o SDK do Android e adb precisa configurar o encaminhamento de porta. Defina opcionalmente o $ANDROID_HOME para especificar o caminho do SDK do Android.
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 começará a fluir 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.
Note
Ao executar dotnet-dsrouter no Windows, usará pipes nomeados para o canal IPC. Substitua ~/mylocalport por mylocalport nos exemplos acima ao executar no Windows.
Note
A porta TCP/IP 9000 é apenas um exemplo. Qualquer porta TCP/IP gratuita pode ser usada.
Note
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 ficará bloqueado na inicialização aguardando as ferramentas de diagnóstico se conectarem 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.
Consulte também
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
