Portas de diagnóstico

Este artigo aplica-se a: ✔️ .NET Core 3.1 e versões posteriores

O tempo de execução do .NET expõe um ponto de extremidade de serviço que permite que outros processos enviem comandos de diagnóstico e recebam respostas por um canal IPC. Esse ponto de extremidade é chamado de porta de diagnóstico. Os comandos podem ser enviados para a porta de diagnóstico para:

• Capture um despejo de memória.
• Inicia um rastreio com EventPipe.
• Solicite a linha de comando usada para iniciar o aplicativo.

A porta de diagnóstico suporta diferentes transportes consoante a plataforma. Atualmente, tanto as implementações de runtime CoreCLR como Mono usam Named Pipes no Windows e sockets de domínio Unix no Linux e macOS. A implementação em runtime Mono no Android, iOS e tvOS utiliza TCP/IP. O canal utiliza um protocolo binário personalizado. A maioria dos programadores nunca interage diretamente com o canal e protocolo subjacente, mas sim utiliza ferramentas de interface gráfica ou CLI que comunicam em seu nome. Por exemplo, as ferramentas dotnet-dump e dotnet-trace abstraem o envio de comandos de protocolo para capturar dumps e iniciar registos. Para programadores que queiram escrever ferramentas personalizadas, o pacote NuGet Microsoft.Diagnostics.NETCore.Client fornece uma abstração da API .NET do transporte e protocolo subjacentes.

Considerações de segurança

A porta de diagnóstico expõe informações sensíveis sobre uma aplicação em funcionamento. Se um utilizador não confiável aceder a este canal, pode observar o estado detalhado do programa, incluindo quaisquer segredos na memória, e modificar arbitrariamente a execução do programa. No runtime CoreCLR, a porta de diagnóstico padrão está configurada para ser acessível apenas pela mesma conta de utilizador que lançou a aplicação ou por uma conta com permissões de superutilizador. Se o seu modelo de segurança não confiar noutros processos com as mesmas credenciais de conta de utilizador, pode desativar todas as portas de diagnóstico definindo a variável DOTNET_EnableDiagnostics=0de ambiente . Esta definição bloqueará a sua capacidade de usar ferramentas externas, como a depuração .NET ou qualquer uma das ferramentas de diagnóstico dotnet-*.

Porta de diagnóstico padrão

No Windows, Linux e macOS, o tempo de execução tem uma porta de diagnóstico aberta por padrão num endpoint bem conhecido. Esta é a porta à qual as ferramentas de diagnóstico dotnet-* se ligam automaticamente quando não foram explicitamente configuradas para usar uma porta alternativa. O ponto final é:

• Janelas - Cano Nomeado \\.\pipe\dotnet-diagnostic-{pid}
• Linux e macOS - Soquete de Domínio Unix {temp}/dotnet-diagnostic-{pid}-{disambiguation_key}-socket

{pid} é o id do processo escrito em decimal, {temp} é a TMPDIR variável de ambiente ou o valor /tmp se TMPDIR for indefinido/vazio, e {disambiguation_key} é o tempo de início do processo escrito em decimal. No macOS e NetBSD, o tempo de início do processo é o número de segundos desde a época UNIX. Em todas as outras plataformas, são ciclos desde o arranque.

Suspender o tempo de execução no arranque

Por defeito, o runtime executa código gerido assim que este inicia, independentemente de alguma ferramenta de diagnóstico estar ligada à porta de diagnóstico. Por vezes é útil que o runtime espere para executar código gerido até que uma ferramenta de diagnóstico esteja ligada, a fim de observar o comportamento inicial do programa. Definir a variável DOTNET_DefaultDiagnosticPortSuspend=1 ambiente faz com que o tempo de execução espere até que uma ferramenta se ligue à porta predefinida. Se nenhuma ferramenta estiver anexada após alguns segundos, o tempo de execução exibe uma mensagem de aviso na consola explicando que ainda está à espera que uma ferramenta se conecte.

Configurar portas de diagnóstico adicionais

Tanto o runtime do Mono como o do CoreCLR podem usar portas de diagnóstico configuradas à medida na função connect. O Mono também suporta portas TCP/IP personalizadas nesta listen função, quando usado com dotnet-dsrouter no Android ou iOS. Estas portas personalizadas são adicionais à porta padrão que permanece disponível. Existem algumas razões comuns pelas quais as portas personalizadas são úteis:

