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

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

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

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

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

Например, команда отладчика размещает скрипты и расширения JavaScript в репозитории GitHub по адресу https://github.com/Microsoft/WinDbg-Samples.

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

Передача нативных объектов

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

• Их можно передать в функции или методы JavaScript
• Они могут быть экземпляром объекта прототипа JavaScript (как, например, визуализатор)
• Их можно возвращать из методов узла, предназначенных для создания собственных объектов отладчика.
• Их можно возвращать из методов узла, предназначенных для создания собственных объектов отладчика

Объекты отладчика, передаваемые расширению JavaScript, имеют набор функциональных возможностей, описанных в этом разделе.

• Доступ к свойствам
• Проецируемые имена
• Специальные типы, относящиеся к объектам отладчика в нативной среде
• Дополнительные атрибуты

Доступ к свойствам

Хотя существуют некоторые свойства объектов, размещенных самим поставщиком JavaScript, большинство свойств в стандартных объектах, которые попадают в JavaScript, предоставляются моделью данных. Это означает, что для доступа к свойству --- object.propertyName или object[propertyName], будет происходить следующее.

• Если propertyName — это имя свойства, проецируемого на объект самим поставщиком JavaScript, оно будет обработано в первую очередь; иначе
• Если propertyName — это имя ключа, проецируемого на объект моделью данных (другим визуализатором), то оно будет разрешено на это имя во вторую очередь; в противном случае
• Если propertyName является именем поля нативного объекта, то это имя будет выбрано в третью очередь; иначе
• Если объект является указателем, указатель будет разыменован, и приведенный выше цикл продолжится (проецируемое свойство объекта, затем ключ и затем нативное поле).

Обычные методы доступа к свойствам в JavaScript — object.propertyName и object[propertyName] — предоставляют доступ к внутренним полям объекта, аналогично тому, как делала бы команда 'dx' в отладчике.

Проецируемые имена

Следующие свойства (и методы) проецируются на встроенные объекты, которые входят в среду JavaScript.

Если объект является указателем, следующие свойства (и методы) проецируются на указатель, который вводит JavaScript:

Специальные типы, относящиеся к объектам нативного отладчика

Объекты расположения

Объект расположения, возвращаемый из свойства targetLocation собственного объекта, содержит следующие свойства (и методы).

Дополнительные атрибуты

Итерируемость

Любой объект, который рассматривается как итерируемый моделью данных (это собственный массив или он имеет визуализатор (NatVis или иной), который делает его итерируемым), будет иметь функцию итератора, индексированную стандартным символом ES6 Symbol.iterator, примененную к нему. Это означает, что вы можете итерировать собственный объект в JavaScript следующим образом.

function iterateNative(nativeObject)
{
    for (var val of nativeObject)
    {
        // 
        // val will contain each element iterated from the native object.  This would be each element of an array,
        // each element of an STL structure which is made iterable through NatVis, each element of a data structure
        // which has a JavaScript iterator accessible via [Symbol.iterator], or each element of something
        // which is made iterable via support of IIterableConcept in C/C++.
        //
    }
}

Индексируемость

Объекты, которые понимаются как индексируемые в одном измерении с помощью порядковых номеров (например, собственных массивов), будут индексироваться в JavaScript через стандартный оператор доступа к свойствам - object[index]. Если объект индексируется по имени или индексируется в нескольких измерениях, методы getValueAt и setValueAt будут проецироваться на объект, чтобы код JavaScript смог использовать индексатор.

function indexNative(nativeArray)
{
    var first = nativeArray[0];
}

Преобразование строк

Любой родной объект, имеющий преобразование строки отображения через поддержку IStringDisplayableConcept или элемент NatVis DisplayString, будет иметь доступ к этому преобразованию строк с помощью стандартного метода JavaScript toString.

function stringifyNative(nativeObject)
{
    var myString = nativeObject.toString();
}

Создание собственных объектов отладчика

Как уже упоминалось, скрипт JavaScript может получить доступ к родным объектам, передавая их в JavaScript одним из нескольких способов или создавая их через вызовы к хост-библиотеке. Используйте следующие функции для создания собственных объектов отладчика.

Хост API для расширений JavaScript

Поставщик JavaScript вставляет объект, называемый host, в глобальное пространство имен каждого загружаемого им скрипта. Этот объект предоставляет доступ к критически важным функциям скрипта, а также к пространству имен отладчика. Он настраивается в два этапа.

• Этап 1. Перед выполнением любого скрипта объект узла содержит только минимальный набор функциональных возможностей, необходимых для инициализации скрипта и регистрации точек расширяемости (как производитель, так и потребитель). Корневой код и код инициализации не предназначены для манипуляции состоянием целевого объекта отладки или выполнения сложных операций, и поэтому хост полностью не заполняется до тех пор, пока метод initializeScript не завершит выполнение.

• Этап 2. После возврата из initializeScript хост-объект заполняется всем необходимым для манипулирования состоянием инкубаторов отладки.

Уровень объекта хоста

Несколько ключевых элементов функциональности находятся непосредственно под объектом хоста. Оставшиеся элементы находятся в подпространстве имен. Пространства имен включают следующие.

Корневой уровень

