JavaScript 扩展中的本机调试器对象 - 调试器对象详细信息

本主题介绍有关在 JavaScript 扩展中使用本机调试器对象的其他详细信息。

本机调试器对象表示调试器环境的各种构造和行为。 可以将对象传递到 JavaScript 扩展中或在其中获取，以操控调试器的状态。

有关调试器对象 JavaScript 扩展的信息，请参阅 JavaScript 扩展中的本机调试器对象。

有关使用 JavaScript 的一般信息，请参阅 JavaScript 调试器脚本。

调试器团队在 GitHub 上托管了一个用于 JavaScript 脚本和扩展的存储库。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++.
        //
    }
}

可索引性

能够通过序数在单一维度上进行索引的对象（例如：原生数组）将可以通过标准属性访问运算符 -- object[index] 在 JavaScript 中进行索引。 如果对象可按名称编制索引，或者可在多个维度中编制索引，则 getValueAt 和 setValueAt 方法将投影到对象上，以便 JavaScript 代码可以利用索引器。

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

字符串转换

任何支持通过 IStringDisplayableConcept 或 NatVis DisplayString 元素进行显示字符串转换的本机对象，都可以通过标准的 JavaScript toString 方法来访问该字符串转换。

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

创建本机调试器对象

如前所述，JavaScript 脚本可以通过多种方式之一传递到 JavaScript 来访问本机对象，也可以通过对主机库的调用创建它们。 使用以下函数创建本机调试器对象。

JavaScript 扩展的主机 API（应用程序接口）

JavaScript 提供程序将一个名为主机的对象插入到它加载的每个脚本的全局命名空间中。 此对象提供对脚本的关键功能的访问权限，以及访问调试器的命名空间。 分两个阶段进行设置。

• 阶段 1：在执行任何脚本之前，主机对象仅包含脚本初始化自身和注册其扩展点（作为生成者和使用者）所需的最小功能集。 根代码和初始化代码不打算操纵调试目标的状态或执行复杂操作，因此，在 initializeScript 方法返回之前，主机不会完全初始化。

• 阶段 2：当 initializeScript 返回后，主机对象将被填充用于操作调试目标状态所需的一切内容。

主机对象级别

一些关键功能片段直接位于主机对象下。 其余部分属于子命名空间。 命名空间包括以下内容。

根级别

直接在主机对象中，可以找到以下属性、方法和构造函数。

诊断功能

主机对象的诊断子命名空间包含以下项。

内存功能

主机对象的内存子命名空间包含以下项。

JavaScript 中的数据模型概念

数据模型映射

以下数据模型概念映射到 JavaScript。

字符串转换

字符串转换概念（IStringDisplayableConcept）直接转换为标准 JavaScript toString 方法。 由于所有 JavaScript 对象都有字符串转换（如果未在其他地方提供），因此返回到数据模型的每个 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 的实例。 索引以数组形式作为第二个参数传递给 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 表分析），以便从代码中表示的静态类型确定对象的真实运行时类型。 针对本机类型注册的数据模型可以通过 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 调试器示例脚本