JavaScript 拡張機能のネイティブ デバッガー オブジェクト - デバッガー オブジェクトの詳細

このトピックでは、JavaScript 拡張機能でのネイティブ デバッガー オブジェクトの使用に関する追加の詳細について説明します。

ネイティブ デバッガー オブジェクトは、デバッガー環境のさまざまなコンストラクトと動作を表します。 オブジェクトを JavaScript 拡張機能に渡したり、取得したりして、デバッガーの状態を操作できます。

デバッガー オブジェクトの JavaScript 拡張機能の詳細については、「 JavaScript 拡張機能のネイティブ デバッガー オブジェクト」を参照してください。

JavaScript の操作に関する一般的な情報については、「 JavaScript デバッガー スクリプト」を参照してください。

たとえば、JavaScript スクリプトや拡張機能など、デバッガー チームは https://github.com/Microsoft/WinDbg-Samples で GitHub リポジトリをホストします。

JavaScript 拡張機能のデバッガー オブジェクト

ネイティブ オブジェクトの渡し

デバッガー オブジェクトは、さまざまな方法で JavaScript 拡張機能に渡したり、取得したりできます。

• これらは JavaScript 関数またはメソッドに渡すことができます
• JavaScript プロトタイプのインスタンス オブジェクトを指定できます (ビジュアライザーなど)。
• これらは、ネイティブ デバッガー オブジェクトを作成するように設計されたホスト メソッドから返すことができます
• これらは、デバッガーのネイティブ オブジェクトを作成するように設計されたホスト メソッドから返すことができます

JavaScript 拡張機能に渡されるデバッガー オブジェクトには、このセクションで説明する一連の機能があります。

• プロパティー・アクセス
• 予定名
• ネイティブ デバッガー オブジェクトに関連する特殊な型
• 追加の属性

プロパティ アクセス

JavaScript プロバイダー自体によって配置されるオブジェクトにはいくつかのプロパティがありますが、JavaScript に入るネイティブ オブジェクトのプロパティの大部分はデータ モデルによって提供されます。 つまり、object.propertyName または object[propertyName] ---プロパティ アクセスの場合、次の処理が行われます。

• propertyName が JavaScript プロバイダー自体によってオブジェクトに投影されるプロパティの名前である場合は、最初にこのプロパティに解決されます。然も無くば
• propertyName がデータモデル（別のビジュアライザー）によってオブジェクトに投影されるキーの名前である場合、優先してこの名前が解決されます。そうでない場合は、他の手段で解決されます。
• propertyName がネイティブオブジェクトのフィールド名である場合、この名前は3番目に解決されます。それ以外の場合は
• オブジェクトがポインターの場合、ポインターは逆参照され、上記のサイクルは続行されます (逆参照されたオブジェクトの投影プロパティの後にキーが続き、ネイティブ フィールドが続きます)

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

予測された名前

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

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

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

ロケーションオブジェクト

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

その他の属性

Iterability

データ モデルで反復可能と認識されるオブジェクト (ネイティブ配列であるか、ビジュアライザー (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 が返されると、デバッグ ターゲットの状態を操作するために必要なすべてのものがホスト オブジェクトに設定されます。

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

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

ルート レベル

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

診断機能

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

メモリ機能

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

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

Iterability

データモデルにおけるオブジェクトのiterable判定の概念は、ES6プロトコルにおけるオブジェクトのiterable判定と直接対応しています。 [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";
    }
}

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

反復可能 と インデックス可能

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