Непосредственно в объекте узла можно найти следующие свойства, методы и конструкторы.

Функции диагностики

Подпространство имен диагностики объекта хоста содержит следующее.

Функциональные возможности памяти

Подпространство имен памяти объекта узла содержит следующее.

Основные понятия модели данных в JavaScript

Сопоставление моделей данных

Следующие концепции модели данных сопоставляются с JavaScript.

Преобразование строк

Концепция преобразования строк (IStringDisplayableConcept) напрямую преобразуется в стандартный метод JavaScript toString . Так как все объекты JavaScript имеют строковое преобразование (предоставленное Object.prototype, если оно не указано в другом месте), каждый объект JavaScript, возвращаемый в модель данных, можно преобразовать в отображаемую строку. Переопределение преобразования строки просто требует реализации собственного метода toString.

class myObject
{
    //
    // This method will be called whenever any native code calls IStringDisplayableConcept::ToDisplayString(...)
    //
    toString()
    { 
        return "This is my own string conversion!";
    }
}

Итерируемость

Концепция модели данных о том, является ли объект итерируемым или не сопоставляется непосредственно с протоколом ES6 о том, является ли объект итерируемым. Любой объект, имеющий метод [Symbol.iterator], считается итератором. Реализация такого объекта сделает объект итерируемым.

Объект, который доступен только для итерации, может иметь реализацию, как показано ниже.

class myObject
{
    //
    // This method will be called whenever any native code calls IIterableConcept::GetIterator
    //
    *[Symbol.iterator]()
    {
        yield "First Value";
        yield "Second Value";
        yield "Third Value";
    }
}

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

Итерируемые и индексируемые

Объект, который является итерируемым и индексируемым, требует специального возвращаемого значения от итератора. Вместо получения значений итератор выдает экземпляры индексированного значения. Индексы передаются как массив во втором аргументе конструктору indexedValue. Они могут быть многомерными, но должны соответствовать размерности, возвращаемой в протоколе индексатора.

В этом коде показан пример реализации.

class myObject
{
    //
    // This method will be called whenever any native code calls IIterableConcept::GetIterator
    //
    *[Symbol.iterator]()
    {
        //
        // Consider this a map which mapped 42->"First Value", 99->"Second Value", and 107->"Third Value"
        //
        yield new host.indexedValue("First Value", [42]);
        yield new host.indexedValue("Second Value", [99]);
        yield new host.indexedValue("Third Value", [107]);
    }
}

Индексируемость

В отличие от JavaScript, модель данных делает очень явное различие между доступом к свойствам и индексированием. Любой объект JavaScript, который хочет представить себя как индексируемый в модели данных, должен реализовать протокол, состоящий из метода getDimensionality, который возвращает размерность индексатора и необязательную пару методов getValueAt и setValueAt, которые выполняют операции чтения и записи объекта при предоставленных наборах. Допустимо пропускать методы getValueAt или setValueAt, если объект доступен только для чтения или только для записи.

class myObject
{
    //
    // This method will be called whenever any native code calls IIndexableConcept::GetDimensionality or IIterableConcept::GetDefaultIndexDimensionality
    //
    getDimensionality()
    {
        //
        // Pretend we are a two dimensional array.
        //
        return 2;
    } 

    //
    // This method will be called whenever any native code calls IIndexableConcept::GetAt
    //
    getValueAt(row, column)
    {
        return this.__values[row * this.__columnCount + column];
    }

    //
    // This method will be called whenever any native code calls IIndexableConcept::SetAt
    //
    setValueAt(value, row, column)
    {
        this.__values[row * this.__columnCount + column] = value;
    }
}

Преобразование типов среды выполнения

Это относится только к прототипам и классам JavaScript, зарегистрированным для встроенных типов системы типов. Отладчик часто способен выполнять анализ (например, Run-Time анализ типа (RTTI) или v-table) для определения истинного типа среды выполнения объекта из статического типа, выраженного в коде. Модель данных, зарегистрированная относительно собственного типа, может изменить это поведение с помощью реализации IPreferredRuntimeTypeConcept. Аналогичным образом, класс JavaScript или прототип, зарегистрированный на родном объекте, может предоставить собственную реализацию через протокол, состоящий из метода getPreferredRuntimeTypedObject.

Несмотря на способность метода возвращать что-либо в техническом плане, считается неправильным, если он фактически возвращает то, что не является типом, применяемым в среде выполнения или производным типом. Это может привести к значительной путанице для пользователей отладчика. Переопределение этого метода может быть полезным для таких вещей, как заголовки в стиле C и объектно-ориентированные стили реализации, и т. д.

class myNativeModel
{
    //
    // This method will be called whenever the data model calls IPreferredRuntimeTypeConcept::CastToPreferredRuntimeType
    //
    getPreferredRuntimeTypedObject()
    {
        var loc = this.targetLocation;

        //
        // Perform analysis...
        //
        var runtimeLoc = loc.Add(runtimeObjectOffset);
  
        return host.createTypedObject(runtimeLoc, runtimeModule, runtimeTypeName);
    }
}

См. также

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

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

Скриптинг для отладки JavaScript

Примеры скриптов отладчика JavaScript