DbgShell

Um front-end PowerShell para o mecanismo de depuração do Windows.

Pronto para navegar com tab até a glória? Para uma introdução mais rápida, dê uma olhada em Começando.

Avisos

1. Este projeto não é produzido, endossado ou monitorado pela equipe do depurador do Windows. Embora a equipe do depurador receba bem feedback sobre sua API e front-ends (windbg, kd et al), eles não têm conexão com este projeto. Não relate bugs ou feedback à equipe do depurador referentes a este projeto.

2. Este não é um projeto financiado: não possui recursos oficiais alocados a ele, e é trabalhado apenas por voluntários. Não assuma nenhuma dependência de produção neste projeto a menos que você esteja disposto a mantê-lo completamente por conta própria. Sinta-se à vontade para abrir Issues e enviar Pull Requests, mas entenda que, com os recursos voluntários limitados, pode levar algum tempo até que suas submissões sejam tratadas.

3. Este é um projeto experimental: não está totalmente amadurecido, e você deve esperar mudanças significativas frequentemente.

Corolário dos avisos acima: eu evitaria anexar o DbgShell a alvos vivos de alto valor.

Binários

https://aka.ms/dbgshell-latest

Motivação

Você já tentou automatizar algo no depurador? (cdb/ntsd/kd/windbg) Como foi?

O principal ímpeto para o DbgShell é que é extremamente difícil automatizar qualquer coisa no depurador. Existem sim recursos hoje para ajudar na automatização do depurador, claro. Mas na minha opinião eles não estão atendendo às necessidades das pessoas.

• Usar a linguagem de script embutida é arcana, limitada, difícil de acertar e difícil de obter ajuda.
• Escrever uma DLL de extensão de depurador completa é muito poderosa, mas é um investimento significativo — muito custoso para resolver problemas rápidos e "pontuais" enquanto você depura problemas aleatórios do mundo real. Apesar do custo, existe um grande número de extensões de depurador em existência. Acho que não deveria haver tantas; acho que a única razão de existirem tantas é porque não há alternativas viáveis.
• Tentativas existentes de fornecer uma interface melhor (como PowerDbg) são baseadas em "raspagem" e análise de texto, o que é extremamente limitante (para não dizer ideologicamente irritante) e, portanto, não são capazes de cumprir a promessa de uma interface verdadeiramente melhor (são apenas marginalmente melhores, na melhor das hipóteses).
• Tentativas existentes de fornecer uma maneira mais fácil de escrever uma extensão de depurador são meramente uma solução temporária para a dor de desenvolver uma extensão de depurador; elas não resolvem realmente o problema maior. (por exemplo, duas grandes falhas são: ainda são muito de baixo nível (você tem que lidar com a API COM dbgeng), e não há REPL)
• A equipe do depurador introduziu recentemente scripting em Javascript. Javascript é uma linguagem muito melhor (e mais bem definida) do que a antiga linguagem de script do windbg, mas acho que o PowerShell tem algumas vantagens, a maior das quais é que ninguém realmente usa um shell Javascript — o PowerShell é muito melhor como um shell e linguagem de script combinados.

O objetivo do projeto DbgShell é trazer a bondade do mundo orientado a objetos do PowerShell para o mundo da depuração. Quando você faz 'dt' para despejar um 'objeto', você deve obter um objeto real. Scripting deve ser tão fácil quanto escrever um script PowerShell.

O projeto DbgShell fornece um front-end PowerShell para dbgeng.dll, incluindo:

• um "modelo de objeto" gerenciado (utilizável em C# se desejado), que é de nível mais alto do que a API COM dbgeng,
• um "provedor de navegação" PowerShell, que expõe aspectos de um alvo de depuração como um namespace hierárquico (para que você possa "cd" para uma thread específica, digitar "dir" para ver a pilha, "cd" para um quadro, fazer outro "dir" para ver variáveis locais/registradores/etc.),
• cmdlets para manipular o alvo,
• um host PowerShell personalizado que permite melhor controle da experiência CLI do depurador, bem como fornece recursos não disponíveis no host powershell.exe padrão (a saber, suporte para coloração de texto usando códigos de escape ANSI (a la ISO/IEC 6429))

O host personalizado ainda é um programa baseado em linha de comando (conhost.exe) (análogo ao ntsd/cdb/kd), mas pode ser invocado a partir do windbg (!DbgShell).

Além de tornar a automação muito mais fácil e poderosa, também abordará outras preocupações, como facilidade de uso para pessoas que não precisam usar os depuradores com tanta frequência. (uma reclamação que ouvi é que "quando acabo precisando usar windbg, passo todo o meu tempo no .CHM")

Para usuários experientes de windbg, por outro lado, outro objetivo é tornar a transição o mais suave possível. Assim, por exemplo, o provedor de namespace não é a única maneira de acessar dados; você ainda pode usar comandos tradicionais como "~3 s", "k", etc.

O que você quer dizer com "automação" e "scripting"?

Não estou falando apenas do tipo de coisa em que você abre um editor de texto e escreve um grande script para fazer algo complexo — estou também falando de poder criar coisas relativamente simples diretamente na linha de comando. Há muitas situações em que você gostaria de poder usar um pouco de lógica, mas nada tão grande ou reutilizável que você queira sequer salvar. Deveria ser fácil criar "one-liners" como "parar em CreateFile se o arquivo que está sendo aberto estiver na área de trabalho do usuário e a função Blah estiver na pilha."

Por que PowerShell?

Deixe-me ser claro: levou aproximadamente 4 anos para eu "aquecer" o PowerShell. Acho que ele tem arestas, aspectos que são simplesmente difíceis e muitos bugs, tanto no design quanto na implementação. Às vezes ele realmente me irrita. No entanto, os benefícios do PowerShell são convincentes e me convenceram de que é a melhor coisa a usar para este projeto:

• É tanto um ambiente de script quanto um ambiente de CLI. O fato de ter que fazer ambos leva a algumas coisas negativas, como uma curva de aprendizado mais íngreme, mas no final é extremamente útil, porque você quer poder tanto fazer coisas rapidamente em um REPL de linha de comando quanto escrever scripts completos e robustos.
• É muito descobrível — coisas como Get-Command, conclusão com tab, a capacidade de expor dados hierárquicos como um sistema de arquivos, as facilidades para fornecer e sintetizar ajuda, são muito boas.
• Conclusão com tab. Eu sei que mencionei no ponto anterior, mas é incrível o suficiente para ter seu próprio ponto.
• O pipeline de objetos: a natureza orientada a objetos do pipeline do PowerShell é tão mais poderosa e fácil de usar do que os maus velhos tempos de scripting baseado em análise de strings que nem é engraçado. Imagine fazer "dt" para "despejar" um "objeto", e realmente obter um objeto. O DbgShell faz isso.
• As pessoas o conhecem: estimo que o número de pessoas que conhecem PowerShell e/ou C# é pelo menos algumas ordens de magnitude maior do que as pessoas que conhecem técnicas de script do windbg. Isso significa que mais pessoas poderão facilmente "pegar" um depurador baseado em PowerShell; e também significa que quando as pessoas precisam de ajuda, o conjunto de possíveis ajudantes é muito maior (para problemas relacionados a script, de qualquer forma).
• O PowerShell ainda é um shell de propósito geral: ao usar o DbgShell, você tem acesso não apenas a comandos do depurador, mas também pode "cd" para o sistema de arquivos, registro, AD, etc.; você pode executar Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod, executar programas arbitrários, etc.

Status Atual

O DbgShell está em "modo de prototipação" há muito tempo. Passei muito tempo descobrindo como algo poderia ou deveria ser feito, mas não necessariamente "finalizando" tudo. Há um enorme número de TODOs no código atual. Portanto, embora tenha começado a se tornar realmente útil, o projeto ainda está bem verde. No entanto, pode definitivamente demonstrar o suficiente para lhe dar um bom gostinho de como deveria ser.

Abaixo estão algumas capturas de tela. É importante notar que nada que você vê é saída de texto do dbgeng. Embora algumas coisas na saída pareçam familiares, isso é apenas porque usei os recursos de formatação e saída do PowerShell para personalizar como certos objetos são exibidos — toda a saída que você vê corresponde na verdade a objetos .NET reais e completos. Por exemplo, essas mensagens ModLoad correspondem cada uma a um objeto MS.Dbg.ModuleLoadedEventArgs, que tem mais propriedades do que as exibidas quando enviado para Out-Default. Não há análise de string de nada do dbgeng. (Bem... quase. Fiz algumas concessões onde não há outra maneira de obter informações. Por exemplo, coisas de desmontagem, ou analisar o nome simbólico de uma função de ajuste de thunk para encontrar o deslocamento.)

Este é um tipo de cenário "hello world": anexar a uma instância do cmd.exe. Primeiro uso o comando embutido do PowerShell Start-Process, depois redireciono a saída para o comando do DbgShell Connect-Process, e então exploro o namespace:

Aqui anexei a um programa de teste, e olhei a pilha, mudei para um quadro de pilha específico, despejei variáveis locais, inspecionei o valor de um std::map local e inspecionei algumas informações de tipo para um valor de enumeração local. Observe a exibição do valor de enumeração: não apenas o DbgShell lida com a busca do nome simbólico para enumerandos individuais, mas também quando múltiplos enumerandos são combinados com OR. Você não pode perceber isso pela captura de tela, mas há conclusão com tab para todas essas coisas.

Recursos Notáveis

• Cor: suporte para coloração de texto usando códigos de escape ANSI (a la ISO/IEC 6429)
• Mecanismo de formatação personalizado: Não gosta de coisas .ps1xml? Eu também não. Além das visualizações padrão de tabela, lista e personalizadas, você pode definir visualizações de "linha única" que são muito úteis para personalizar exibições de valores de símbolos.
• Conversão personalizada de valor de símbolo: Para a maioria das variáveis, a conversão e exibição padrão são boas. Mas às vezes, você gostaria que o depurador fizesse um pouco mais de trabalho para você. O recurso de conversão de valor de símbolo permite, por exemplo, que objetos de coleção STL sejam transformados em objetos de coleção .NET que são muito mais fáceis de lidar.
• Detecção de tipo derivado: Para quando sua variável é um IFoo, mas o objeto real é um FooImpl.
• Informações de tipo ricas: expostas para seu prazer programático.
• P: Funciona no WinDbg? Só usarei o WinDbg. R: Sim — carregue a DLL de extensão DbgShellExt.dll e depois execute "!dbgshell" para abrir um console DbgShell.

Deficiências Atuais

• A maior deficiência atualmente é que ele não suporta bem o modo kernel (se você já estiver no contexto adequado, pode exibir valores, mas não pode mudar de contexto de dentro do DbgShell, e o namespace não está conectado).
• Embora você possa carregar e executar extensões de depurador tradicionais da maneira usual, ainda faltam muitos comandos do windbg.
• Remotos não são suportados: a API dbgeng suporta conectar a um depurador remoto. Infelizmente, as informações de símbolo e tipo expostas pela API dbgeng são criticamente insuficientes para as necessidades do DbgShell, então o DbgShell usa a API dbghelp. Infelizmente, não existe dbghelp remoto. Precisaremos trabalhar com a equipe do depurador para resolver este problema.

Licença

Licenciado sob a Licença MIT.

Contribuindo

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um Contrato de Licença de Contribuidor (CLA) declarando que você tem o direito de, e realmente nos concede, os direitos de usar sua contribuição. Para detalhes, visite https://cla.microsoft.com.

Ao enviar um pull request, um bot de CLA determinará automaticamente se você precisa fornecer um CLA e decorará o PR apropriadamente (por exemplo, etiqueta, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Veja Contribuindo para mais informações sobre como contribuir com o projeto.

Código de Conduta

Este projeto adotou o Código de Conduta de Código Aberto da Microsoft.

Para mais informações, veja a FAQ do Código de Conduta ou entre em contato com [email protected] com quaisquer perguntas ou comentários adicionais.

Outros tópicos

• Começando com o DbgShell

• Cor

• Mecanismo de formatação personalizado

• Conversão personalizada de valor de símbolo

• Detecção de tipo derivado

• Informações de tipo ricas

• Contribuindo com o DbgShell

• DbgEngWrapper

Você pode encontrar uma breve introdução em vídeo (3 minutos) aqui: https://youtu.be/ynbg2zZ1Igc