SDK Helpers for Debugging
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
These functions and declarations are global helper functions for implementing debug engines, expression evaluators, and symbol providers in C++.
Note
There are no managed versions of these functions and declarations at this time.
Overview
In order for debug engines, expression evaluators, and symbol providers to be used by Visual Studio, they must be registered. This is done by setting registry subkeys and entries, otherwise known as "setting metrics." The following global functions are designed to ease the process of updating these metrics. See the section on Registry Locations to find out the layout of each registry subkey that is updated by these functions.
General Metric Functions
These are general functions used by debug engines. Specialized functions for expression evaluators and symbol providers are detailed later.
GetMetric Method
Retrieves a metric value from the registry.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parameter | Description |
|---|---|
| pszMachine | [in] Name of a possibly remote machine whose register will be written (NULL means local machine). |
| pszType | [in] One of the metric types. |
| guidSection | [in] GUID of a specific engine, evaluator, exception, etc. This specifies a subsection under a metric type for a specific element. |
| pszMetric | [in] The metric to be obtained. This corresponds to a specific value name. |
| pdwValue | [in] The storage location of the value from the metric. There are several flavors of GetMetric that can return a DWORD (as in this example), a BSTR, a GUID, or an array of GUIDs. |
| pszAltRoot | [in] An alternate registry root to use. Set to NULL to use the default. |
SetMetric Method
Sets the specified metric value in the registry.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parameter | Description |
|---|---|
| pszType | [in] One of the metric types. |
| guidSection | [in] GUID of a specific engine, evaluator, exception, etc. This specifies a subsection under a metric type for a specific element. |
| pszMetric | [in] The metric to be obtained. This corresponds to a specific value name. |
| dwValue | [in] The storage location of the value in the metric. There are several flavors of SetMetric that can store a DWORD (in this example), a BSTR, a GUID, or an array of GUIDs. |
| fUserSpecific | [in] TRUE if the metric is user-specific and if it should be written to the user's hive instead of the local machine hive. |
| pszAltRoot | [in] An alternate registry root to use. Set to NULL to use the default. |
RemoveMetric Method
Removes the specified metric from the registry.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parameter | Description |
|---|---|
| pszType | [in] One of the metric types. |
| guidSection | [in] GUID of a specific engine, evaluator, exception, etc. This specifies a subsection under a metric type for a specific element. |
| pszMetric | [in] The metric to be removed. This corresponds to a specific value name. |
| pszAltRoot | [in] An alternate registry root to use. Set to NULL to use the default. |
EnumMetricSections Method
Enumerates the various metric sections in the registry.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parameter | Description |
|---|---|
| pszMachine | [in] Name of a possibly remote machine whose register will be written (NULL means local machine). |
| pszType | [in] One of the metric types. |
| rgguidSections | [in, out] Preallocated array of GUIDs to be filled in. |
| pdwSize | [in] The maximum number of GUIDs that can be stored in the rgguidSections array. |
| pszAltRoot | [in] An alternate registry root to use. Set to NULL to use the default. |
Expression Evaluator Functions
| Function | Description |
|---|---|
| GetEEMetric | Retrieves a metric value from the registry. |
| SetEEMetric | Sets the specified metric value in the registry. |
| RemoveEEMetric | Removes the specified metric from the registry. |
| GetEEMetricFile | Gets a file name from the specified metric and loads it, returning the file contents as a string. |
Exception Functions
| Function | Description |
|---|---|
| GetExceptionMetric | Retrieves a metric value from the registry. |
| SetExceptionMetric | Sets the specified metric value in the registry. |
| RemoveExceptionMetric | Removes the specified metric from the registry. |
| RemoveAllExceptionMetrics | Removes all exception metrics from the registry. |
Symbol Provider Functions
| Function | Description |
|---|---|
| GetSPMetric | Retrieves a metric value from the registry. |
| SetSPMetric | Sets the specified metric value in the registry. |
| RemoveSPMetric | Removes the specified metric from the registry. |
Enumeration Functions
| Function | Description |
|---|---|
| EnumMetricSections | Enumerates all metrics for a specified metric type. |
| EnumDebugEngine | Enumerates the registered debug engines. |
| EnumEEs | Enumerates the registered expression evaluators. |
| EnumExceptionMetrics | Enumerates all exception metrics. |
Metric Definitions
These definitions can be used for predefined metric names. The names correspond to various registry keys and value names and are all defined as wide character strings: for example, extern LPCWSTR metrictypeEngine.
| Predefined Metric Types | Description: The base key for.... |
|---|---|
| metrictypeEngine | All debug engine metrics. |
| metrictypePortSupplier | All port supplier metrics. |
| metrictypeException | All exception metrics. |
| metricttypeEEExtension | All expression evaluator extensions. |
| Debug Engine Properties | Description |
|---|---|
| metricAddressBP | Set to nonzero to indicate support for address breakpoints. |
| metricAlwaysLoadLocal | Set to nonzero in order to always load the debug engine locally. |
| metricLoadInDebuggeeSession | NOT USED |
| metricLoadedByDebuggee | Set to nonzero to indicate that the debug engine will always be loaded with or by the program being debugged. |
| metricAttach | Set to nonzero to indicate support for attachment to existing programs. |
| metricCallStackBP | Set to nonzero to indicate support for call stack breakpoints. |
| metricConditionalBP | Set to nonzero to indicate support for the setting of conditional breakpoints. |
| metricDataBP | Set to nonzero to indicate support for the setting of breakpoints on changes in data. |
| metricDisassembly | Set to nonzero to indicate support for the production of a disassembly listing. |
| metricDumpWriting | Set to nonzero to indicate support for dump writing (the dumping of memory to an output device). |
| metricENC | Set to nonzero to indicate support for Edit and Continue. Note: A custom debug engine should never set this or should always set it to 0. |
| metricExceptions | Set to nonzero to indicate support for exceptions. |
| metricFunctionBP | Set to nonzero to indicate support for named breakpoints (breakpoints that break when a certain function name is called). |
| metricHitCountBP | Set to nonzero to indicate support for the setting of "hit point" breakpoints (breakpoints that are triggered only after being hit a certain number of times). |
| metricJITDebug | Set to nonzero to indicate support for just-in-time debugging (the debugger is launched when an exception occurs in a running process). |
| metricMemory | NOT USED |
| metricPortSupplier | Set this to the CLSID of the port supplier if one is implemented. |
| metricRegisters | NOT USED |
| metricSetNextStatement | Set to nonzero to indicate support for setting the next statement (which skips execution of intermediate statements). |
| metricSuspendThread | Set to nonzero to indicate support for suspending thread execution. |
| metricWarnIfNoSymbols | Set to nonzero to indicate that the user should be notified if there are no symbols. |
| metricProgramProvider | Set this to the CLSID of the program provider. |
| metricAlwaysLoadProgramProviderLocal | Set this to nonzero to indicate that the program provider should always be loaded locally. |
| metricEngineCanWatchProcess | Set this to nonzero to indicate that the debug engine will watch for process events instead of the program provider. |
| metricRemoteDebugging | Set this to nonzero to indicate support for remote debugging. |
| metricEncUseNativeBuilder | Set this to nonzero to indicate that the Edit and Continue Manager should use the debug engine's encbuild.dll to build for Edit and Continue. Note: A custom debug engine should never set this or should always set it to 0. |
| metricLoadUnderWOW64 | Set this to nonzero to indicate that the debug engine should be loaded in the debuggee process under WOW when debugging a 64-bit process; otherwise, the debug engine will be loaded in the Visual Studio process (which is running under WOW64). |
| metricLoadProgramProviderUnderWOW64 | Set this to nonzero to indicate that the program provider should be loaded in the debuggee process when debugging a 64-bit process under WOW; otherwise, it will be loaded in the Visual Studio process. |
| metricStopOnExceptionCrossingManagedBoundary | Set this to nonzero to indicate that the process should stop if an unhandled exception is thrown across managed/unmanaged code boundaries. |
| metricAutoSelectPriority | Set this to a priority for automatic selection of the debug engine (higher values equals higher priority). |
| metricAutoSelectIncompatibleList | Registry key containing entries that specify GUIDs for debug engines to be ignored in automatic selection. These entries are a number (0, 1, 2, and so on) with a GUID expressed as a string. |
| metricIncompatibleList | Registry key containing entries that specify GUIDs for debug engines that are incompatible with this debug engine. |
| metricDisableJITOptimization | Set this to nonzero to indicate that just-in-time optimizations (for managed code) should be disabled during debugging. |
| Expression Evaluator Properties | Description |
|---|---|
| metricEngine | This holds the number of debug engines that support the specified expression evaluator. |
| metricPreloadModules | Set this to nonzero to indicate that modules should be preloaded when an expression evaluator is launched against a program. |
| metricThisObjectName | Set this to the "this" object name. |
| Expression Evaluator Extension Properties | Description |
|---|---|
| metricExtensionDll | Name of the dll that supports this extension. |
| metricExtensionRegistersSupported | List of registers supported. |
| metricExtensionRegistersEntryPoint | Entry point for accessing registers. |
| metricExtensionTypesSupported | List of types supported. |
| metricExtensionTypesEntryPoint | Entry point for accessing types. |
| Port Supplier Properties | Description |
|---|---|
| metricPortPickerCLSID | The CLSID of the port picker (a dialog box the user can use to select ports and add ports to use for debugging). |
| metricDisallowUserEnteredPorts | Nonzero if the user-entered ports cannot be added to the port supplier (this makes the port-picker dialog box essentially read-only). |
| metricPidBase | The base process ID used by the port supplier when allocating process IDs. |
| Predefined SP Store Types | Description |
|---|---|
| storetypeFile | The symbols are stored in a separate file. |
| storetypeMetadata | The symbols are stored as metadata in an assembly. |
| Miscellaneous Properties | Description |
|---|---|
| metricShowNonUserCode | Set this to nonzero to show nonuser code. |
| metricJustMyCodeStepping | Set this to nonzero to indicate that stepping can occur only in user code. |
| metricCLSID | CLSID for an object of a specific metric type. |
| metricName | User-friendly name for an object of a specific metric type. |
| metricLanguage | Language name. |
Registry Locations
The metrics are read from and written to the registry, specifically in the VisualStudio subkey.
Note
Most of the time, the metrics will be written to the HKEY_LOCAL_MACHINE key. However, sometimes HKEY_CURRENT_USER will be the destination key. Dbgmetric.lib handles both keys. When getting a metric, it searches HKEY_CURRENT_USER first, then HKEY_LOCAL_MACHINE. When it is setting a metric, a parameter specifies which top-level key to use.
[registry key]\
Software\
Microsoft\
VisualStudio\
[version root]\
[metric root]\
[metric type]\
[metric] = [metric value]
[metric] = [metric value]
[metric] = [metric value]
| Placeholder | Description |
|---|---|
| [registry key] | HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE. |
| [version root] | The version of Visual Studio (for example, 7.0, 7.1, or 8.0). However, this root can also be modified using the /rootsuffix switch to devenv.exe. For VSIP, this modifier is typically Exp, so the version root would be, for example, 8.0Exp. |
| [metric root] | This is either AD7Metrics or AD7Metrics(Debug), depending on whether the debug version of dbgmetric.lib is used. Note: Whether or not dbgmetric.lib is used, this naming convention should be adhered to if you have differences between debug and release versions that must be reflected in the registry. |
| [metric type] | The type of metric to be written: Engine, ExpressionEvaluator, SymbolProvider, etc. These are all defined as in dbgmetric.h as metricTypeXXXX, where XXXX is the specific type name. |
| [metric] | The name of an entry to be assigned a value in order to set the metric. The actual organization of the metrics depends on the metric type. |
| [metric value] | The value assigned to the metric. The type the value should have (string, number, etc.) depends on the metric. |
Note
All GUIDs are stored in the format of {GUID}. For example, {123D150B-FA18-461C-B218-45B3E4589F9B}.
Debug Engines
The following is the organization of the debug engines metrics in the registry. Engine is the metric type name for a debug engine and corresponds to [metric type] in the above registry subtree.
Engine\
[engine guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
[metric] = [metric value]
PortSupplier\
0 = [port supplier guid]
1 = [port supplier guid]
| Placeholder | Description |
|---|---|
| [engine guid] | The GUID of the debug engine. |
| [class guid] | The GUID of the class that implements this debug engine. |
| [port supplier guid] | The GUID of the port supplier, if any. Many debug engines use the default port supplier and therefore do not specify their own supplier. In this case, the subkey PortSupplier will be absent. |
Port Suppliers
The following is the organization of the port supplier metrics in the registry. PortSupplier is the metric type name for a port supplier and corresponds to [metric type].
PortSupplier\
[port supplier guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
| Placeholder | Description |
|---|---|
| [port supplier guid] | The GUID of the port supplier |
| [class guid] | The GUID of the class that implements this port supplier |
Symbol Providers
The following is the organization of the symbol supplier metrics in the registry. SymbolProvider is the metric type name for the symbol provider and corresponds to [metric type].
SymbolProvider\
[symbol provider guid]\
file\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
metadata\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
| Placeholder | Description |
|---|---|
| [symbol provider guid] | The GUID of the symbol provider |
| [class guid] | The GUID of the class that implements this symbol provider |
Expression Evaluators
The following is the organization of the expression evaluator metrics in the registry. ExpressionEvaluator is the metric type name for the expression evaluator and corresponds to [metric type].
Note
The metric type for ExpressionEvaluator is not defined in dbgmetric.h, as it is assumed that all metric changes for expression evaluators will go through the appropriate expression evaluator metric functions (the layout of the ExpressionEvaluator subkey is somewhat complicated, so the details are hidden inside dbgmetric.lib).
ExpressionEvaluator\
[language guid]\
[vendor guid]\
CLSID = [class guid]
[metric] = [metric value]
[metric] = [metric value]
Engine\
0 = [debug engine guid]
1 = [debug engine guid]
| Placeholder | Description |
|---|---|
| [language guid] | The GUID of a language |
| [vendor guid] | The GUID of a vendor |
| [class guid] | The GUID of the class that implements this expression evaluator |
| [debug engine guid] | The GUID of a debug engine that this expression evaluator works with |
Expression Evaluator Extensions
The following is the organization of the expression evaluator extension metrics in the registry. EEExtensions is the metric type name for the expression evaluator extensions and corresponds to [metric type].
EEExtensions\
[extension guid]\
[metric] = [metric value]
[metric] = [metric value]
| Placeholder | Description |
|---|---|
| [extension guid] | The GUID of an expression evaluator extension |
Exceptions
The following is the organization of the exceptions metrics in the registry. Exception is the metric type name for the exceptions and corresponds to [metric type].
Exception\
[debug engine guid]\
[exception types]\
[exception]\
[metric] = [metric value]
[metric] = [metric value]
[exception]\
[metric] = [metric value]
[metric] = [metric value]
| Placeholder | Description |
|---|---|
| [debug engine guid] | The GUID of a debug engine that supports exceptions. |
| [exception types] | A general title for the subkey identifying the class of exceptions that can be handled. Typical names are C++ Exceptions, Win32 Exceptions, Common Language Runtime Exceptions, and Native Run-Time Checks. These names are also used to identify a particular class of exception to the user. |
| [exception] | A name for an exception: for example, _com_error or Control-Break. These names are also used to identify a particular exception to the user. |
Requirements
These files are located in the Microsoft Visual Studio 2010 SDK installation directory (by default, [drive]\Program Files\Microsoft Visual Studio 2010 SDK\).
Header: includes\dbgmetric.h
Library: libs\ad2de.lib, libs\dbgmetric.lib