Asistentes de SDK para la depuración
Estas funciones y declaraciones son funciones auxiliares globales para implementar motores de depuración, evaluadores de expresiones y proveedores de símbolos en C++.
Nota:
No hay versiones administradas de estas funciones y declaraciones en este momento.
Para que Visual Studio use motores de depuración, evaluadores de expresiones y proveedores de símbolos, deben registrarse. Esto se hace estableciendo subclaves del Registro y entradas, lo que se conoce como "establecer métricas". Las siguientes funciones globales están diseñadas para facilitar el proceso de actualización de estas métricas. Consulte la sección ubicaciones del Registro para averiguar el diseño de cada subclave del Registro que actualiza estas funciones.
Funciones generales de métricas
Estas son funciones generales que usan los motores de depuración. Las funciones especializadas para evaluadores de expresiones y proveedores de símbolos se detallan más adelante.
GetMetric (método)
Recupera un valor de métrica del Registro.
HRESULT GetMetric(
LPCWSTR pszMachine,
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
DWORD * pdwValue,
LPCWSTR pszAltRoot
);
| Parámetro | Descripción |
|---|---|
| pszMachine | [in] Nombre de una máquina posiblemente remota cuyo registro se escribirá (NULL significa máquina local). |
| pszType | [in] Uno de los tipos de métricas. |
| guidSection | [in] GUID de un motor específico, evaluador, excepción, etc. Especifica una subsección bajo un tipo de métrica para un elemento específico. |
| pszMetric | [in] Métrica que se va a obtener. Esto corresponde a un nombre de valor específico. |
| pdwValue | [in] Ubicación de almacenamiento del valor de la métrica. Hay varios tipos de GetMetric que pueden devolver un DWORD (como en este ejemplo), un BSTR, un GUID o una matriz de GUID. |
| pszAltRoot | [in] Una raíz del Registro alternativa que se va a usar. Establézcalo en NULL para usar el valor predeterminado. |
SetMetric (método)
Establece el valor de métrica especificado en el Registro.
HRESULT SetMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
const DWORD dwValue,
bool fUserSpecific,
LPCWSTR pszAltRoot
);
| Parámetro | Descripción |
|---|---|
| pszType | [in] Uno de los tipos de métricas. |
| guidSection | [in] GUID de un motor específico, evaluador, excepción, etc. Especifica una subsección bajo un tipo de métrica para un elemento específico. |
| pszMetric | [in] Métrica que se va a obtener. Esto corresponde a un nombre de valor específico. |
| dwValue | [in] Ubicación de almacenamiento del valor en la métrica. Hay varios tipos de SetMetric que pueden almacenar un DWORD (en este ejemplo), un BSTR, un GUID o una matriz de GUID. |
| fUserSpecific | [in] TRUE si la métrica es específica del usuario y si se debe escribir en el subárbol del usuario en lugar del subárbol del equipo local. |
| pszAltRoot | [in] Una raíz del Registro alternativa que se va a usar. Establézcalo en NULL para usar el valor predeterminado. |
RemoveMetric (método)
Quita la métrica especificada del Registro.
HRESULT RemoveMetric(
LPCWSTR pszType,
REFGUID guidSection,
LPCWSTR pszMetric,
LPCWSTR pszAltRoot
);
| Parámetro | Descripción |
|---|---|
| pszType | [in] Uno de los tipos de métricas. |
| guidSection | [in] GUID de un motor específico, evaluador, excepción, etc. Especifica una subsección bajo un tipo de métrica para un elemento específico. |
| pszMetric | [in] Métrica que se va a quitar. Esto corresponde a un nombre de valor específico. |
| pszAltRoot | [in] Una raíz del Registro alternativa que se va a usar. Establézcalo en NULL para usar el valor predeterminado. |
EnumMetricSections (método)
Enumera las distintas secciones de métricas del Registro.
HRESULT EnumMetricSections(
LPCWSTR pszMachine,
LPCWSTR pszType,
GUID * rgguidSections,
DWORD * pdwSize,
LPCWSTR pszAltRoot
);
| Parámetro | Descripción |
|---|---|
| pszMachine | [in] Nombre de una máquina posiblemente remota cuyo registro se escribirá (NULL significa máquina local). |
| pszType | [in] Uno de los tipos de métricas. |
| rgguidSections | [dentro, fuera] Matriz preasignada de GUID que se van a rellenar. |
| pdwSize | [in] Número máximo de GUID que se pueden almacenar en la rgguidSections matriz. |
| pszAltRoot | [in] Una raíz del Registro alternativa que se va a usar. Establézcalo en NULL para usar el valor predeterminado. |
Funciones del evaluador de expresiones
| Función | Descripción |
|---|---|
| GetEEMetric | Recupera un valor de métrica del Registro. |
| SetEEMetric | Establece el valor de métrica especificado en el Registro. |
| RemoveEEMetric | Quita la métrica especificada del Registro. |
| GetEEMetricFile | Obtiene un nombre de archivo de la métrica especificada y lo carga, devolviendo el contenido del archivo como una cadena. |
Funciones de excepción
| Función | Descripción |
|---|---|
| GetExceptionMetric | Recupera un valor de métrica del Registro. |
| SetExceptionMetric | Establece el valor de métrica especificado en el Registro. |
| RemoveExceptionMetric | Quita la métrica especificada del Registro. |
| RemoveAllExceptionMetrics | Quita todas las métricas de excepción del Registro. |
Funciones del proveedor de símbolos
| Función | Descripción |
|---|---|
| GetSPMetric | Recupera un valor de métrica del Registro. |
| SetSPMetric | Establece el valor de métrica especificado en el Registro. |
| RemoveSPMetric | Quita la métrica especificada del Registro. |
Funciones de enumeración
| Función | Descripción |
|---|---|
| EnumMetricSections | Enumera todas las métricas de un tipo de métrica especificado. |
| EnumDebugEngine | Enumera los motores de depuración registrados. |
| EnumEEs | Enumera los evaluadores de expresiones registradas. |
| EnumExceptionMetrics | Enumera todas las métricas de excepción. |
Definiciones de métricas
Estas definiciones se pueden usar para nombres de métrica predefinidos. Los nombres corresponden a varias claves del Registro y nombres de valor y se definen como cadenas de caracteres anchos: por ejemplo, extern LPCWSTR metrictypeEngine.
| Tipos de métricas predefinidos | Descripción: la clave base para...... |
|---|---|
| metrictypeEngine | Todas las métricas del motor de depuración. |
| metrictypePortSupplier | Todas las métricas del proveedor de puertos. |
| metrictypeException | Todas las métricas de excepción. |
| metricttypeEEExtension | Todas las extensiones del evaluador de expresiones. |
| Propiedades del motor de depuración | Descripción |
|---|---|
| metricAddressBP | Establézcalo en distinto de cero para indicar la compatibilidad con los puntos de interrupción de dirección. |
| metricAlwaysLoadLocal | Establézcalo en distinto de cero para cargar siempre el motor de depuración localmente. |
| metricLoadInDebuggeeSession | NO SE UTILIZA |
| metricLoadedByDebuggee | Establézcalo en distinto de cero para indicar que el motor de depuración siempre se cargará con o con el programa que se está depurando. |
| metricAttach | Establézcalo en distinto de cero para indicar la compatibilidad con los datos adjuntos a los programas existentes. |
| métricaCallStackBP | Establézcalo en distinto de cero para indicar la compatibilidad con los puntos de interrupción de la pila de llamadas. |
| metricConditionalBP | Establézcalo en distinto de cero para indicar la compatibilidad con la configuración de puntos de interrupción condicionales. |
| metricDataBP | Establézcalo en distinto de cero para indicar la compatibilidad con la configuración de puntos de interrupción en los cambios en los datos. |
| metricDisassembly | Establézcalo en distinto de cero para indicar la compatibilidad con la producción de una lista de desensamblaje. |
| metricDumpWriting | Establézcalo en distinto de cero para indicar la compatibilidad con la escritura de volcados de memoria (el volcado de memoria en un dispositivo de salida). |
| metricENC | Establézcalo en distinto de cero para indicar la compatibilidad con Editar y continuar. Nota: Un motor de depuración personalizado nunca debe establecerlo o siempre debe establecerlo en 0. |
| metricExceptions | Establézcalo en distinto de cero para indicar la compatibilidad con excepciones. |
| metricFunctionBP | Establezca en distinto de cero para indicar la compatibilidad con puntos de interrupción con nombre (puntos de interrupción que se interrumpen cuando se llama a un nombre de función determinado). |
| metricHitCountBP | Establézcalo en distinto de cero para indicar la compatibilidad con el valor de puntos de interrupción de "punto de acierto" (puntos de interrupción que se desencadenan solo después de alcanzar un número determinado de veces). |
| metricJITDebug | Establézcalo en distinto de cero para indicar la compatibilidad con la depuración Just-In-Time (el depurador se inicia cuando se produce una excepción en un proceso en ejecución). |
| metricMemory | NO SE UTILIZA |
| metricPortSupplier | Establézcalo en el CLSID del proveedor de puertos si se implementa uno. |
| metricRegisters | NO SE UTILIZA |
| metricSetNextStatement | Establézcalo en distinto de cero para indicar la compatibilidad para establecer la siguiente instrucción (que omite la ejecución de instrucciones intermedias). |
| metricSuspendThread | Establézcalo en distinto de cero para indicar la compatibilidad con la suspensión de la ejecución del subproceso. |
| metricWarnIfNoSymbols | Establézcalo en distinto de cero para indicar que se debe notificar al usuario si no hay símbolos. |
| metricProgramProvider | Establézcalo en el CLSID del proveedor del programa. |
| metricAlwaysLoadProgramProviderLocal | Establézcalo en distinto de cero para indicar que el proveedor del programa siempre debe cargarse localmente. |
| metricEngineCanWatchProcess | Establézcalo en distinto de cero para indicar que el motor de depuración observará los eventos de proceso en lugar del proveedor del programa. |
| metricRemoteDebugging | Establézcalo en distinto de cero para indicar la compatibilidad con la depuración remota. |
| metricEncUseNativeBuilder | Establézcalo en distinto de cero para indicar que el Administrador de edición y continuación debe usar el archivo encbuild.dll del motor de depuración para compilar para Editar y continuar. Nota: Un motor de depuración personalizado nunca debe establecerlo o siempre debe establecerlo en 0. |
| metricLoadUnderWOW64 | Establézcalo en distinto de cero para indicar que el motor de depuración debe cargarse en el proceso depurado en WOW al depurar un proceso de 64 bits; De lo contrario, el motor de depuración se cargará en el proceso de Visual Studio (que se ejecuta en WOW64). |
| métricaLoadProgramProviderUnderWOW64 | Establézcalo en distinto de cero para indicar que el proveedor de programas debe cargarse en el proceso depurado al depurar un proceso de 64 bits en WOW; De lo contrario, se cargará en el proceso de Visual Studio. |
| métricaStopOnExceptionCrossingManagedBoundary | Establézcalo en distinto de cero para indicar que el proceso debe detenerse si se produce una excepción no controlada en los límites de código administrados o no administrados. |
| metricAutoSelectPriority | Establézcalo en una prioridad para la selección automática del motor de depuración (los valores más altos son iguales a mayor prioridad). |
| metricAutoSelectIncompatibleList | Clave del Registro que contiene entradas que especifican GUID para los motores de depuración que se omitirán en la selección automática. Estas entradas son un número (0, 1, 2, etc.) con un GUID expresado como una cadena. |
| metricIncompatibleList | Clave del Registro que contiene entradas que especifican GUID para motores de depuración que no son compatibles con este motor de depuración. |
| metricDisableJITOptimization | Establézcalo en distinto de cero para indicar que las optimizaciones Just-In-Time (para código administrado) deben deshabilitarse durante la depuración. |
| Propiedades del evaluador de expresiones | Descripción |
|---|---|
| metricEngine | Contiene el número de motores de depuración que admiten el evaluador de expresiones especificado. |
| metricPreloadModules | Establézcalo en distinto de cero para indicar que los módulos deben cargarse previamente cuando se inicia un evaluador de expresiones en un programa. |
| metricThisObjectName | Establézcalo en el nombre del objeto "this". |
| Propiedades de extensión del evaluador de expresiones | Descripción |
|---|---|
| metricExtensionDll | Nombre del archivo DLL que admite esta extensión. |
| metricExtensionRegistersSupported | Lista de registros admitidos. |
| metricExtensionRegistersEntryPoint | Punto de entrada para acceder a los registros. |
| metricExtensionTypesSupported | Lista de tipos admitidos. |
| metricExtensionTypesEntryPoint | Punto de entrada para acceder a los tipos. |
| Propiedades del proveedor de puertos | Descripción |
|---|---|
| metricPortPickerCLSID | CLSID del selector de puertos (un cuadro de diálogo que el usuario puede usar para seleccionar puertos y agregar puertos que se usarán para la depuración). |
| metricDisallowUserEnteredPorts | Distinto de cero si los puertos introducidos por el usuario no se pueden agregar al proveedor de puertos (esto hace que el cuadro de diálogo selector de puertos esencialmente sea de solo lectura). |
| metricPidBase | Identificador de proceso base utilizado por el proveedor de puertos al asignar identificadores de proceso. |
| Tipos de almacén de SP predefinidos | Descripción |
|---|---|
| storetypeFile | Los símbolos se almacenan en un archivo independiente. |
| storetypeMetadata | Los símbolos se almacenan como metadatos en un ensamblado. |
| Propiedades varias | Descripción |
|---|---|
| metricShowNonUserCode | Establézcalo en distinto de cero para mostrar código que no sea de usuario. |
| métricaJustMyCodeStepping | Establézcalo en distinto de cero para indicar que la ejecución paso a paso solo puede producirse en el código de usuario. |
| metricCLSID | CLSID para un objeto de un tipo de métrica específico. |
| metricName | Nombre descriptivo para un objeto de un tipo de métrica específico. |
| metricLanguage | Nombre del idioma. |
Ubicaciones del Registro
Las métricas se leen y escriben en el Registro, específicamente en la VisualStudio subclave.
Nota:
La mayoría de las veces, las métricas se escribirán en la clave de HKEY_LOCAL_MACHINE. Sin embargo, a veces HKEY_CURRENT_USER será la clave de destino. Dbgmetric.lib controla ambas claves. Al obtener una métrica, busca primero HKEY_CURRENT_USER y, a continuación, HKEY_LOCAL_MACHINE. Cuando se establece una métrica, un parámetro especifica qué clave de nivel superior se va a usar.
[clave del Registro]\
Software\
Microsoft\
VisualStudio\
[raíz de versión]\
[raíz de métrica]\
[tipo de métrica]\
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
| Marcador de posición | Descripción |
|---|---|
| [clave del Registro] | HKEY_CURRENT_USER o HKEY_LOCAL_MACHINE. |
| [raíz de versión] | La versión de Visual Studio (por ejemplo, 7.0, 7.1o 8.0). Sin embargo, esta raíz también se puede modificar mediante el modificador /rootuffix a devenv.exe. Para VSIP, este modificador suele ser Exp, por lo que la raíz de la versión sería, por ejemplo, 8.0Exp. |
| [raíz de métrica] | Esto es AD7Metrics o AD7Metrics(Debug), en función de si se usa la versión de depuración de dbgmetric.lib. Nota: Si se usa o no dbgmetric.lib, esta convención de nomenclatura debe cumplirse si tiene diferencias entre las versiones de depuración y versión que se deben reflejar en el registro. |
| [tipo de métrica] | Tipo de métrica que se va a escribir: Engine, ExpressionEvaluator, SymbolProvider, etc. Todos se definen como en dbgmetric.h como metricTypeXXXX, donde XXXX es el nombre de tipo específico. |
| [métrica] | Nombre de una entrada a la que se va a asignar un valor para establecer la métrica. La organización real de las métricas depende del tipo de métrica. |
| [valor de métrica] | Valor asignado a la métrica. El tipo que debe tener el valor (cadena, número, etc.) depende de la métrica. |
Nota:
Todos los GUID se almacenan en el formato de {GUID}. Por ejemplo, {123D150B-FA18-461C-B218-45B3E4589F9B}.
Motores de depuración
A continuación se muestra la organización de las métricas de los motores de depuración en el registro. Engine es el nombre de tipo de métrica de un motor de depuración y corresponde a [tipo de métrica] en el subárbol del Registro anterior.
Engine\
[guid del motor]\
CLSID = [guid de clase]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
PortSupplier\
0 = [guid del proveedor de puertos]
1 = [guid del proveedor de puertos]
| Marcador de posición | Descripción |
|---|---|
| [guid del motor] | GUID del motor de depuración. |
| [guid de clase] | GUID de la clase que implementa este motor de depuración. |
| [guid del proveedor de puertos] | GUID del proveedor de puertos, si existe. Muchos motores de depuración usan el proveedor de puertos predeterminado y, por lo tanto, no especifican su propio proveedor. En este caso, la subclave PortSupplier estará ausente. |
Proveedores de puertos
A continuación se muestra la organización de las métricas del proveedor de puertos en el Registro. PortSupplier es el nombre del tipo de métrica para un proveedor de puertos y corresponde a [tipo de métrica].
PortSupplier\
[guid del proveedor de puertos]\
CLSID = [guid de clase]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
| Marcador de posición | Descripción |
|---|---|
| [guid del proveedor de puertos] | GUID del proveedor de puertos |
| [guid de clase] | GUID de la clase que implementa este proveedor de puertos |
Proveedores de símbolos
A continuación se muestra la organización de las métricas del proveedor de símbolos en el Registro. SymbolProvider es el nombre de tipo de métrica para el proveedor de símbolos y corresponde a [tipo de métrica].
SymbolProvider\
[guid del proveedor de símbolos]\
file\
CLSID = [guid de clase]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
metadata\
CLSID = [guid de clase]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
| Marcador de posición | Descripción |
|---|---|
| [guid del proveedor de símbolos] | GUID del proveedor de símbolos |
| [guid de clase] | GUID de la clase que implementa este proveedor de símbolos |
Evaluadores de expresiones
A continuación se muestra la organización de las métricas del evaluador de expresiones en el Registro. ExpressionEvaluator es el nombre del tipo de métrica para el evaluador de expresiones y corresponde a [tipo de métrica].
Nota:
El tipo de métrica para ExpressionEvaluator no se define en dbgmetric.h, ya que se supone que todos los cambios de métrica para evaluadores de expresiones pasarán por las funciones de métricas del evaluador de expresiones adecuadas (el diseño de la ExpressionEvaluator subclave es algo complicado, por lo que los detalles se ocultan dentro de dbgmetric.lib).
ExpressionEvaluator\
[guid de idioma]\
[guid del proveedor]\
CLSID = [guid de clase]
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
Engine\
0 = [guid del motor de depuración]
1 = [guid del motor de depuración]
| Marcador de posición | Descripción |
|---|---|
| [guid de idioma] | GUID de un idioma |
| [guid del proveedor] | Guid de un proveedor |
| [guid de clase] | GUID de la clase que implementa este evaluador de expresiones |
| [guid del motor de depuración] | Guid de un motor de depuración con el que funciona este evaluador de expresiones |
Extensiones del evaluador de expresiones
A continuación se muestra la organización de las métricas de extensión del evaluador de expresiones en el Registro. EEExtensions es el nombre de tipo de métrica para las extensiones del evaluador de expresiones y corresponde a [tipo de métrica].
EEExtensions\
[guid de extensión]\
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
| Marcador de posición | Descripción |
|---|---|
| [guid de extensión] | GUID de una extensión del evaluador de expresiones |
Excepciones
A continuación se muestra la organización de las métricas de excepciones en el Registro. Exception es el nombre de tipo de métrica para las excepciones y corresponde a [tipo de métrica].
Exception\
[guid del motor de depuración]\
[tipos de excepción]\
[excepción]\
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
[excepción]\
[métrica] = [valor de métrica]
[métrica] = [valor de métrica]
| Marcador de posición | Descripción |
|---|---|
| [guid del motor de depuración] | GUID de un motor de depuración que admite excepciones. |
| [tipos de excepción] | Título general de la subclave que identifica la clase de excepciones que se puede controlar. Los nombres típicos son excepciones de C++, excepciones de Win32, excepciones de Common Language Runtime y comprobaciones en tiempo de ejecución nativas. Estos nombres también se usan para identificar una clase determinada de excepción al usuario. |
| [excepción] | Un nombre para una excepción: por ejemplo, _com_error o Control-Break. Estos nombres también se usan para identificar una excepción determinada al usuario. |
Requisitos
Estos archivos se encuentran en el directorio de instalación del SDK de Microsoft Visual Studio 2010 (de forma predeterminada, [unidad]\Archivos de programa\Microsoft Visual Studio 2010 SDK\).
Encabezado: includes\dbgmetric.h
Biblioteca: libs\ad2de.lib, libs\dbgmetric.lib