Objetos nativos do depurador em extensões JavaScript – Considerações sobre design e teste

Artigo
11/15/2023

Este tópico descreve considerações de design e teste para usar os objetos nativos do depurador em extensões JavaScript.

Objetos de depurador nativos representam vários constructos e comportamentos do ambiente do depurador. Os objetos podem ser passados para extensões JavaScript (ou adquiridas em) para manipular o estado do depurador.

Para obter informações sobre extensões JavaScript de objeto de depurador, consulte Native Debugger Objects in JavaScript Extensions.

Para obter informações gerais sobre como trabalhar com JavaScript, consulte Scripts do Depurador javaScript.

Considerações sobre o design do modelo de dados do depurador

Princípios de design

Considere os princípios a seguir para tornar suas extensões de depurador que apresentam informações detectáveis, consultáveis e que podem ser scripts.

As informações estão próximas de onde são necessárias. Por exemplo, as informações sobre uma chave do Registro devem ser exibidas como parte de uma variável local que contém um identificador de chave do Registro.
As informações são estruturadas. Por exemplo, informações sobre uma chave do Registro são apresentadas em campos separados, como tipo de chave, ACL de chave, nome da chave e valor. Isso significa que os campos individuais podem ser acessados sem analisar texto.
As informações são consistentes. As informações sobre identificadores de chave do Registro são apresentadas da maneira mais semelhante possível às informações sobre identificadores de arquivo.

Evite essas abordagens que não dão suporte a esses princípios.

Não estrutrufique seus itens em um único "coletor de cozinha" simples. Uma hierarquia organizada permite que os usuários procurem as informações que estão procurando sem conhecimento prévio do que estão procurando e dá suporte à descoberta.
Não converta uma extensão dbgeng clássica simplesmente movendo-a para o modelo enquanto ainda gera telas de texto bruto. Isso não é composível com outras extensões e não pode ser consultado com expressões LINQ. Em vez disso, divida os dados em campos separados e consultáveis.

Diretrizes de nomenclatura

A capitalização de campos deve ser PascalCase. Uma exceção pode ser considerada para nomes amplamente conhecidos em outra maiúsculas e minúsculas, como jQuery.
Evite usar caracteres especiais que normalmente não seriam usados em um identificador C++. Por exemplo, evite usar nomes como "Comprimento Total" (que contém um espaço) ou "[size]" (que contém colchetes). Essa convenção permite um consumo mais fácil de linguagens de script em que esses caracteres não são permitidos como parte dos identificadores e também permite o consumo mais fácil da janela de comando.

Diretrizes de organização e hierarquia

Não estenda o nível superior do namespace do depurador. Em vez disso, você deve estender um nó existente no depurador para que as informações sejam exibidas onde elas são mais relevantes.
Não duplicar conceitos. Se você estiver criando uma extensão de modelo de dados que lista informações adicionais sobre um conceito que já existe no depurador, estenda as informações existentes em vez de tentar substituí-la por novas informações. Em outras palavras, uma extensão que exibe detalhes sobre um módulo deve estender o objeto Module existente em vez de criar uma nova lista de módulos.
Os comandos de utilitário flutuante gratuitos devem fazer parte do namespace Debugger.Utility . Eles também devem ser sub-nomes espaçados adequadamente (por exemplo, Debugger.Utility.Collections.FromListEntry)

Compatibilidade com versões anteriores e alterações interruptivas

Um script publicado não deve interromper a compatibilidade com outros scripts que dependem dele. Por exemplo, se uma função for publicada no modelo, ela deverá permanecer no mesmo local e com os mesmos parâmetros, sempre que possível.

Sem uso de recursos externos

As extensões não devem gerar processos externos. Processos externos podem interferir no comportamento do depurador e se comportarão incorretamente em vários cenários de depurador remoto (por exemplo, remotos dbgsrv, remotos ntsd e "ntsd -d remotes")
As extensões não devem exibir nenhuma interface do usuário. A exibição de elementos de interface do usuário se comportará incorretamente em cenários de depuração remota e poderá interromper cenários de depuração do console.
As extensões não devem manipular o mecanismo de depurador ou a interface do usuário do depurador por meio de métodos não documentados. Isso causa problemas de compatibilidade e se comportará incorretamente em clientes de depurador com interface do usuário diferente.
As extensões devem acessar as informações de destino somente por meio das APIs documentadas do depurador. Tentar acessar informações sobre um destino por meio de APIs win32 falhará em muitos cenários remotos e até mesmo em alguns cenários de depuração local entre limites de segurança.

Sem uso de recursos específicos do Dbgeng

Os scripts destinados a serem usados como extensões não devem depender de recursos específicos do dbgeng sempre que possível (como executar extensões de depurador "clássicas"). Os scripts devem ser utilizáveis sobre qualquer depurador que hospede o modelo de dados.

Testando extensões do depurador

Espera-se que as extensões funcionem em uma ampla variedade de cenários. Embora algumas extensões possam ser específicas para um cenário (como um cenário de depuração de kernel), a maioria das extensões deve funcionar em todos os cenários ou ter metadados indicando os cenários com suporte.

Modo Kernel