偵錯工具資料模型 C++ 其他介面

發行項
04/14/2023

本主題描述一些與偵錯工具 C++ 資料模型相關聯的其他介面，例如中繼資料、概念和物件列舉。

偵錯工具資料模型中繼資料介面

資料模型中的其中一個核心概念是物件 (特別是綜合一個) 是索引鍵/值/中繼資料元組的字典。每個索引鍵都可以有與其相關聯的整個中繼資料存放區，描述索引鍵及其潛在值周圍的各種專案。請注意，中繼資料不會以任何方式變更索引鍵的值。它只是與索引鍵及其值相關聯的輔助資訊，可能會影響索引鍵及其值的呈現或其他相關屬性。

在某些情況下，中繼資料存放區與資料模型中物件本質的索引鍵/值/中繼資料元組不同。不過，從這個檢視簡化。中繼資料存放區是由 IKeyStore 介面表示。雖然也是索引鍵/值/中繼資料元組的集合，但中繼資料金鑰存放區與模型物件可以執行的工作有一些限制：

金鑰存放區只能有單一父存放區，它不能有任意的父代模型鏈結。
金鑰存放區沒有概念。它只能有索引鍵/值/中繼資料元組的字典。這表示金鑰存放區中的金鑰是靜態的。動態語言系統無法視需要建立它們。
根據慣例，元資料定義索引鍵存放區中的值僅限於基本值， (內建函式和屬性存取子)

雖然金鑰存放區可以有任意數目的索引鍵 (和任意命名) ，但有某些名稱具有定義的語意值。目前，這些名稱如下：

金鑰名稱	數值類型	描述
PreferredRadix	整數：2、8、10 或 16	指出應該顯示序數值的基數
PreferredFormat	整數：如 PreferredFormat 列舉所定義	指出顯示值的慣用格式類型
PreferredLength	整數	針對陣列和其他容器，表示預設應該顯示多少個元素
FindDerivation	Boolean	指出偵錯主機是否應該先對值執行衍生類型分析，再使用 (例如：顯示)
說明	String	使用者介面可適當地以適當説明的方式呈現金鑰的工具提示樣式解說文字。
ActionName	字串	表示指定的方法 (一個不採用引數，而且不會傳回任何值，) 為動作。動作的名稱是在中繼資料中指定。使用者介面可以利用這個名稱，在操作功能表或其他適當的介面中顯示選項
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

GetKey 方法類似于 IModelObject 上的 GetKey 方法。如果指定的金鑰存在於金鑰存放區或金鑰存放區的父存放區中，則會傳回指定索引鍵的值。請注意，如果索引鍵的值是屬性存取子，則不會在屬性存取子上呼叫 GetValue 方法。實際的 IModelPropertyAccessor Boxed 會傳回 IModelObject。用戶端通常會基於這個原因呼叫 GetKeyValue。

SetKey

SetKey 方法類似于 IModelObject 上的 SetKey 方法。這是唯一能夠建立金鑰，並將中繼資料與金鑰存放區內建立關聯的方法。

GetKeyValue

GetKeyValue 方法是用戶端將移至的第一個方法，以便在中繼資料存放區中尋找特定索引鍵的值。如果索引鍵引數指定的索引鍵存在於存放區內 (或父存放區) ，則會傳回該索引鍵的值及其相關聯的任何中繼資料。如果索引鍵的值是屬性存取子 (IModelPropertyAccessor boxed 到 IModelObject) ，則 GetKeyValue 和傳回之屬性的基礎值會自動呼叫屬性存取子的 GetValue 方法。

SetKeyValue

SetKeyValue 方法類似于 IModelObject 上的 SetKeyValue 方法。此方法無法在中繼資料存放區內建立新的金鑰。如果索引鍵引數指出現有的索引鍵，其值將會設定為指示。如果索引鍵是屬性存取子，則會在屬性存取子上呼叫 SetValue 方法，以設定基礎值。請注意，中繼資料通常會在建立後是靜態的。在中繼資料金鑰存放區上使用這個方法應該不常使用。

ClearKeys

ClearKeys 方法類似于 IModelObject 上的 ClearKeys 方法。它會從指定的中繼資料存放區中移除每個金鑰。這個方法不會影響任何父存放區。

資料模型中的物件列舉

列舉資料模型中的物件

資料模型中有兩個核心索引鍵列舉介面：IKeyEnumerator 和 IRawEnumerator。雖然這些是兩個核心介面，但可用來列舉三種樣式之一中的物件：

索引鍵 - 您可以透過呼叫 EnumerateKeys 來取得 IKeyEnumerator 介面，以便列舉物件的索引鍵及其值/中繼資料，而不需要解析任何基礎屬性存取子。此列舉樣式可以傳回原始 IModelPropertyAccessor 值，並 Boxed 到 IModelObjects 中。

值 - 您可以透過呼叫 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 方法會向前移動列舉值，並傳回列舉中該位置的原生/語言建構。