調試程序數據模型C++其他介面

發行項
07/16/2024

本主題描述與調試程式C++數據模型相關聯的一些其他介面，例如元數據、概念和物件列舉。

調試程序數據模型元數據介面

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

從某種意義上說，元數據存放區與數據模型中對象本質的索引鍵/值/元數據元組不同。不過，從這個檢視簡化。元數據存放區是由 IKeyStore 介面表示。雖然也是索引鍵/值/元數據元組的集合，但元數據密鑰存放區與模型物件可以執行的工作有一些限制：

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

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

金鑰名稱	值類型	描述
PreferredRadix	整數：2、8、10 或 16	指出應該在中顯示序數值的基數
PreferredFormat	整數：如 PreferredFormat 列舉所定義	指出顯示值的慣用格式類型
PreferredLength	整數	針對陣列和其他容器，表示預設應該顯示多少個元素
FindDerivation	布林值	指出偵錯主機在使用之前是否應該對值執行衍生類型分析（例如：顯示）
說明	String	索引鍵的工具提示樣式說明文字，其可由使用者介面以適當説明的方式呈現。
ActionName	String	表示指定的方法（不採用任何自變數且不傳回任何值）是一個動作。動作的名稱是在元數據中指定。使用者介面可以利用這個名稱，在操作功能表或其他適當的介面中顯示選項
ActionIsDefault	布林值	只有在指定 ActionName 索引鍵時才有效，表示這是對象的預設動作。
ActionDescription	String	只有在指定 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 方法。實際的IModelPropertyAccessor Boxed 到IModelObject 將會傳回。用戶端通常會基於這個原因呼叫 GetKeyValue。

SetKey

SetKey 方法類似於 IModelObject 上的 SetKey 方法。這是唯一能夠建立密鑰的方法，並將元數據與金鑰存放區內產生關聯。

GetKeyValue

GetKeyValue 方法是用戶端將移至的第一個方法，以便尋找元數據存放區中特定索引鍵的值。如果key自變數所指定的索引鍵存在於存放區中（或它是父存放區），則會傳回該索引鍵的值及其相關聯的任何元數據。如果索引鍵的值是屬性存取子（IModelPropertyAccessor Boxed 到 IModelObject 中），屬性存取子的 GetValue 方法會自動由 GetKeyValue 呼叫，並傳回屬性的基礎值。

SetKeyValue

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

ClearKeys

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

數據模型中的物件列舉

列舉數據模型中的物件

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

索引鍵 - IKeyEnumerator 介面可以透過呼叫 EnumerateKeys 來取得，以便列舉物件的索引鍵及其值/元數據，而不解析任何基礎屬性存取子。此列舉樣式可以將格式化為IModelObjects的原始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

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