用于调试的 SDK 帮助程序
这些函数和声明是用于在 C++ 中实现调试引擎、表达式计算器和符号提供程序的全局帮助程序函数。
注意
目前没有这些函数和声明的托管版本。
为了使 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]如果指标特定于用户，并且是否应将其写入用户的 hive 而不是本地计算机配置单元，则为 TRUE。 |
| 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设置为使用默认值。 |
表达式计算器函数
| 函数 | 说明 |
|---|---|
| Get企业版Metric | 从注册表中检索指标值。 |
| Set企业版Metric | 在注册表中设置指定的指标值。 |
| Remove企业版Metric | 从注册表中删除指定的指标。 |
| GetEEMetricFile | 从指定的指标中获取文件名并加载它，以字符串的形式返回文件内容。 |
异常函数
| 函数 | 说明 |
|---|---|
| GetExceptionMetric | 从注册表中检索指标值。 |
| SetExceptionMetric | 在注册表中设置指定的指标值。 |
| RemoveExceptionMetric | 从注册表中删除指定的指标。 |
| RemoveAllExceptionMetrics | 从注册表中删除所有异常指标。 |
符号提供程序函数
| 函数 | 说明 |
|---|---|
| GetSPMetric | 从注册表中检索指标值。 |
| SetSPMetric | 在注册表中设置指定的指标值。 |
| RemoveSPMetric | 从注册表中删除指定的指标。 |
枚举函数
| 函数 | 说明 |
|---|---|
| EnumMetricSections | 枚举指定指标类型的所有指标。 |
| EnumDebugEngine | 枚举已注册的调试引擎。 |
| EnumEEs | 枚举已注册的表达式计算器。 |
| EnumExceptionMetrics | 枚举所有异常指标。 |
指标定义
这些定义可用于预定义的指标名称。 这些名称对应于各种注册表项和值名称，并且都定义为宽字符字符串：例如 extern LPCWSTR metrictypeEngine。
| 预定义指标类型 | 说明：...的基键... |
|---|---|
| metrictypeEngine | 所有调试引擎指标。 |
| metrictypePortSupplier | 所有端口供应商指标。 |
| metrictypeException | 所有异常指标。 |
| metricttype企业版Extension | 所有表达式计算器扩展。 |
| 调试引擎属性 | 说明 |
|---|---|
| metricAddressBP | 设置为非零，指示对地址断点的支持。 |
| metricAlwaysLoadLocal | 设置为非零，以便始终在本地加载调试引擎。 |
| metricLoadInDebuggeeSession | 未使用 |
| metricLoadedByDebuggee | 设置为非零，指示将始终加载调试引擎，或者由正在调试的程序加载。 |
| metricAttach | 设置为非零，指示对现有程序的附件的支持。 |
| metricCallStackBP | 设置为非零，指示对调用堆栈断点的支持。 |
| metricConditionalBP | 设置为非零，指示对条件断点设置的支持。 |
| metricDataBP | 设置为非零，以指示对数据更改设置断点的支持。 |
| metricDisassembly | 设置为非零，指示对反汇编列表的生产支持。 |
| metricDumpWriting | 设置为非零，指示对转储写入的支持（将内存转储到输出设备）。 |
| metricENC | 设置为非零，指示对“编辑并继续”的支持。 注意： 自定义调试引擎不应设置此引擎或应始终将其设置为 0。 |
| metricExceptions | 设置为非零，指示对异常的支持。 |
| metricFunctionBP | 设置为非零，指示对命名断点的支持（调用特定函数名称时中断的断点）。 |
| metricHitCountBP | 设置为非零，以指示对“命中点”断点设置的支持（仅在达到特定次数后触发的断点）。 |
| metricJITDebug | 设置为非零，以指示对实时调试的支持（在正在运行的进程中发生异常时启动调试器）。 |
| metricMemory | 未使用 |
| metricPortSupplier | 如果已实现端口供应商的 CLSID，请将它设置为 CLSID。 |
| metricRegisters | 未使用 |
| metricSetNextStatement | 设置为非零，指示支持设置下一个语句（跳过中间语句的执行）。 |
| metricSuspendThread | 设置为非零，指示对暂停线程执行的支持。 |
| metricWarnIfNoSymbols | 设置为非零，以指示在没有符号的情况下应通知用户。 |
| metricProgramProvider | 将此设置为程序提供程序的 CLSID。 |
| metricAlwaysLoadProgramProviderLocal | 将此设置为非零，以指示应始终在本地加载程序提供程序。 |
| metricEngineCanWatchProcess | 将此设置为非零值，以指示调试引擎将监视进程事件而不是程序提供程序。 |
| metricRemoteDebugging | 将此设置为非零，以指示对远程调试的支持。 |
| metricEncUseNativeBuilder | 将此设置为非零值，以指示“编辑并继续”管理器应使用调试引擎的 encbuild.dll 生成编辑并继续。 注意： 自定义调试引擎不应设置此引擎或应始终将其设置为 0。 |
| metricLoadUnderWOW64 | 将此设置为非零，以指示调试引擎应在调试 64 位进程时在 WOW 下的调试对象进程中加载;否则，调试引擎将加载到 Visual Studio 进程中（在 WOW64 下运行）。 |
| metricLoadProgramProviderUnderWOW64 | 将此设置为非零，以指示在 WOW 下调试 64 位进程时，应在调试对象进程中加载程序提供程序;否则，它将在 Visual Studio 进程中加载。 |
| metricStopOnExceptionCrossingManagedBoundary | 将此设置为非零值，以指示如果跨托管/非托管代码边界引发未经处理的异常，进程应停止。 |
| metricAutoSelectPriority | 将此设置为自动选择调试引擎的优先级（较高的值等于更高的优先级）。 |
| metricAutoSelectIncompatibleList | 包含指定在自动选择中忽略调试引擎的 GUID 的条目的注册表项。 这些条目是一个数字（0、1、2 等），其 GUID 表示为字符串。 |
| metricIncompatibleList | 包含为与此调试引擎不兼容的调试引擎指定 GUID 的条目的注册表项。 |
| metricDisableJITOptimization | 将此设置为非零，以指示在调试期间应禁用实时优化（对于托管代码）。 |
| 表达式计算器属性 | 说明 |
|---|---|
| metricEngine | 这包含支持指定表达式计算器的调试引擎数。 |
| metricPreloadModules | 将此设置为非零值，以指示在针对程序启动表达式计算器时应预加载模块。 |
| metricThisObjectName | 将其设置为“this”对象名称。 |
| 表达式计算器扩展属性 | 说明 |
|---|---|
| metricExtensionDll | 支持此扩展的 dll 的名称。 |
| metricExtensionRegistersSupported | 支持的寄存器列表。 |
| metricExtensionRegistersEntryPoint | 用于访问寄存器的入口点。 |
| metricExtensionTypesSupported | 支持的类型列表。 |
| metricExtensionTypesEntryPoint | 用于访问类型的入口点。 |
| 端口供应商属性 | 说明 |
|---|---|
| metricPortPickerCLSID | 端口选取器 CLSID（用户可用于选择端口并添加用于调试的端口）的对话框。 |
| metricDisallowUserEnteredPorts | 如果无法将用户输入的端口添加到端口供应商，则为非零（这会使端口选取器对话框实质上为只读）。 |
| metricPidBase | 分配进程 ID 时，端口供应商使用的基本进程 ID。 |
| 预定义的 SP 存储类型 | 说明 |
|---|---|
| storetypeFile | 符号存储在单独的文件中。 |
| storetypeMetadata | 符号作为元数据存储在程序集中。 |
| 杂项属性 | 说明 |
|---|---|
| metricShowNonUserCode | 将此设置为非零，以显示非用户代码。 |
| metricJustMyCodeStepping | 将此设置为非零，以指示单步执行只能在用户代码中发生。 |
| metricCLSID | 特定指标类型的对象的 CLSID。 |
| metricName | 特定指标类型的对象的用户友好名称。 |
| metricLanguage | 语言名称。 |
注册表位置
指标是从注册表中读取和写入的，特别是在子项中 VisualStudio 。
注意
大多数情况下，指标将写入HKEY_LOCAL_MACHINE密钥。 但是，有时HKEY_CURRENT_U标准版R 将是目标密钥。 Dbgmetric.lib 处理这两个键。 获取指标时，它会先搜索 HKEY_CURRENT_U标准版R，然后HKEY_LOCAL_MACHINE。 设置指标时，参数指定要使用的顶级键。
[注册表项]\
Software\
Microsoft\
VisualStudio\
[版本根]\
[指标根]\
[指标类型]\
[metric] = [metric value]
[metric] = [metric value]
[metric] = [metric value]
| 占位符 | 说明 |
|---|---|
| [注册表项] | HKEY_CURRENT_USER 或 HKEY_LOCAL_MACHINE。 |
| [版本根] | Visual Studio 的版本（例如，7.0或7.18.0）。 但是，也可以使用 /rootuffix 开关将此根修改为 devenv.exe。 对于 VSIP，此修饰符通常是 Exp，因此版本根目录为 8.0Exp。 |
| [指标根] | 这取决于AD7MetricsAD7Metrics(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 是表达式计算器的指标类型名称，对应于 [指标类型]。
注意
dbgmetric.h 中未定义指标类型 ExpressionEvaluator ，因为假定表达式计算器的所有指标更改都将经过适当的表达式计算器指标函数（子项的 ExpressionEvaluator 布局有点复杂，因此详细信息隐藏在 dbgmetric.lib 中）。
ExpressionEvaluator\
[语言 guid]\
[供应商 guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
Engine\
0 = [调试引擎 guid]
1 = [调试引擎 guid]
| 占位符 | 说明 |
|---|---|
| [语言 guid] | 语言的 GUID |
| [供应商 guid] | 供应商的 GUID |
| [class guid] | 实现此表达式计算器的类的 GUID |
| [调试引擎 guid] | 此表达式计算器使用的调试引擎的 GUID |
表达式计算器扩展
下面是注册表中表达式计算器扩展指标的组织。 EEExtensions 是表达式计算器扩展的指标类型名称，对应于 [指标类型]。
EEExtensions\
[扩展 guid]\
[metric] = [metric value]
[metric] = [metric value]
| 占位符 | 说明 |
|---|---|
| [扩展 guid] | 表达式计算器扩展的 GUID |
异常
下面是注册表中的异常指标的组织。 Exception 是异常的指标类型名称，对应于 [指标类型]。
Exception\
[调试引擎 guid]\
[异常类型]\
[异常]\
[metric] = [metric value]
[metric] = [metric value]
[异常]\
[metric] = [metric value]
[metric] = [metric value]
| 占位符 | 说明 |
|---|---|
| [调试引擎 guid] | 支持异常的调试引擎的 GUID。 |
| [异常类型] | 标识可以处理的异常类的子项的常规标题。 典型名称包括 C++ 异常、 Win32 异常、 公共语言运行时异常和 本机运行时检查。 这些名称还用于标识用户的特定异常类。 |
| [异常] | 异常的名称：例如，_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