DbgShell

Интерфейс PowerShell для отладчика Windows.

Готовы табулировать свой путь к успеху? Для быстрого знакомства посмотрите Начало работы.

Отказ от ответственности

1. Этот проект не создан, не одобрен и не контролируется командой отладчика Windows.
   Команда отладчика приветствует обратную связь по своему API и интерфейсам (windbg, kd и др.), но они не имеют никакого отношения к этому проекту. Не отправляйте ошибки или отзывы команде отладчика касательно этого проекта.

2. Это не финансируемый проект: ему не выделены официальные ресурсы, над ним работают только добровольцы. Не берите на себя производственные зависимости от этого проекта, если вы не готовы полностью поддерживать его самостоятельно. Не стесняйтесь оставлять Issues и отправлять Pull Requests, но имейте в виду, что из-за ограниченных волонтёрских ресурсов обработка ваших вкладов может занять некоторое время.

3. Это экспериментальный проект: он не до конца проработан, и вы должны ожидать, что критические изменения будут вноситься часто.

Следствие из вышеуказанных отказов: я бы избегал подключения DbgShell к живым целям высокой ценности.

Бинарные файлы

https://aka.ms/dbgshell-latest

Мотивация

Вы когда-нибудь пытались автоматизировать что-то в отладчике? (cdb/ntsd/kd/windbg) Как успехи?

Основная движущая сила DbgShell — это то, что автоматизировать что-либо в отладчике слишком сложно. Конечно, на сегодняшний день существуют средства для автоматизации отладчика. Но, на мой взгляд, они не удовлетворяют потребностям людей.

• Использование встроенного языка сценариев — это архаично, ограниченно, трудно сделать правильно и сложно получить помощь.
• Написание полноценной DLL расширения отладчика — это очень мощно, но это значительная инвестиция — слишком дорого для быстрых «одноразовых» задач при отладке случайных реальных проблем. Несмотря на затраты, существует огромное количество расширений отладчика. Я считаю, что их не должно быть так много; единственная причина, по которой их так много, — отсутствие жизнеспособных альтернатив.
• Существующие попытки предоставить лучший интерфейс (например, PowerDbg) основаны на «скрапинге» и текстовом анализе, что крайне ограничивает (не говоря уже об идеологической раздражающей сути) и поэтому они не могут выполнить обещание действительно лучшего интерфейса (в лучшем случае они лишь немного лучше).
• Существующие попытки упростить написание расширения отладчика — это лишь временная мера, решающая боль разработки расширения; они не решают более крупную проблему. (например, два основных недостатка: они всё ещё слишком низкоуровневые (приходится работать с COM API dbgeng), и нет REPL)
• Команда отладчика недавно представила скриптинг на JavaScript. JavaScript — гораздо лучший (и более чётко определённый) язык, чем старый язык сценариев windbg, но я считаю, что PowerShell имеет некоторые преимущества, самое большое из которых — никто на самом деле не использует оболочку JavaScript — PowerShell гораздо лучше как комбинированная оболочка и язык сценариев.

Цель проекта DbgShell — принести все преимущества объектно-ориентированного мира PowerShell в мир отладки. Когда вы выполняете 'dt' для дампа 'объекта', вы должны получить реальный объект. Скриптинг должен быть таким же простым, как написание скрипта PowerShell.

Проект DbgShell предоставляет интерфейс PowerShell для dbgeng.dll, включая:

