Utilitário de depuração e análise de dumps de processos em tempo real (dotnet-debug)

Este artigo aplica-se a: ✔️ dotnet-debug versão 0.0.710501 e versões posteriores

Observação

dotnet-debug atualmente apenas suporta aplicações baseadas em CoreCLR e não é suportado no macOS.

Install

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

dotnet tool install --global dotnet-debug

Sinopse

dotnet-debug [-h|--help] [--version] <command>

Description

A dotnet-debug ferramenta global permite-lhe ligar processos .NET ao vivo e analisar ficheiros de dump de forma interativa. Ao contrário dotnet-dumpde , que se foca na recolha de dumps e análise offline, dotnet-debug é concebido para inspeção de processos em tempo real. Suporta todos os mesmos comandos de depuração SOS que dotnet-dump.

Esta ferramenta é útil em plataformas como o Alpine Linux, onde não está disponível um sistema totalmente funcional lldb . A dotnet-debug ferramenta executa comandos SOS para analisar diagnósticos de estado gerido e heap, mas não é um depurador nativo, por isso a exibição de frames nativos da pilha não é suportada.

Opções

  • --version

    Mostra a versão da ferramenta dotnet-debug.

  • -h|--help

    Mostra a ajuda da linha de comando.

Commands

Command
dotnet-debug attach
dotnet-debug open-dump

dotnet-debug attach

Liga-se a um processo em tempo real e inicia um shell interativo com comandos de depuração para o explorar.

Sinopse

dotnet-debug attach <process-id> [-c|--commands <debug_command>] [--accept-license-agreement]

Arguments

  • <process-id>

    O ID do processo a anexar e analisar.

Opções

  • -c|--commands <debug_command>

    Executa os comandos no início. Várias instâncias desse parâmetro podem ser usadas em uma invocação para comandos em cadeia. Os comandos executam-se pela ordem em que são fornecidos na linha de comandos. Se quiseres dotnet-debug sair depois dos comandos, o teu último comando deve ser exit.

  • --accept-license-agreement

    Aceita o acordo de licenciamento sem ser solicitado.

Example

Anexar a um processo em execução com ID 1234:

$ dotnet-debug attach 1234
Attaching to process: 1234 ...
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

Executa um comando em anexar e depois sai:

dotnet-debug attach 1234 -c clrstack -c exit

dotnet-debug open-dump

Inicia um shell interativo com comandos de depuração para explorar um ficheiro de dump.

Sinopse

dotnet-debug open-dump <dump_path> [-c|--commands] [--accept-license-agreement]

Arguments

  • <dump_path>

    O caminho para o ficheiro de despejo para analisar.

Opções

  • -c|--commands <debug_command>

    Executa os comandos no início. Várias instâncias desse parâmetro podem ser usadas em uma invocação para comandos em cadeia. Os comandos executam-se pela ordem em que são fornecidos na linha de comandos. Se quiseres dotnet-debug sair depois dos comandos, o teu último comando deve ser exit.

  • --accept-license-agreement

    Aceita o acordo de licenciamento sem ser solicitado.

Example

Abra e analise um ficheiro de dump:

$ dotnet-debug open-dump ./core_20260209_135837
Loading dump: ./core_20260209_135837 ...
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

Depuração de comandos SOS

Ambos os attach comandos and open-dump apresentam uma sessão interativa que aceita os seguintes comandos SOS.

