Собственные объекты отладчика в расширениях JavaScript — рекомендации по проектированию и тестированию

Статья
11/15/2023

В этом разделе описываются рекомендации по проектированию и тестированию для использования собственных объектов отладчика в расширениях JavaScript.

Собственные объекты отладчика представляют различные конструкции и поведения среды отладчика. Объекты можно передавать в расширения JavaScript (или получать в) для управления состоянием отладчика.

Сведения о расширениях JavaScript для объектов отладчика см. в разделе Собственные объекты отладчика в расширениях JavaScript.

Общие сведения о работе с JavaScript см. в разделе Скрипты отладчика JavaScript.

Рекомендации по проектированию модели данных отладчика

Принципы проектирования

Рассмотрите следующие принципы, чтобы расширения отладчика отображали информацию, которая доступна для обнаружения, создания запросов и создания сценариев.

Информация близка к тому, где она необходима. Например, сведения о разделе реестра должны отображаться как часть локальной переменной, содержащей дескриптор раздела реестра.
Информация структурирована. Например, сведения о разделе реестра представлены в отдельных полях, таких как тип ключа, список ACL ключа, имя ключа и значение. Это означает, что доступ к отдельным полям можно получить без анализа текста.
Информация является согласованной. Сведения о дескрипторах разделов реестра представлены так же, как и сведения о дескрипторах файлов.

Избегайте этих подходов, которые не поддерживают эти принципы.

Не структурируйте свои предметы в одну плоскую "Кухонную раковину". Организованная иерархия позволяет пользователям искать нужные сведения без предварительного знания о том, что они ищут, и поддерживает возможность обнаружения.
Не преобразуйте классическое расширение dbgeng, просто переместив его в модель, по-прежнему выводя экраны необработанного текста. Он не компонуется с другими расширениями и не может запрашиваться с помощью выражений LINQ. Вместо этого разбейте данные на отдельные поля, доступные для запроса.

Правила именования

Заглавная буква полей должна иметь значение PascalCase. Исключение можно рассмотреть для имен, широко известных в другом регистре, например jQuery.
Избегайте использования специальных символов, которые обычно не используются в идентификаторе C++. Например, избегайте использования таких имен, как "Общая длина" (содержит пробел) или "[размер]" (содержащий квадратные скобки). Это соглашение упрощает использование языков сценариев, где эти символы не допускаются в составе идентификаторов, а также упрощает использование из командного окна.

Руководство по организации и иерархии

Не расширяйте верхний уровень пространства имен отладчика. Вместо этого следует расширить существующий узел в отладчике, чтобы информация отображалась там, где она наиболее актуальна.
Не дублируйте понятия. Если вы создаете расширение модели данных, которое содержит дополнительные сведения о концепции, уже существующей в отладчике, расширьте существующие сведения, а не пытайтесь заменить их новыми сведениями. Иными словами, расширение, отображающее сведения о модуле, должно расширять существующий объект Module , а не создавать новый список модулей.
Бесплатные плавающие служебные команды должны быть частью пространства имен Debugger.Utility . Они также должны быть соответствующими вложенными пространствами имен (например , Debugger.Utility.Collections.FromListEntry).

Обратная совместимость и критические изменения

Опубликованный скрипт не должен нарушать совместимость с другими скриптами, которые от него зависят. Например, если функция публикуется в модели, она должна оставаться в том же расположении и с теми же параметрами, когда это возможно.

Отсутствие использования внешних ресурсов

Расширения не должны порождать внешние процессы. Внешние процессы могут влиять на поведение отладчика и будут неправильно вести себя в различных сценариях удаленного отладчика (например, dbgsrv remotes, ntsd remotes и "ntsd -d remotes").
Расширения не должны отображать пользовательский интерфейс. Отображение элементов пользовательского интерфейса будет неправильно работать в сценариях удаленной отладки и может нарушить сценарии отладки консоли.
Расширения не должны управлять подсистемой отладчика или пользовательским интерфейсом отладчика с помощью недокументированных методов. Это приводит к проблемам совместимости и будет неправильно работать на клиентах отладчика с другим пользовательским интерфейсом.
Расширения должны получать доступ к целевой информации только через задокументированные API отладчика. Попытка получить доступ к сведениям о целевом объекте через API Win32 приведет к сбою для многих удаленных сценариев и даже для некоторых локальных сценариев отладки за пределами безопасности.

Не используются специальные функции Dbgeng

Скрипты, предназначенные для использования в качестве расширений, не должны по возможности полагаться на функции dbgeng (например, выполнение "классических" расширений отладчика). Скрипты должны использоваться поверх любого отладчика, в котором размещена модель данных.

Тестирование расширений отладчика

Ожидается, что расширения будут работать в широком спектре сценариев. Хотя некоторые расширения могут быть характерными для сценария (например, сценария отладки ядра), большинство расширений должны работать во всех сценариях или содержать метаданные, указывающие на поддерживаемые сценарии.

Режим ядра