Вспомогательные пакеты 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 или массив графических идентификаторов. |
| fUserSpecific | [in] Значение TRUE, если метрика относится к пользователю, и если она должна быть записана в 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] Максимальное количество идентификаторов GUID, которые могут храниться в массиве rgguidSections . |
| pszAltRoot | [in] Альтернативный корневой каталог реестра для использования. Установите для NULL использования значения по умолчанию. |
Функции вычислителя выражений
| Function | Description |
|---|---|
| GetEEMetric | Извлекает значение метрик из реестра. |
| SetEEMetric | Задает указанное значение метрик в реестре. |
| RemoveEEMetric | Удаляет указанную метрику из реестра. |
| GetEEMetricFile | Возвращает имя файла из указанной метрики и загружает его, возвращая содержимое файла в виде строки. |
Функции исключений
| Function | Description |
|---|---|
| GetExceptionMetric | Извлекает значение метрик из реестра. |
| SetExceptionMetric | Задает указанное значение метрик в реестре. |
| RemoveExceptionMetric | Удаляет указанную метрику из реестра. |
| RemoveAllExceptionMetrics | Удаляет все метрики исключений из реестра. |
Функции поставщика символов
| Function | Description |
|---|---|
| GetSPMetric | Извлекает значение метрик из реестра. |
| SetSPMetric | Задает указанное значение метрик в реестре. |
| RemoveSPMetric | Удаляет указанную метрику из реестра. |
Функции перечисления
| Function | Description |
|---|---|
| Перечисление Метрик | Перечисляет все метрики для указанного типа метрик. |
| EnumDebugEngine | Перечисляет зарегистрированные подсистемы отладки. |
| EnumEEs | Перечисляет зарегистрированные вычислители выражений. |
| EnumExceptionMetrics | Перечисляет все метрики исключений. |
Определения метрик
Эти определения можно использовать для предопределенных имен метрик. Имена соответствуют различным разделам реестра и именам значений и определяются как широкие символьные строки: например. extern LPCWSTR metrictypeEngine
| Предопределенные типы метрик | Описание: базовый ключ для.... |
|---|---|
| metrictypeEngine | Все метрики подсистемы отладки. |
| metrictypePortSupplier | Все метрики поставщика портов. |
| metrictypeException | Все метрики исключений. |
| metricttypeEEExtension | Все расширения вычислителя выражений. |
| Свойства обработчика отладки | Description |
|---|---|
| metricAddressBP | Задайте значение nonzero, чтобы указать поддержку точек останова адресов. |
| metricAlwaysLoadLocal | Установите значение nonzero, чтобы всегда загружать подсистему отладки локально. |
| metricLoadInDebuggeeSession | НЕ ИСПОЛЬЗУЕТСЯ |
| metricLoadedByDebuggee | Установите значение nonzero, чтобы указать, что подсистема отладки всегда будет загружена или отлаживаемая программой. |
| metricAttach | Установите значение nonzero, чтобы указать поддержку вложений к существующим программам. |
| metricCallStackBP | Задайте значение nonzero, чтобы указать поддержку точек останова стека вызовов. |
| metricConditionalBP | Установите значение nonzero, чтобы указать поддержку параметра условных точек останова. |
| metricDataBP | Установите значение nonzero, чтобы указать поддержку параметров точек останова на изменениях данных. |
| metricDisassembly | Задайте значение nonzero, чтобы указать поддержку производства списка дизассембли. |
| metricDumpWriting | Задайте значение nonzero, чтобы указать поддержку записи дампа (дамп памяти на выходное устройство). |
| метрика | Установите значение nonzero, чтобы указать поддержку правки и продолжения. Примечание. Пользовательский модуль отладки никогда не должен задавать это значение или всегда должен иметь значение 0. |
| metricExceptions | Задайте значение nonzero, чтобы указать поддержку исключений. |
| metricFunctionBP | Установите значение nonzero, чтобы указать поддержку именованных точек останова (точек останова, которые прерываются при вызове определенного имени функции). |
| metricHitCountBP | Установите значение nonzero, чтобы указать поддержку параметров точек останова "точка попадания" (точек останова, которые активируются только после нажатия определенного количества раз). |
| metricJITDebug | Установите значение nonzero, чтобы указать поддержку JIT-отладки (отладчик запускается при возникновении исключения в запущенном процессе). |
| metricMemory | НЕ ИСПОЛЬЗУЕТСЯ |
| metricPortSupplier | Задайте для параметра CLSID поставщика портов, если он реализован. |
| metricRegisters | НЕ ИСПОЛЬЗУЕТСЯ |
| metricSetNextStatement | Установите значение nonzero, чтобы указать поддержку установки следующей инструкции (которая пропускает выполнение промежуточных инструкций). |
| metricSuspendThread | Установите значение nonzero, чтобы указать поддержку приостановки выполнения потока. |
| metricWarnIfNoSymbols | Установите значение nonzero, чтобы указать, что пользователь должен получать уведомления, если символов нет. |
| metricProgramProvider | Задайте для параметра CLSID поставщика программы. |
| metricAlwaysLoadProgramProviderLocal | Задайте для этого значение ненулевого значения, чтобы указать, что поставщик программы всегда должен быть загружен локально. |
| metricEngineCanWatchProcess | Задайте для этого значение ненулевого значения, чтобы указать, что подсистема отладки будет отслеживать события процесса вместо поставщика программы. |
| metricRemoteDebugging | Задайте для этого значение ненулевого значения, чтобы указать поддержку удаленной отладки. |
| metricEncUseNativeBuilder | Задайте для этого значение ненулевого значения, чтобы указать, что диспетчер редактирования и продолжения должен использовать encbuild.dll подсистемы отладки для сборки для редактирования и продолжения. Примечание. Пользовательский модуль отладки никогда не должен задавать это значение или всегда должен иметь значение 0. |
| metricLoadUnderWOW64 | Задайте для этого значение ненулевого значения, чтобы указать, что подсистема отладки должна быть загружена в процессе отладки в WOW при отладке 64-разрядного процесса; в противном случае подсистема отладки будет загружена в процессе Visual Studio (который выполняется в WOW64). |
| metricLoadProgramProviderUnderWOW64 | Задайте для этого значение ненулевого значения, чтобы указать, что поставщик программы должен быть загружен в процесс отладчика при отладке 64-разрядного процесса в WOW; в противном случае она будет загружена в процессе Visual Studio. |
| metricStopOnExceptionCrossingManagedBoundary | Задайте для этого значение ненулевого значения, чтобы указать, что процесс должен остановиться, если необработанное исключение возникает через границы управляемого или неуправляемого кода. |
| metricAutoSelectPriority | Задайте для этого приоритет для автоматического выбора обработчика отладки (более высокие значения равны более высокому приоритету). |
| metricAutoSelectIncompatibleList | Раздел реестра, содержащий записи, указывающие идентификаторы GUID для обработчиков отладки, которые будут игнорироваться при автоматическом выборе. Эти записи являются числом (0, 1, 2 и т. д.) с GUID, выраженным как строка. |
| metricIncompatibleList | Раздел реестра, содержащий записи, указывающие идентификаторы GUID для обработчиков отладки, несовместимых с этим модулем отладки. |
| metricDisableJITOptimization | Задайте для этого значение ненулевого значения, чтобы указать, что во время отладки необходимо отключить оптимизацию jit (для управляемого кода). |
| Свойства вычислителя выражений | Description |
|---|---|
| metricEngine | Это содержит количество обработчиков отладки, поддерживающих указанный средство оценки выражений. |
| metricPreloadModules | Задайте для этого значение ненулевого значения, чтобы указать, что модули должны быть предварительно загружены при запуске вычислителя выражений в программе. |
| metricThisObjectName | Задайте для этого имя объекта "this". |
| Свойства расширения вычислителя выражений | Description |
|---|---|
| metricExtensionDll | Имя библиотеки DLL, поддерживающей это расширение. |
| metricExtensionRegistersSupported | Список поддерживаемых регистров. |
| metricExtensionRegistersEntryPoint | Точка входа для доступа к регистрам. |
| metricExtensionTypesSupported | Список поддерживаемых типов. |
| metricExtensionTypesEntryPoint | Точка входа для типов доступа. |
| Свойства поставщика портов | Description |
|---|---|
| metricPortPickerCLSID | CLSID средства выбора портов (диалоговое окно пользователь может использовать для выбора портов и добавления портов для отладки). |
| metricDisallowUserEnteredPorts | Ненулевое значение, если введенные пользователем порты не могут быть добавлены в поставщик портов (это делает диалоговое окно выбора портов по сути доступно только для чтения). |
| metricPidBase | Базовый идентификатор процесса, используемый поставщиком портов при выделении идентификаторов процессов. |
| Предопределенные типы хранилища SP | Description |
|---|---|
| storetypeFile | Символы хранятся в отдельном файле. |
| storetypeMetadata | Символы хранятся в виде метаданных в сборке. |
| Прочие свойства | Description |
|---|---|
| metricShowNonUserCode | Задайте для этого значение ненулевого кода, чтобы отобразить неиспользуемый код. |
| metricJustMyCodeStepping | Задайте для этого значение ненулевого значения, чтобы указать, что пошаговое выполнение может происходить только в пользовательском коде. |
| metricCLSID | CLSID для объекта определенного типа метрик. |
| metricName | Понятное имя объекта определенного типа метрик. |
| metricLanguage | Имя языка. |
Расположения реестра
Метрики считываются и записываются в реестр, в частности в подразделе VisualStudio .
Примечание.
В большинстве случаев метрики записываются в ключ HKEY_LOCAL_MACHINE. Однако иногда HKEY_CURRENT_USER будет ключом назначения. Dbgmetric.lib обрабатывает оба ключа. При получении метрики сначала выполняется поиск HKEY_CURRENT_USER, а затем HKEY_LOCAL_MACHINE. При настройке метрики параметр указывает, какой ключ верхнего уровня следует использовать.
[раздел реестра]\
Software\
Microsoft\
VisualStudio\
[корень версии]\
[корневой каталог метрик]\
[тип метрики]\
[метрика] = [значение метрики]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
| Заполнитель | Description |
|---|---|
| [раздел реестра] | HKEY_CURRENT_USER или HKEY_LOCAL_MACHINE. |
| [корень версии] | Версия Visual Studio (например, или 7.07.18.0). Однако этот корневой каталог также можно изменить с помощью переключателя /rootuffix на devenv.exe. Для VSIP этот модификатор обычно является Exp, поэтому корень версии будет, например, 8.0Exp. |
| [корневой каталог метрик] | Это или AD7MetricsAD7Metrics(Debug), в зависимости от того, используется ли отладочная версия dbgmetric.lib. Примечание. Используется ли dbgmetric.lib, это соглашение об именовании должно соответствовать, если у вас есть различия между версиями отладки и выпуска, которые должны отражаться в реестре. |
| [тип метрики] | Тип метрики для записи: Engine, ExpressionEvaluator, SymbolProviderи т. д. Это все определяется как в dbgmetric.h as metricTypeXXXX, где XXXX указано имя конкретного типа. |
| [метрика] | Имя записи, назначаемой значением, чтобы задать метрику. Фактическая организация метрик зависит от типа метрик. |
| [значение метрики] | Значение, назначенное метрику. Тип значения должен иметь (строка, число и т. д.) зависит от метрики. |
Примечание.
Все идентификаторы GUID хранятся в формате {GUID}. Например, {123D150B-FA18-461C-B218-45B3E4589F9B}.
Обработчики отладки
Ниже приведена организация метрик обработчиков отладки в реестре. Engine — имя типа метрик для подсистемы отладки и соответствует [типу метрик] в приведенном выше поддереве реестра.
Engine\
[guid обработчика]\
CLSID = [guid класса]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
PortSupplier\
0 = [guid поставщика портов]
1 = [guid поставщика портов]
| Заполнитель | Description |
|---|---|
| [guid обработчика] | GUID обработчика отладки. |
| [guid класса] | GUID класса, реализующего этот модуль отладки. |
| [guid поставщика портов] | GUID поставщика портов, если таковой есть. Многие обработчики отладки используют поставщика портов по умолчанию и поэтому не указывают собственного поставщика. В этом случае подраздел PortSupplier будет отсутствует. |
Поставщики портов
Ниже приведена организация метрик поставщика портов в реестре. PortSupplier — имя типа метрики для поставщика портов и соответствует [типу метрик].
PortSupplier\
[guid поставщика портов]\
CLSID = [guid класса]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
| Заполнитель | Description |
|---|---|
| [guid поставщика портов] | GUID поставщика портов |
| [guid класса] | GUID класса, реализующего этот поставщик портов |
Поставщики символов
Ниже приведена организация метрик поставщика символов в реестре. SymbolProvider — имя типа метрик для поставщика символов и соответствует [типу метрик].
SymbolProvider\
[guid поставщика символов]\
file\
CLSID = [guid класса]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
metadata\
CLSID = [guid класса]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
| Заполнитель | Description |
|---|---|
| [guid поставщика символов] | GUID поставщика символов |
| [guid класса] | GUID класса, реализующего этот поставщик символов |
Вычислители выражений
Ниже приведена организация метрик вычислителя выражений в реестре. ExpressionEvaluator — имя типа метрик для вычислителя выражений и соответствует [типу метрики].
Примечание.
Тип метрик для ExpressionEvaluator не определен в dbgmetric.h, так как предполагается, что все изменения метрик для вычислителей выражений будут проходить через соответствующие функции метрики вычислителя выражений (макет ExpressionEvaluator подраздела несколько сложный, поэтому детали скрыты внутри dbgmetric.lib).
ExpressionEvaluator\
[guid языка]\
[guid поставщика]\
CLSID = [guid класса]
[метрика] = [значение метрики]
[метрика] = [значение метрики]
Engine\
0 = [guid модуля отладки]
1 = [guid модуля отладки]
| Заполнитель | Description |
|---|---|
| [guid языка] | GUID языка |
| [guid поставщика] | GUID поставщика |
| [guid класса] | GUID класса, реализующего этот средство оценки выражений |
| [guid модуля отладки] | GUID обработчика отладки, с которым работает средство оценки выражений. |
Расширения вычислителя выражений
Ниже приведена организация метрик расширения средства оценки выражений в реестре. EEExtensions — это имя типа метрик для расширений вычислителя выражений и соответствует [типу метрик].
EEExtensions\
[guid расширения]\
[метрика] = [значение метрики]
[метрика] = [значение метрики]
| Заполнитель | Description |
|---|---|
| [guid расширения] | GUID расширения вычислителя выражений |
Исключения
Ниже приведена организация метрик исключений в реестре. Exception — имя типа метрик для исключений и соответствует [типу метрик].
Exception\
[guid модуля отладки]\
[типы исключений]\
[исключение]\
[метрика] = [значение метрики]
[метрика] = [значение метрики]
[исключение]\
[метрика] = [значение метрики]
[метрика] = [значение метрики]
| Заполнитель | Description |
|---|---|
| [guid модуля отладки] | GUID обработчика отладки, поддерживающего исключения. |
| [типы исключений] | Общее название подраздела, определяющее класс исключений, которые можно обрабатывать. Типичными именами являются исключения C++, исключения Win32, исключения среды CLR и собственные проверки времени выполнения. Эти имена также используются для идентификации определенного класса исключения для пользователя. |
| [исключение] | Имя исключения: например, _com_error или Control-Break. Эти имена также используются для идентификации определенного исключения для пользователя. |
Requirements
Эти файлы находятся в каталоге установки пакета SDK Microsoft Visual Studio 2010 (по умолчанию [диск]\Program Files\Microsoft Visual Studio 2010 SDK\).
Заголовок: include\dbgmetric.h
Библиотека: libs\ad2de.lib, libs\dbgmetric.lib