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 がデータ モデル (別のビジュアライザー) によってオブジェクトに投影されるキーの名前である場合、この名前は 2 番目に解決されます。それ以外の場合は解決されます。
• propertyName がネイティブ オブジェクトのフィールドの名前である場合、この名前は 3 番目に解決されます。それ以外の場合は解決されます。
• オブジェクトがポインターの場合、ポインターは逆参照され、上記のサイクルは続行されます (逆参照されたオブジェクトの投影プロパティの後にキーが続き、ネイティブ フィールドが続きます)

JavaScript でのプロパティ アクセスの通常の手段 -- object.propertyName と object[propertyName] -- は、デバッガー内の 'dx' コマンドと同様に、オブジェクトの基になるネイティブ フィールドにアクセスします。

投影名

次のプロパティ (およびメソッド) は、JavaScript を入力するネイティブ オブジェクトに投影されます。

オブジェクトがポインターの場合、次のプロパティ (およびメソッド) が JavaScript に入るポインターに投影されます。

ネイティブ デバッガー オブジェクトに関連する特殊な型

位置オブジェクト

ネイティブ オブジェクトの targetLocation プロパティから返される ___location オブジェクトには、次のプロパティ (およびメソッド) が含まれています。

追加の属性

反復可能性

データ モデルで反復可能と認識されるオブジェクト (ネイティブ配列であるか、ビジュアライザー (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++.
        //
    }
}

インデックス可能性

序数 (ネイティブ配列など) を介して 1 つの次元でインデックス可能と認識されるオブジェクトは、標準のプロパティ アクセス演算子 -- object[index] を使用して JavaScript でインデックスを作成できます。 オブジェクトが名前でインデックス可能であるか、複数のディメンションでインデックスを作成できる場合、javaScript コードがインデクサーを利用できるように、getValueAt メソッドと setValueAt メソッドがオブジェクトに投影されます。

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

文字列変換

IStringDisplayableConcept または NatVis DisplayString 要素のサポートによる表示文字列変換を持つネイティブ オブジェクトは、標準の JavaScript toString メソッドを使用してその文字列変換にアクセスできます。

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

ネイティブ デバッガー オブジェクトの作成

メンションしたように、JavaScript スクリプトは、いくつかの方法のいずれかで JavaScript に渡すことでネイティブ オブジェクトにアクセスできます。また、ホスト ライブラリの呼び出しを通じて作成することもできます。 ネイティブ デバッガー オブジェクトを作成するには、次の関数を使用します。

JavaScript 拡張機能のホスト API

JavaScript プロバイダーは、ホストと呼ばれるオブジェクトを、読み込むすべてのスクリプトのグローバル名前空間に挿入します。 このオブジェクトは、スクリプトの重要な機能へのアクセスと、デバッガーの名前空間へのアクセスを提供します。 これは 2 つのフェーズで設定されます。

• フェーズ 1: スクリプトを実行する前に、ホスト オブジェクトには、スクリプト自体を初期化してその拡張ポイント (プロデューサーとコンシューマーの両方) を登録するために必要な最小限の機能セットのみが含まれます。 ルートコードと初期化コードは、デバッグ ターゲットの状態を操作したり、複雑な操作を実行したりするためのものではありません。そのため、initializeScript メソッドが戻るまで、ホストは完全には設定されません。

• フェーズ 2: initializeScript が返されると、デバッグ ターゲットの状態を操作するために必要なすべてのものがホスト オブジェクトに設定されます。

ホスト オブジェクト レベル

いくつかの重要な機能は、ホスト オブジェクトのすぐ下にあります。 reメインder はサブ名前空間です。 名前空間には次のものが含まれます。

ルートレベル

ホスト オブジェクト内で直接、次のプロパティ、メソッド、およびコンストラクターを見つけることができます。

診断機能

ホスト オブジェクトの 診断 サブ名前空間には、次のものが含まれています。

メモリ機能

ホスト オブジェクトのメモリ サブ名前空間には次のものが含まれます。

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!";
    }
}

反復可能性

オブジェクトが iterable かどうかを示すデータ モデルの概念は、オブジェクトが iterable かどうかを示す ES6 プロトコルに直接マップされます。 [Symbol.iterator] メソッドを持つオブジェクトは、反復可能と見なされます。 このような実装により、オブジェクトが iterable になります。

iterable だけのオブジェクトは、次のような実装を持つことができます。

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";
    }
}

反復子から返されるオブジェクトには、インデックスと特殊な戻り値の型を使用する値を含める必要があるため、反復可能なオブジェクトとインデックス可能なオブジェクトの両方に対して特別な考慮事項を指定する必要があります。

Iterable と Indexable

反復可能でインデックス付け可能なオブジェクトには、反復子からの特別な戻り値が必要です。 反復子は、値を生成する代わりに、indexedValue のインスタンスを生成します。 indicies は、2 番目の引数の配列として 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 プロトタイプ/クラスにのみ関連します。 デバッガーは、多くの場合、分析 (ランタイム型情報 (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 デバッガーのスクリプト例