• No Android, iOS e tvOS não existe uma porta predefinida, por isso configurar uma porta é necessário para usar ferramentas de diagnóstico.
• Em ambientes com contentores ou firewalls, pode querer configurar um endereço de endpoint previsível que não varie com base no ID do processo, como acontece com a porta predefinida. Depois, a porta personalizada pode ser explicitamente adicionada a uma lista de permissões ou encaminhada através de alguma fronteira de segurança.
• Para ferramentas de monitorização, é útil que a ferramenta ouça num endpoint, e o runtime tente ativamente ligar-se a ele. Isto evita a necessidade de a ferramenta de monitorização pesquisar continuamente por novas aplicações que estão a iniciar. Em ambientes onde a porta de diagnóstico padrão não está acessível, também evita a necessidade de configurar o monitor com um endpoint personalizado para cada aplicação monitorizada.

Em cada canal de comunicação entre uma ferramenta de diagnóstico e o runtime .NET, um lado tem de ser o ouvinte e esperar que o outro lado se ligue. O runtime pode ser configurado para atuar na connect função de qualquer porta. (O tempo de execução Mono também pode ser configurado para atuar no listen papel de qualquer porta.) As portas também podem ser configuradas de forma independente para suspenderem no arranque, aguardando que uma ferramenta de diagnóstico emita um comando de retomar. As portas configuradas para ligar repetem as tentativas de ligação indefinidamente se o endpoint remoto não estiver a ouvir ou se a ligação for perdida. Mas a aplicação não suspende automaticamente o código gerido enquanto espera para estabelecer essa ligação. Se quiseres que a aplicação espere que a ligação seja estabelecida, usa a opção de suspender no arranque.

As portas personalizadas são configuradas usando a DOTNET_DiagnosticPorts variável de ambiente. Esta variável deve ser definida para uma lista delimitada por ponto e vírgula das descrições das portas. Cada descrição de porta consiste num endereço de endpoint e modificadores opcionais que controlam o papel do runtime `connect` ou `listen` e se o runtime deve ser suspenso no arranque. No Windows, o endereço do endpoint é o nome de um pipe nomeado sem o \\.\pipe\ prefixo. No Linux e macOS, é o caminho completo para um socket de domínio UNIX. No Android, iOS e tvOS, o endereço é um IP e uma porta. Por exemplo:

1. DOTNET_DiagnosticPorts=my_diag_port1 - (Windows) O runtime liga-se ao canal nomeado \\.\pipe\my_diag_port1.
2. DOTNET_DiagnosticPorts=/foo/tool1.socket;foo/tool2.socket - (Linux e macOS) O runtime liga-se tanto aos Sockets de Domínio Unix /foo/tool1.socket como aos /foo/tool2.socket.
3. DOTNET_DiagnosticPorts=127.0.0.1:9000 - (Android, iOS e tvOS) O runtime liga-se ao IP 127.0.0.1 na porta 9000.
4. DOTNET_DiagnosticPorts=/foo/tool1.socket,nosuspend - (Linux e macOS) Este exemplo tem o nosuspend modificador. O runtime tenta ligar-se ao Unix Domain Socket /foo/tool1.socket criado por uma ferramenta externa. Portas de diagnóstico adicionais normalmente fariam com que o tempo de execução se suspendesse no arranque à espera de um comando de retomada, mas nosuspend impediria que o tempo de execução esperasse.

A sintaxe completa de uma porta é address[,(listen|connect)][,(suspend|nosuspend)]. connect é o padrão se nem connect nem listen forem especificados (e listen é suportado apenas pelo runtime Mono no Android ou iOS). suspend é o padrão se nenhum suspend ou nosuspend for especificado.

Utilização em ferramentas de diagnóstico do .NET

Ferramentas como dotnet-dump, dotnet-counters e dotnet-trace suportam verbos collect ou monitor que comunicam com uma aplicação .NET através da porta de diagnóstico.

• Quando estas ferramentas usam o --processId argumento, a ferramenta calcula automaticamente o endereço padrão da porta de diagnóstico e liga-se a ele.
• Ao especificar o --diagnostic-port argumento, a ferramenta escuta o endereço indicado e deve usar a DOTNET_DiagnosticPorts variável de ambiente para configurar a sua aplicação para se ligar. Para um exemplo completo com contadores de dotnet, veja Utilização da Porta de Diagnóstico.

Usa o ds-router para fazer proxy na porta de diagnóstico

Todas as ferramentas de diagnóstico dotnet-* esperam ligar-se a uma porta de diagnóstico que seja um Named Pipe local ou um Socket de Domínio Unix. O Mono corre frequentemente em hardware isolado ou em emuladores que precisam de um proxy sobre TCP para se tornarem acessíveis. A ferramenta dotnet-dsrouter pode encaminhar um Named Pipe local ou um socket de domínio Unix para TCP, permitindo que as ferramentas sejam usadas nesses ambientes. Para mais informações, veja dotnet-dsrouter.