Command Função
analyzeoom Exibe as informações do último OOM que ocorreu em uma solicitação de alocação para o heap GC.
clrmodules Lista os módulos gerenciados no processo.
clrstack Fornece um rastreamento de pilha somente de código gerenciado.
clrthreads Lista os threads gerenciados que estão em execução.
clru Exibe uma desmontagem anotada de um método gerenciado.
d ou readmemory Despeja o conteúdo da memória.
dbgout Habilita/desabilita (-off) o registro interno do SOS.
dso Exibe todos os objetos gerenciados encontrados dentro dos limites da pilha atual.
dumpalc Exibe detalhes sobre um AssemblyLoadContext colecionável para o qual o objeto especificado é carregado.
dumparray Exibe detalhes sobre uma matriz gerenciada.
dumpasync Exibe informações sobre máquinas de estado assíncronas na pilha coletada de lixo.
dumpassembly Exibe detalhes sobre uma montagem.
dumpclass Exibe informações sobre a EEClass estrutura no endereço especificado.
dumpconcurrentdictionary Exibe conteúdo de dicionário simultâneo.
dumpconcurrentqueue Exibe o conteúdo da fila simultânea.
dumpdelegate Exibe informações sobre um delegado.
dumpdomain Exibe informações sobre todos os assemblies em todos os AppDomains ou no especificado.
dumpgcdata Exibe informações sobre os dados GC.
dumpgen Exibe o conteúdo de pilha para a geração especificada.
dumpheap Exibe informações sobre a pilha coletada de lixo e estatísticas de coleta sobre objetos.
dumpil Exibe a linguagem intermediária comum (CIL) associada a um método gerenciado.
dumplog Grava o conteúdo de um log de estresse na memória no arquivo especificado.
dumpmd Exibe informações sobre a MethodDesc estrutura no endereço especificado.
dumpmodule Exibe informações sobre o módulo no endereço especificado.
dumpmt Exibe informações sobre a tabela de método no endereço especificado.
dumpobj Exibe informações do objeto no endereço especificado.
dumpruntimetypes Encontra todos os objetos System.RuntimeType no heap GC e imprime o nome do tipo e o MethodTable a que se referem.
dumpsig Despeja a assinatura de um método ou campo especificado por <sigaddr> <moduleaddr>.
dumpsigelem Despeja um único elemento de um objeto de assinatura.
dumpstackobjects Exibe todos os objetos gerenciados encontrados dentro dos limites da pilha atual.
dumpvc Exibe informações sobre os campos de uma classe de valor.
eeheap Exibe informações sobre a memória de processo consumida por estruturas de dados de tempo de execução internas.
eestack É executado dumpstack em todos os threads no processo.
eeversion Exibe informações sobre as versões de tempo de execução e SOS.
ehinfo Exibe os blocos de tratamento de exceção em um método JIT-ed.
exit ou quit Sai do modo interativo.
finalizequeue Exibe todos os objetos registrados para finalização.
findappdomain Tenta resolver o AppDomain de um objeto GC.
gchandles Exibe estatísticas sobre as alças do coletor de lixo no processo.
gcheapstat Exibe estatísticas sobre o coletor de lixo.
gcinfo Exibe a codificação JIT GC para um método.
gcroot Exibe informações sobre referências (ou raízes) ao objeto no endereço especificado.
gcwhere Exibe o local no heap GC do endereço especificado.
histclear Libera todos os recursos usados pela família de comandos Hist.
histinit Inicializa as estruturas SOS a partir do log de estresse salvo no depurador.
histobj Examina todos os registos de realocação de registos de stress e mostra a cadeia de relocações de recolha de lixo que podem ter levado à passagem do endereço como argumento.
histobjfind Exibe todas as entradas de log que fazem referência ao objeto no endereço especificado.
histroot Exibe informações relacionadas a promoções e realocações da raiz especificada.
histstats Exibe estatísticas de log de estresse.
ip2md Exibe a MethodDesc estrutura no endereço especificado no código que foi compilado em JIT.
listnearobj Exibe o objeto que precede e sucede o endereço especificado.
logopen Habilita o registro em log de arquivos do console.
logclose Desabilita o log de arquivos do console.
logging Habilita/desabilita o registro interno de SOS.
lm ou modules Exibe os módulos nativos no processo.
name2ee Exibe as MethodTable estruturas e EEClass para o tipo ou método especificado no módulo especificado.
objsize Exibe o tamanho do objeto especificado.
parallelstacks Exibe a pilha de threads mesclados de forma semelhante ao painel 'Pilhas paralelas' do Visual Studio.
pathto Exibe o caminho GC de <root> para <target>.
pe ou printexception Exibe e formata campos de qualquer objeto derivado da Exception classe no endereço especificado.
r ou registers Exibe os registros do thread.
runtimes Lista os tempos de execução no destino ou altera o tempo de execução padrão.
setclrpath Define o caminho para carregar arquivos coreclr dac/dbi usando setclrpath <path>o .
setsymbolserver Habilita o suporte ao servidor de símbolos.
sos Executa vários comandos de depuração coreclr. Use a sintaxe sos <command-name> <args>. Para mais informações, use soshelp.
soshelp ou help Exibe todos os comandos disponíveis.
soshelp <command> ou help <command> Exibe o comando especificado.
syncblk Exibe as informações do titular do SyncBlock.
taskstate Exibe um estado Task em um formato legível por humanos.
threadpool Exibe informações sobre o pool de threads de tempo de execução.
threadpoolqueue Exibe itens de trabalho do pool de threads enfileirados.
threadstate Pretty imprime o significado de um estado de threads.
threads <threadid> ou setthread <threadid> Define ou exibe o ID de thread atual para os comandos SOS.
timerinfo Exibe informações sobre temporizadores em execução.
token2ee Exibe a estrutura MethodTable e a estrutura MethodDesc para o token e o módulo especificados.
traverseheap Grava informações de pilha em um arquivo em um formato compreendido pelo CLR Profiler.
verifyheap Verifica a pilha GC em busca de sinais de corrupção.
verifyobj Verifica o objeto que é passado como um argumento para sinais de corrupção.

Observação

Para mais detalhes, veja Extensão de Depuração SOS para .NET.

Usar dotnet-debug para ligar a um processo em tempo real

O exemplo seguinte mostra como ligar a um processo .NET em corrida e investigar um problema de pool de threads:

$ dotnet-debug attach 1902
Attaching to process: 1902 ...
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

Esta ação apresenta uma sessão interativa que aceita comandos como:

> clrstack
OS Thread Id: 0x573d (0)
    Child SP               IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String)
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String)
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String)
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[])

Para ver uma exceção não tratada:

> pe -lines
Exception object: 00007fb18c038590
Exception type:   System.Reflection.TargetInvocationException
Message:          Exception has been thrown by the target of an invocation.
InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP               IP               Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d

StackTraceString: <none>
HResult: 80131604

dotnet-debug vs dotnet-dump

dotnet-debug e dotnet-dump partilham os mesmos comandos de depuração SOS, mas servem propósitos principais diferentes:

Característica dotnet-debug dotnet-dump
Anexar a um processo em tempo real ✔️ ❌
Recolher despejos ❌ ✔️
Analisar ficheiros de despejo ✔️ ✔️
Listar processos .NET (ps) ❌ ✔️

Use dotnet-debug quando precisar de depurar um processo em tempo real de forma interativa. Usa dotnet-dump quando precisares de recolher dumps ou analisá-los offline.

Consulte também

  • Last updated on