這些函式和宣告是全域協助程式函式，可用於在 C++ 中實作偵錯引擎、表達式評估工具及符號提供者。
注意
目前沒有這些函式和宣告的Managed版本。
若要讓 Visual Studio 使用的偵錯引擎、表達式評估工具及符號提供者，必須註冊它們。 這是藉由設定登錄子機碼和專案來完成，否則稱為「設定計量」。下列全域函式旨在簡化更新這些計量的程式。 請參閱登錄位置一節，以了解這些功能所更新之每個登錄子機碼的配置。
一般計量函式
這些是偵錯引擎所使用的一般函式。 表達式評估工具與符號提供者的特製化函式稍後會詳細說明。
GetMetric 方法
從登錄擷取計量值。
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| 參數 | 描述 |
|---|---|
| pszMachine | [in]將寫入登錄的可能遠端電腦名稱（NULL 表示本機電腦）。 |
| pszType | [in]其中一種計量類型。 |
| guidSection | [in]特定引擎的 GUID、評估工具、例外狀況等。這會指定特定專案之計量類型底下的子區段。 |
| pszMetric | [in]要取得的計量。 這會對應至特定值名稱。 |
| pdwValue | [in]計量中值的儲存位置。 GetMetric 有數種類別可以傳回 DWORD（如此範例所示）、BSTR、GUID 或 GUID 陣列。 |
| pszAltRoot | [in]要使用的替代登錄根目錄。 設定為 NULL 以使用預設值。 |
SetMetric 方法
在登錄中設定指定的計量值。
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| 參數 | 描述 |
|---|---|
| pszType | [in]其中一種計量類型。 |
| guidSection | [in]特定引擎的 GUID、評估工具、例外狀況等。這會指定特定專案之計量類型底下的子區段。 |
| pszMetric | [in]要取得的計量。 這會對應至特定值名稱。 |
| dwValue | [in]計量中值的儲存位置。 SetMetric 有數種類型可以儲存 DWORD（在此範例中）、BSTR、GUID 或 GUID 陣列。 |
| fUserSpecific | [in]TRUE 是表示 如果計量是使用者特定的，而且是否應該寫入使用者的 Hive，而不是本機電腦 Hive。 |
| pszAltRoot | [in]要使用的替代登錄根目錄。 設定為 NULL 以使用預設值。 |
RemoveMetric 方法
從登錄中移除指定的計量。
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| 參數 | 描述 |
|---|---|
| pszType | [in]其中一種計量類型。 |
| guidSection | [in]特定引擎的 GUID、評估工具、例外狀況等。這會指定特定專案之計量類型底下的子區段。 |
| pszMetric | [in]要移除的計量。 這會對應至特定值名稱。 |
| pszAltRoot | [in]要使用的替代登錄根目錄。 設定為 NULL 以使用預設值。 |
EnumMetricSections 方法
列舉登錄中的各種計量區段。
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| 參數 | 描述 |
|---|---|
| pszMachine | [in]將寫入登錄的可能遠端電腦名稱（NULL 表示本機電腦）。 |
| pszType | [in]其中一種計量類型。 |
| rgguidSections | [in， out]要填入之 GUID 的預先配置數位。 |
| pdwSize | [in]可以儲存在陣列中的 rgguidSections GUID 數目上限。 |
| pszAltRoot | [in]要使用的替代登錄根目錄。 設定為 NULL 以使用預設值。 |
表達式評估工具函式
| 函式 | 描述 |
|---|---|
| GetEEMetric | 從登錄擷取計量值。 |
| SetEEMetric | 在登錄中設定指定的計量值。 |
| RemoveEEMetric | 從登錄中移除指定的計量。 |
| GetEEMetricFile | 從指定的計量取得檔名，並載入它，並以字串的形式傳回檔案內容。 |
例外狀況函式
| 函式 | 描述 |
|---|---|
| GetExceptionMetric | 從登錄擷取計量值。 |
| SetExceptionMetric | 在登錄中設定指定的計量值。 |
| RemoveExceptionMetric | 從登錄中移除指定的計量。 |
| RemoveAllExceptionMetrics | 從登錄中移除所有例外狀況計量。 |
符號提供者函式
| 函式 | 描述 |
|---|---|
| GetSPMetric | 從登錄擷取計量值。 |
| SetSPMetric | 在登錄中設定指定的計量值。 |
| RemoveSPMetric | 從登錄中移除指定的計量。 |
列舉函式
| 函式 | 描述 |
|---|---|
| EnumMetricSections | 列舉指定計量類型的所有計量。 |
| EnumDebugEngine | 列舉已註冊的偵錯引擎。 |
| EnumEEs | 列舉已註冊的表達式評估工具。 |
| EnumExceptionMetrics | 列舉所有例外狀況計量。 |
度量定義
這些定義可用於預先定義的計量名稱。 這些名稱會對應至各種登入機碼和值名稱，而且全都定義為寬字元字串：例如 extern LPCWSTR metrictypeEngine。
| 預先定義的計量類型 | 描述：的基底索引鍵。 |
|---|---|
| metrictypeEngine | 所有偵錯引擎計量。 |
| metrictypePortSupplier | 所有埠供應商計量。 |
| metrictypeException | 所有例外狀況計量。 |
| metricttypeEEExtension | 所有表達式評估工具延伸模組。 |
| 偵錯引擎屬性 | 描述 |
|---|---|
| metricAddressBP | 設定為非零，表示支援位址斷點。 |
| metricAlwaysLoadLocal | 設定為非零，以便一律在本機載入偵錯引擎。 |
| metricLoadInDebuggeeSession | 未使用 |
| metricLoadedByDebuggee | 設定為非零，表示偵錯引擎一律會載入偵錯引擎，或由正在偵錯的程式載入。 |
| metricAttach | 設定為非零，表示支援現有程式的附件。 |
| metricCallStackBP | 設定為非零，表示支援呼叫堆疊斷點。 |
| metricConditionalBP | 設定為非零，表示支援條件斷點設定。 |
| metricDataBP | 設定為非零，表示支援數據變更的斷點設定。 |
| metricDisassembly | 設定為非零，表示支援反組譯碼清單的生產。 |
| metricDumpWriting | 設定為非零，表示支持傾印寫入（將記憶體傾印至輸出裝置）。 |
| metricENC | 設定為非零，表示支援 [編輯後繼續]。 注意： 自定義偵錯引擎不應該設定這個，或應該一律將它設定為 0。 |
| metricExceptions | 設定為非零，表示對例外狀況的支援。 |
| metricFunctionBP | 設定為非零，表示對具名斷點的支援（呼叫特定函式名稱時會中斷的斷點）。 |
| metricHitCountBP | 設定為非零，表示支援設定「命中點」斷點（只有在達到特定次數之後才會觸發的斷點）。 |
| metricJITDebug | 設定為非零，表示對 Just-In-Time 偵錯的支援（調試程式會在執行中的進程中發生例外狀況時啟動）。 |
| metricMemory | 未使用 |
| metricPortSupplier | 如果實作埠供應商的CLSID，請將此值設定為CLSID。 |
| metricRegisters | 未使用 |
| metricSetNextStatement | 設定為非零，表示支援設定下一個語句（略過中繼語句的執行）。 |
| metricSuspendThread | 設定為非零，表示支援暫停線程執行。 |
| metricWarnIfNoSymbols | 設定為非零，表示如果沒有符號，則應該通知使用者。 |
| metricProgramProvider | 將此設定為程式提供者的 CLSID。 |
| metricAlwaysLoadProgramProviderLocal | 將此設定為非零，表示程式提供者應該一律在本機載入。 |
| metricEngineCanWatchProcess | 將此設定為非零值，表示偵錯引擎會監看進程事件，而不是程式提供者。 |
| metricRemoteDebugging | 將此設定為非零，表示支援遠端偵錯。 |
| metricEncUseNativeBuilder | 將此設定為非零，表示編輯後繼續管理員應該使用偵錯引擎的 encbuild.dll 來建置 Edit 和 Continue。 注意： 自定義偵錯引擎不應該設定這個，或應該一律將它設定為 0。 |
| metricLoadUnderWOW64 | 將此設定為非零值，表示偵錯引擎應該在偵錯 64 位進程時，於 WOW 下的偵錯程式中載入;否則，偵錯引擎將會載入Visual Studio進程（在WOW64下執行）。 |
| metricLoadProgramProviderUnderWOW64 | 將此設定為非零，表示偵錯 64 位進程在 WOW 下偵錯 64 位進程時，應該載入程式提供者;否則，它會在 Visual Studio 程式中載入。 |
| metricStopOnExceptionCrossingManagedBoundary | 將此設定為非零值，表示如果跨 Managed/Unmanaged 程式代碼界限擲回未處理的例外狀況，進程應該停止。 |
| metricAutoSelectPriority | 將此設定為自動選取偵錯引擎的優先順序（較高的值等於較高優先順序）。 |
| metricAutoSelectIncompatibleList | 登錄機碼，其中包含指定偵錯引擎在自動選取範圍中要忽略之 GUID 的專案。 這些專案是一個以字串表示的 GUID 的數位（0、1、2 等等）。 |
| metricIncompatibleList | 登錄機碼，其中包含針對與這個偵錯引擎不相容之偵錯引擎指定 GUID 的專案。 |
| metricDisableJITOptimization | 將此設定為非零，表示偵錯期間應該停用 Just-In-Time 優化（適用於 Managed 程式代碼）。 |
| 表達式評估工具屬性 | 描述 |
|---|---|
| metricEngine | 這會保存支援指定表示式評估工具的偵錯引擎數目。 |
| metricPreloadModules | 將此設定為非零值，表示當表達式評估工具針對程序啟動時，應該預先載入模組。 |
| metricThisObjectName | 將此設定為 「this」 物件名稱。 |
| 表達式評估工具延伸模組屬性 | 描述 |
|---|---|
| metricExtensionDll | 支援此延伸模組的 dll 名稱。 |
| metricExtensionRegistersSupported | 支援的快取器清單。 |
| metricExtensionRegistersEntryPoint | 存取快取器的進入點。 |
| metricExtensionTypesSupported | 支援的類型清單。 |
| metricExtensionTypesEntryPoint | 存取類型的進入點。 |
| 埠供應商屬性 | 描述 |
|---|---|
| metricPortPickerCLSID | 埠選擇器 CLSID （使用者可以用來選取埠的對話框，並新增要用於偵錯的埠）。 |
| metricDisallowUserEnteredPorts | 如果無法將使用者輸入的埠新增至埠供應商，則為非零（這會使埠選擇器對話框基本上是唯讀的）。 |
| metricPidBase | 配置進程標識碼時，埠供應商所使用的基底進程標識碼。 |
| 預先定義的SP存放區類型 | 描述 |
|---|---|
| storetypeFile | 符號會儲存在個別的檔案中。 |
| storetypeMetadata | 符號會儲存為元件中的元數據。 |
| 其他屬性 | 描述 |
|---|---|
| metricShowNonUserCode | 將此設定為非零，以顯示非用戶程序代碼。 |
| metricJustMyCodeStepping | 將此設定為非零，表示只能在用戶程式代碼中執行逐步執行。 |
| metricCLSID | 特定計量類型的物件 CLSID。 |
| metricName | 特定計量類型的物件的使用者易記名稱。 |
| metricLanguage | 語言名稱。 |
登錄位置
計量會讀取並寫入登錄，特別是在子機碼中 VisualStudio 。
注意
大部分時候，計量都會寫入HKEY_LOCAL_MACHINE密鑰。 不過，有時HKEY_CURRENT_USER會是目的地密鑰。 Dbgmetric.lib 會處理這兩個索引鍵。 取得計量時，它會先搜尋HKEY_CURRENT_USER，然後HKEY_LOCAL_MACHINE。 設定計量時，參數會指定要使用的最上層索引鍵。
[登錄機碼]\
Software\
Microsoft\
VisualStudio\
[版本根目錄]\
[計量根目錄]\
[計量類型]\
[metric] = [metric value]
[metric] = [metric value]
[metric] = [metric value]
| 預留位置 | 描述 |
|---|---|
| [登錄機碼] | HKEY_CURRENT_USER 或 HKEY_LOCAL_MACHINE。 |
| [版本根目錄] | Visual Studio 的版本（例如 、7.07.1、 或 8.0）。 不過，您也可以使用 /rootuffix 參數來修改此根目錄，以 devenv.exe。 對於 VSIP，此修飾詞通常是 Exp，因此版本根目錄會是 8.0Exp。 |
| [計量根目錄] | 這是 AD7Metrics 或 AD7Metrics(Debug)，視是否使用 dbgmetric.lib 的偵錯版本而定。 注意： 如果使用 dbgmetric.lib，如果偵錯和發行版本之間的差異必須反映在登錄中，則應該遵守此命名慣例。 |
| [計量類型] | 要寫入的計量類型： Engine、、 ExpressionEvaluator、 SymbolProvider等。這些全都定義為 dbgmetric.h 中的 metricTypeXXXX，其中 XXXX 是特定的類型名稱。 |
| [metric] | 要指派值的項目名稱，以便設定計量。 計量的實際組織取決於計量類型。 |
| [計量值] | 指派給計量的值。 值應該具有的類型（字串、數位等）取決於計量。 |
注意
所有 GUID 都會以 的格式 {GUID}儲存。 例如： {123D150B-FA18-461C-B218-45B3E4589F9B} 。
偵錯引擎
以下是登錄中偵錯引擎計量的組織。 Engine 是偵錯引擎的計量類型名稱，且對應至 上述登錄子樹中的 [計量類型 ]。
Engine\
[引擎 guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
[metric] = [metric value]
PortSupplier\
0 = [埠供應商 guid]
1 = [埠供應商 guid]
| 預留位置 | 描述 |
|---|---|
| [引擎 guid] | 偵錯引擎的 GUID。 |
| [class guid] | 實作這個偵錯引擎之 類別的 GUID。 |
| [埠供應商 guid] | 如果有的話，埠供應商的 GUID。 許多偵錯引擎都會使用預設埠供應商，因此不會指定自己的供應商。 在此情況下，子機碼 PortSupplier 將會不存在。 |
連接埠提供者
以下是登錄中埠供應商計量的組織。 PortSupplier是埠供應商的計量類型名稱，對應至 [計量類型]。
PortSupplier\
[埠供應商 guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
| 預留位置 | 描述 |
|---|---|
| [埠供應商 guid] | 埠供應商的 GUID |
| [class guid] | 實作此埠供應商之 類別的 GUID |
符號提供者
以下是登錄中符號供應商計量的組織。 SymbolProvider是符號提供者的計量類型名稱，且對應至 [計量類型]。
SymbolProvider\
[符號提供者 guid]\
file\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
metadata\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
| 預留位置 | 描述 |
|---|---|
| [符號提供者 guid] | 符號提供者的 GUID |
| [class guid] | 實作此符號提供者之 類別的 GUID |
表達式評估工具
以下是登錄中表達式評估工具計量的組織。 ExpressionEvaluator是表達式評估工具的計量類型名稱，且對應至 [計量類型]。
注意
的計量類型 ExpressionEvaluator 未定義於 dbgmetric.h 中，因為假設表達式評估工具的所有計量變更都會經過適當的表達式評估工具計量函式（子機碼的配置 ExpressionEvaluator 有點複雜，因此詳細數據會隱藏在 dbgmetric.lib 內）。
ExpressionEvaluator\
[語言 guid]\
[廠商 guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
Engine\
0 = [debug engine guid]
1 = [debug engine guid]
| 預留位置 | 描述 |
|---|---|
| [語言 guid] | 語言的 GUID |
| [廠商 guid] | 廠商的 GUID |
| [class guid] | 實作此表達式評估工具之類別的 GUID |
| [debug engine guid] | 這個表達式評估工具可搭配使用的偵錯引擎 GUID |
表達式評估工具延伸模組
以下是登錄中表達式評估工具擴充計量的組織。 EEExtensions是表達式評估工具延伸模組的計量類型名稱，對應至 [計量類型]。
EEExtensions\
[擴充功能 guid]\
[metric] = [metric value]
[metric] = [metric value]
| 預留位置 | 描述 |
|---|---|
| [擴充功能 guid] | 表達式評估工具延伸模組的 GUID |
例外狀況
以下是登錄中例外狀況計量的組織。 Exception是例外狀況的計量類型名稱，且對應至 [計量類型]。
Exception\
[debug engine guid]\
[例外狀況類型]\
[exception]\
[metric] = [metric value]
[metric] = [metric value]
[exception]\
[metric] = [metric value]
[metric] = [metric value]
| 預留位置 | 描述 |
|---|---|
| [debug engine guid] | 支援例外狀況之偵錯引擎的 GUID。 |
| [例外狀況類型] | 子機碼的一般標題，識別可以處理的例外狀況類別。 一般名稱包括 C++ 例外狀況、Win32 例外狀況、Common Language Runtime 例外狀況和原生運行時間檢查。 這些名稱也可用來識別使用者的特定例外狀況類別。 |
| [exception] | 例外狀況的名稱：例如，_com_error或 Control-Break。 這些名稱也可用來識別使用者的特定例外狀況。 |
需求
這些檔案位於 Microsoft Visual Studio 2010 SDK 安裝目錄（預設為 [磁碟驅動器]\Program Files\Microsoft Visual Studio 2010 SDK\）。
標頭：includes\dbgmetric.h
連結庫：libs\ad2de.lib、libs\dbgmetric.lib