调试器数据模型 C++ 的其他接口

2025-03-27

本主题介绍与调试器C++数据模型关联的一些附加接口，例如元数据、概念和对象枚举。

调试器数据模型元数据接口

数据模型中的核心概念之一是对象（尤其是合成对象）是键/值/元数据元组的字典。每个键可以有一个完整的元数据存储，用于描述键及其潜在值周围的各种内容。请注意，元数据不会以任何方式更改键的值。它只是与键及其值关联的辅助信息，可能会影响键及其值的呈现或其他关联属性。

从某种意义上说，元数据存储与作为数据模型中对象本质的键/值/元数据元组不同。但是，它已从此视图中简化。元数据存储由 IKeyStore 接口表示。同时，键/值/元数据元组的集合，但元数据密钥存储与模型对象可以执行的作有一些限制：

密钥存储只能有一个父存储 -- 它不能具有任意父模型链。
密钥存储没有概念。它只能有键/值/元数据元组的字典。这意味着密钥存储中存在的密钥是静态的。动态语言系统无法按需创建它们。
根据约定，元数据定义的密钥存储中的值仅限于基本值（内部函数和属性访问器）

虽然密钥存储可以具有任意数量的键（和任意命名），但某些名称具有定义的语义值。目前，这些名称为：

密钥名称	值类型	说明
PreferredRadix	整数：2、8、10 或 16	指示应在哪个弧度中显示序号值
PreferredFormat	整数：由 PreferredFormat 枚举定义	指示用于显示值的首选格式类型
PreferredLength	整数	对于数组和其他容器，指示默认情况下应显示多少个元素
FindDerivation	布尔值	指示调试主机在使用前是否应对值执行派生类型分析（例如：显示）
帮助	字符串	用户界面可以以适当有用的方式呈现的键的工具提示样式帮助文本。
ActionName	字符串	指示给定的方法（不采用任何参数且不返回任何值）是一个作。作的名称在元数据中指定。用户界面可以利用此名称在上下文菜单或其他适当的界面中显示该选项
ActionIsDefault	布尔值	仅当指定 ActionName 键时有效，指示这是对象的默认作。
ActionDescription	字符串	仅当指定 ActionName 键时有效，这才为作提供工具提示样式说明。此类文本可以通过用户界面以适当有用的方式呈现。

请注意，虽然元数据存储中的键可以有自己的元数据（ad infiniteum），但目前没有此类用途。大多数调用方将在 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

GetKey 方法类似于 IModelObject 上的 GetKey 方法。如果指定键存在于密钥存储或密钥存储的父存储中，它将返回指定键的值。请注意，如果键的值是属性访问器，则不会对属性访问器调用 GetValue 方法。将返回 IModelObject 中装箱的实际 IModelPropertyAccessor。通常，客户端会出于此原因调用 GetKeyValue。

SetKey

SetKey 方法类似于 IModelObject 上的 SetKey 方法。它是唯一能够创建密钥并在密钥存储中关联元数据的方法。

GetKeyValue

GetKeyValue 方法是客户端将转到的第一种方法，以便在元数据存储中查找特定键的值。如果由密钥参数指定的键存在于存储区（或它是父存储），则返回该键的值及其关联的任何元数据。如果键的值是属性访问器（将 IModelPropertyAccessor 装箱到 IModelObject 中），则属性访问器的 GetValue 方法将自动由 GetKeyValue 和返回的属性的基础值调用。

SetKeyValue

SetKeyValue 方法类似于 IModelObject 上的 SetKeyValue 方法。此方法无法在元数据存储中创建新密钥。如果键参数指示存在现有键，则会按指示设置其值。如果键是属性访问器，则会对属性访问器调用 SetValue 方法以设置基础值。请注意，创建元数据后通常为静态元数据。对元数据密钥存储使用此方法不常。

ClearKeys

ClearKeys 方法类似于 IModelObject 上的 ClearKeys 方法。它将从给定的元数据存储中删除每个密钥。此方法对任何父存储没有任何影响。

数据模型中对象枚举

在数据模型中枚举对象

数据模型中有两个核心键枚举接口：IKeyEnumerator 和 IRawEnumerator。虽然它们是两个核心接口，但它们可用于枚举三种样式中的一个对象：

键 - 可以通过调用 EnumerateKeys 来获取 IKeyEnumerator 接口，以便枚举对象的键及其值/元数据，而无需解析任何基础属性访问器。此枚举样式可以返回装箱到 IModelObjects 的原始 IModelPropertyAccessor 值。

值 - 可以通过调用 EnumerateKeyValues 或 EnumerateRawValues 来获取 IKeyEnumerator 和 IRawEnumerator 接口，以便枚举对象的键/原始值及其值/元数据。枚举中存在的任何属性访问器都通过调用基础 GetValue 方法在此类枚举期间自动解析。

引用 - 可以通过调用 EnumerateKeyReferences 或 EnumerateRawReferences 来获取 IKeyEnumerator 和 IRawEnumerator 接口，以便枚举对对象的键/原始值的引用。可以保存此类引用，稍后用于获取或设置基础键或原始值。

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

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

GetNext 方法将枚举器向前移动，并返回枚举中该位置的本机/语言构造。