• управляемую "объектную модель" (используемую из C#, если хотите), которая является более высокоуровневой, чем COM API dbgeng,
• "провайдер навигации" PowerShell, который предоставляет аспекты цели отладки в виде иерархического пространства имён (так что можно "cd" к определённому потоку, ввести "dir" для просмотра стека, "cd" в кадр, снова выполнить "dir" для просмотра локальных переменных/регистров и т.д.),
• командлеты для управления целью,
• пользовательский хост PowerShell, который обеспечивает лучший контроль над CLI-интерфейсом отладчика, а также предоставляет функции, недоступные в стандартном хосте powershell.exe (а именно, поддержка цветовой раскраски текста с использованием управляющих последовательностей ANSI (в соответствии с ISO/IEC 6429)).

Пользовательский хост по-прежнему является программой на основе командной строки (conhost.exe) (аналогично ntsd/cdb/kd), но его можно вызвать из windbg (!DbgShell).

Помимо значительного упрощения и расширения возможностей автоматизации, он будет решать и другие проблемы, такие как удобство использования для людей, которым не приходится часто использовать отладчики. (одна из жалоб, которую я слышал: «когда мне в конце концов приходится использовать windbg, я провожу всё время в .CHM»)

Для опытных пользователей windbg, с другой стороны, ещё одна цель — сделать переход максимально плавным. Так, например, провайдер пространства имён — не единственный способ доступа к данным; вы по-прежнему можете использовать традиционные команды, такие как "~3 s", "k" и т.д.

Что вы имеете в виду под «автоматизацией» и «скриптингом»?

Я имею в виду не только то, когда вы открываете текстовый редактор и пишете большой скрипт для выполнения чего-то сложного — я также имею в виду возможность создавать относительно простые вещи прямо в командной строке. Есть много ситуаций, когда вам хотелось бы использовать немного логики, но это не настолько большое или повторно используемое, что вы захотели бы его сохранять. Должно быть легко создавать «однострочники» вроде «остановиться на CreateFile, если открываемый файл находится на рабочем столе пользователя, а функция Blah находится в стеке».

Почему PowerShell?

Позвольте мне внести ясность: мне потребовалось примерно 4 года, чтобы «согреться» к PowerShell. Я считаю, что у него есть острые углы, аспекты, которые просто сложны, и множество ошибок как в дизайне, так и в реализации. Иногда это меня очень раздражает. Однако преимущества PowerShell убедительны и убедили меня, что это лучший выбор для этого проекта:

• Это одновременно среда сценариев и среда CLI. Тот факт, что он должен выполнять обе функции, приводит к некоторым негативным моментам, таким как более крутая кривая обучения, но в конечном итоге это чрезвычайно удобно, потому что вы хотите иметь возможность быстро делать что-то в командной строке REPL, а также писать полнофункциональные, надёжные сценарии.
• Он очень «обнаруживаем» — такие вещи, как Get-Command, автодополнение по Tab, возможность предоставления иерархических данных, подобных файловой системе, средства для предоставления и синтеза справки — всё это очень хорошо.
• Автодополнение по Tab. Я знаю, что упомянул это в предыдущем пункте, но оно настолько замечательно, что заслуживает отдельного пункта.
• Конвейер объектов: объектно-ориентированная природа конвейера PowerShell настолько мощнее и проще в использовании, чем старые дни скриптов на основе синтаксического анализа строк, что это даже не смешно. Представьте себе выполнение "dt" для «дампа» «объекта» и получение реального объекта. DbgShell это делает.
• Люди его знают: я оцениваю, что количество людей, знающих PowerShell и/или C#, по крайней мере на несколько порядков больше, чем количество людей, знающих методы скриптинга windbg. Это означает, что больше людей смогут легко «освоить» отладчик на основе PowerShell; а также, когда людям понадобится помощь, пул потенциальных помощников будет намного больше (во всяком случае, для проблем, связанных со скриптингом).
• PowerShell по-прежнему является оболочкой общего назначения: при использовании DbgShell у вас есть доступ не только к командам отладчика, но вы можете "cd" в файловую систему, реестр, AD и т.д.; вы можете выполнять Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod, запускать произвольные программы и т.д.

Текущее состояние

DbgShell долгое время находился в «режиме прототипирования». Я потратил много времени на выяснение того, как что-то могло бы или должно быть сделано, но не обязательно «доделывая» всё. В текущем коде есть огромное количество TODO. Так что, хотя он уже начал становиться полезным, проект всё ещё довольно сырой. Тем не менее, он определённо может продемонстрировать достаточно, чтобы дать вам хорошее представление о том, каким он должен быть.

Ниже приведены несколько скриншотов. Важно отметить, что всё, что вы видите, не является текстовым выводом dbgeng. Хотя некоторые элементы вывода будут выглядеть знакомо, это только потому, что я использовал функции форматирования и вывода PowerShell для настройки отображения определённых объектов — весь вывод, который вы видите, на самом деле соответствует реальным, полноценным объектам .NET. Например, каждое сообщение ModLoad соответствует объекту MS.Dbg.ModuleLoadedEventArgs, который имеет больше свойств, чем отображается при отправке в Out-Default. Никакого синтаксического анализа строк из dbgeng не происходит. (Ну... почти. Я пошёл на несколько компромиссов, где нет другого способа получить информацию. Например, дизассемблирование или разбор символического имени функции-регулятора adjustor thunk для поиска смещения.)

Это своего рода сценарий «hello world»: подключение к экземпляру cmd.exe. Я сначала использую встроенную команду PowerShell Start-Process, затем передаю вывод команде DbgShell Connect-Process, а затем исследую пространство имён:

Здесь я подключился к тестовой программе, посмотрел стек, переключился на конкретный кадр стека, выгрузил локальные переменные, проверил значение локального std::map и проверил некоторую информацию о типе для локального перечисления. Обратите внимание на отображение значения перечисления: DbgShell не только обрабатывает поиск символьного имени для отдельных значений, но и когда несколько значений объединены через OR. По скриншоту этого не видно, но для всех этих элементов есть автодополнение по Tab.

Заметные особенности

• Цвет: поддержка цветовой раскраски текста с использованием управляющих последовательностей ANSI (в соответствии с ISO/IEC 6429)
• Пользовательский движок форматирования: Не нравится .ps1xml? Мне тоже. В дополнение к стандартным табличным, списочным и пользовательским представлениям можно определять «однострочные» представления, которые очень удобны для настройки отображения значений символов.
• Пользовательское преобразование значений символов: Для большинства переменных преобразование и отображение по умолчанию хороши. Но иногда хочется, чтобы отладчик выполнил немного больше работы за вас. Функция преобразования значений символов позволяет, например, преобразовывать объекты коллекций STL в объекты коллекций .NET, с которыми гораздо проще работать.
• Определение производных типов: Для случаев, когда ваша переменная — это IFoo, но фактический объект — FooImpl.
• Подробная информация о типах: предоставлена для вашего программного удобства.
• В: Работает ли это в WinDbg? Я буду использовать только WinDbg. О: Да — загрузите DLL расширения DbgShellExt.dll, а затем выполните "!dbgshell", чтобы открыть консоль DbgShell.

Текущие недостатки

• Самый большой недостаток на данный момент — отсутствие поддержки режима ядра (если вы уже находитесь в соответствующем контексте, вы можете отображать значения, но вы не можете сменить контекст из DbgShell, и пространство имён не настроено).
• Хотя вы можете загружать и выполнять традиционные расширения отладчика обычным способом, всё ещё отсутствует множество команд windbg.
• Удалённые сеансы не поддерживаются: API dbgeng поддерживает подключение к удалённому отладчику. К сожалению, информация о символах и типах, предоставляемая API dbgeng, критически недостаточна для нужд DbgShell, поэтому DbgShell использует API dbghelp. К сожалению, не существует такого понятия, как удалённый dbghelp. Нам нужно будет поработать с командой отладчика для решения этой проблемы.

Лицензия

Лицензировано в соответствии с MIT.

Вклад

Этот проект приветствует вклад и предложения. Большинство вкладов требует вашего согласия с Лицензионным соглашением с участником (CLA), которое подтверждает, что вы имеете право и действительно предоставляете нам права на использование вашего вклада. Подробности см. на https://cla.microsoft.com.

Когда вы отправляете запрос на включение (pull request), CLA-бот автоматически определит, нужно ли вам предоставить CLA, и соответствующим образом оформит PR (например, метка, комментарий). Просто следуйте инструкциям бота. Вам нужно будет сделать это только один раз для всех репозиториев, использующих наше CLA.

См. Вклад для получения дополнительной информации о вкладе в проект.

Кодекс поведения

Этот проект принял Кодекс поведения Microsoft Open Source.

Для получения дополнительной информации см. Часто задаваемые вопросы о Кодексе поведения или свяжитесь с [email protected] с любыми дополнительными вопросами или комментариями.

Другие темы

• Начало работы с DbgShell

• Цвет

• Пользовательский движок форматирования

• Пользовательское преобразование значений символов

• Определение производных типов

• Подробная информация о типах

• Хакинг DbgShell

• DbgEngWrapper

Короткое (3-минутное) видео-введение можно найти здесь: https://youtu.be/ynbg2zZ1Igc