Debugger Data Model C++ のその他のインターフェイス
このトピックでは、メタデータ、概念、オブジェクト列挙など、デバッガー C++ データ モデルに関連付けられているいくつかの追加のインターフェイスについて説明します。
デバッガー データ モデル メタデータ インターフェイス
データ モデルの中心概念の 1 つは、オブジェクト (特に合成型) がキー/値/メタデータ タプルのディクショナリであるという点です。 各キーには、キーとその潜在的な値を取り巻くさまざまな事柄を説明する、それに関連付けられたメタデータのストア全体を含めることができます。 メタデータでは、キーの値は変更されないことに注意してください。 これは、キーとその値に関連付けられた単なる補助情報であり、キーとその値のプレゼンテーションまたはその他の関連属性に影響を与える可能性があります。
ある意味では、メタデータ ストアは、データ モデル内のオブジェクトの本質であるキー/値/メタデータのタプルとそれほど変わりません。 ただし、このビューからは簡略化されています。 メタデータ ストアは、IKeyStore インターフェイスによって表されます。 キー/値/メタデータ タプルのコレクションでもありますが、メタデータ キー ストアとモデル オブジェクトで実行できることには制限があります。
- キー ストアには、単一の親ストアのみを含めることができます。任意の親モデルのチェーンを持つことはできません。
- キー ストアには概念はありません。 キー/値/メタデータタプルのディクショナリのみを持つことができます。 つまり、キー ストアに存在するキーは静的です。 動的言語システムでは、必要に応じて作成することはできません。
- 慣例のみにより、メタデータ定義のキー ストア内の値は基本値 (組み込みおよびプロパティ アクセサー) に制限されます。
キー ストアにはキーの任意の数 (および任意の名前付け) を指定できますが、セマンティック値が定義されている特定の名前があります。 現在、これらの名前は次のとおりです。
| キーの名称 | Value タイプ | 説明 |
|---|---|---|
| PreferredRadix | 整数: 2、8、10、または 16 | 順序値をどの基数で表示するかを示します |
| PreferredFormat | 整数: PreferredFormat 列挙型で定義されているとおり | 値の表示に推奨される書式設定タイプを示します。 |
| PreferredLength | 整数型 | 配列およびその他のコンテナーの場合、既定で表示される要素の数を示します。 |
| FindDerivation | Boolean | デバッグ ホストが値を使用する前に派生型分析を実行する必要があるかどうかを示します (例: 表示)。 |
| ヘルプ | String | 適切に役立つ方法でユーザー インターフェイスに表示できる、キーのツール ヒント スタイルのヘルプ テキストです。 |
| ActionName | String | 指定されたメソッド (引数を取らず、値も返さないメソッド) がアクションであることを示します。 アクションの名前はメタデータで指定されます。 ユーザー インターフェイスはこの名前を利用して、コンテキスト メニューまたは他の適切なインターフェイスにオプションを表示できます。 |
| ActionIsDefault | Boolean | ActionName キーが指定されている場合にのみ有効で、これがオブジェクトの既定のアクションであることを示します。 |
| ActionDescription | String | ActionName キーが指定されている場合にのみ有効で、アクションのツールヒント スタイルの説明が与えられます。 このようなテキストは、ユーザー インターフェイスによって適切に役立つ方法で表示できます。 |
メタデータ ストア内のキーには独自のメタデータ (無限) を含めることができますが、現時点ではそのような用途はないことに注意してください。 ほとんどの呼び出し元は、IKeyStore インターフェイスのメソッドのメタデータ パラメーターに null を指定します。
コア メタデータ インターフェイス: IKeyStore
IKeyStore インターフェイスは次のように定義されます。
DECLARE_INTERFACE_(IKeyStore, IUnknown)
{
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_ IModelObject* object) PURE;
STDMETHOD(ClearKeys)() PURE;
}
GetKey メソッドは、IModelObject の GetKey メソッドに似ています。 指定されたキーがキー ストアまたはキー ストアの親ストアに存在する場合は、そのキーの値を返します。 キーの値がプロパティ アクセサーである場合、GetValue メソッドはプロパティ アクセサーでは呼び出されないことに注意してください。 IModelObject にボックス化された実際の IModelPropertyAccessor が返されます。 通常、クライアントはこの理由で GetKeyValue を呼び出します。
SetKey メソッドは、IModelObject の SetKey メソッドに似ています。 これは、キーを作成し、キー ストア内でキーにメタデータを関連付けることができる唯一の方法です。
GetKeyValue メソッドは、クライアントがメタデータ ストア内の特定のキーの値を見つけるために使用する最初のメソッドです。 キー引数で指定されたキーがストア (またはその親ストア) 内に存在する場合、そのキーの値とそれに関連付けられたメタデータが返されます。 キーの値がプロパティ アクセサー (IModelObject にボックス化された IModelPropertyAccessor) の場合、プロパティ アクセサーの GetValue メソッドが GetKeyValue によって自動的に呼び出され、プロパティの基になる値が返されます。
SetKeyValue メソッドは、IModelObject の SetKeyValue メソッドに似ています。 このメソッドでは、メタデータ ストア内に新しいキーを作成できません。 キー引数で示される既存のキーが存在する場合、その値は示されたとおりに設定されます。 キーがプロパティ アクセサーの場合、基になる値を設定するために、プロパティ アクセサーで SetValue メソッドが呼び出されます。 メタデータは通常、一度作成されると静的であることに注意してください。 メタデータ キー ストアでこのメソッドを使用する頻度は低くなります。
ClearKeys メソッドは、IModelObject の ClearKeys メソッドに似ています。 指定されたメタデータ ストアからすべてのキーが削除されます。 このメソッドは親ストアには影響しません。
データ モデルのオブジェクト列挙
データ モデル内のオブジェクト列挙
データ モデルには、IKeyEnumerator と IRawEnumerator の 2 つの主要な列挙インターフェイスがあります。 これらは 2 つのコア インターフェイスですが、次の 3 つのスタイルのいずれかでオブジェクトを列挙するために使用できます。
キー - IKeyEnumerator インターフェイスは、オブジェクトのキーとその値/メタデータを列挙するために、基になるプロパティ アクセサーを解決せずに EnumerateKeys の呼び出しを介して取得できます。 この列挙スタイルでは、IModelObject にボックス化された生の IModelPropertyAccessor 値を返すことができます。
値 - IKeyEnumerator インターフェイスと IRawEnumerator インターフェイスは、オブジェクトのキー/生の値とその値/メタデータを列挙するために、EnumerateKeyValues または EnumerateRawValues への呼び出しを介して取得できます。 列挙内に存在するプロパティ アクセサーは、そのような列挙中に基になる GetValue メソッドの呼び出しによって自動的に解決されます。
参照 - IKeyEnumerator インターフェイスと IRawEnumerator インターフェイスは、オブジェクトのキー/生の値への参照を列挙するために、EnumerateKeyReferences または EnumerateRawReferences のいずれかの呼び出しを介して取得できます。 このような参照は保存でき、後で基になるキーまたは生の値を取得または設定するために使用できます。
KeyEnumerator: 合成キーの列挙
IKeyEnumerator インターフェイスは、インスタンス オブジェクト内のすべてのキー (キー、値、または参照による) およびその親モデル チェーン内の関連するすべての親モデルを列挙するための単一のインターフェイスです。 このインターフェイスは次のように定義されます。
DECLARE_INTERFACE_(IKeyEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR* key, _COM_Errorptr_opt_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
}
Reset メソッドは、列挙子を最初に取得したときの位置 (例: 列挙型の最初の要素の前) にリセットします。 後続の GetNext の呼び出しでは、最初に列挙されたキーが返されます。
GetNext メソッドは、列挙子を前方に移動し、列挙内のその位置にあるキーを返します。
IRawEnumerator: ネイティブ言語または基になる言語 (C/C++) コンストラクトの列挙
IRawEnumerator インターフェイスは、デバッグ ターゲットのアドレス空間内のネイティブ構成体を表すオブジェクト内のすべてのネイティブ/言語構成体を (値または参照によって) 列挙するための単一のインターフェイスです。 このインターフェイスは次のように定義されます。
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
Reset メソッドは、列挙子を最初に取得したときの位置 (例: 列挙型の最初の要素の前) にリセットします。 後続の GetNext の呼び出しでは、最初に列挙されたネイティブ/言語構造が返されます。
GetNext メソッドは、列挙子を前方に移動し、列挙内のその位置にあるネイティブ/言語構造を返します。
関連項目
このトピックは、C++ からアクセスできるインターフェイス、それらを使用して C++ ベースのデバッガー拡張機能を構築する方法、および C++ データ モデル拡張機能から他のデータ モデル構造 (JavaScript や NatVis など) を利用する方法を説明するシリーズの一部です。
Debugger Data Model C++ のインターフェイス
Debugger Data Model C++ のオブジェクト
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示