Macros de depuración e informe de errores
Estas macros proporcionan funciones útiles de depuración y seguimiento.
| Nombre | Descripción |
|---|---|
| _ATL_DEBUG_INTERFACES | Escribe, en la ventana de salida, las pérdidas de interfaz que se detectan cuando se llama a _Module.Term. |
| _ATL_DEBUG_QI | Escribe todas las llamadas en QueryInterface a la ventana de salida. |
| ATLASSERT | Realiza la misma funcionalidad que la macro _ASSERTE que se puede encontrar en la biblioteca en tiempo de ejecución de C. |
| ATLENSURE | Realiza la validación de parámetros. Llame a AtlThrow si es necesario |
| ATLTRACENOTIMPL | Envía un mensaje al dispositivo de volcado de memoria de que la función especificada no está implementada. |
| ATLTRACE | Notifica advertencias a un dispositivo de salida, como la ventana del depurador, según las marcas y los niveles indicados. La compatibilidad con versiones anteriores está incluida. |
| ATLTRACE2 | Notifica advertencias a un dispositivo de salida, como la ventana del depurador, según las marcas y los niveles indicados. |
_ATL_DEBUG_INTERFACES
Defina esta macro antes de incluir cualquier archivo de encabezado ATL para hacer el seguimiento de todas las llamadas AddRef y Release en las interfaces de los componentes a la ventana de salida.
#define _ATL_DEBUG_INTERFACES
Comentarios
La salida de seguimiento aparecerá como se muestra a continuación:
ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug
La primera parte de cada seguimiento siempre será ATL: QIThunk. A continuación, hay un valor que identifica la interfaz en código thunk específica que se está usando. Una interfaz en código thunk es un objeto que se usa para mantener un recuento de referencias y ofrecer la capacidad de seguimiento usada aquí. Se crea una nueva interfaz en código thunk en cada llamada QueryInterface excepto para las solicitudes de la interfaz IUnknown (en este caso, se devuelve el mismo código thunk cada vez para cumplir con las reglas de identidad de COM).
A continuación, verá AddRef o Release que indica qué método se ha llamado. Después, verá un valor que identifica el objeto al que se le ha cambiado la cuenta de referencias de la interfaz. El valor de seguimiento es el puntero del objeto this.
El recuento de referencias que se realiza en un seguimiento es el recuento de referencias de ese código thunk después de que se llamara a AddRef o Release. Tenga en cuenta que este recuento de referencias puede no coincidir con el del objeto. Cada código thunk mantiene su propio recuento de referencias para ayudarle a cumplir plenamente con las reglas de recuento de referencias de COM.
El último fragmento de información rastreado es el nombre del objeto y la interfaz afectada por la llamada AddRef o Release.
Las pérdidas de interfaz que se detectan cuando el servidor se apaga y se llama a _Module.Term se registrarán así:
ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug
La información proporcionada aquí se asigna directamente a la información proporcionada en las instrucciones de seguimiento anteriores, por lo que puede examinar los recuentos de referencia durante toda la duración de una interfaz en código thunk. Además, obtendrá una indicación del recuento máximo de referencias en esa interfaz thunk.
Nota:
Se puede usar _ATL_DEBUG_INTERFACES en versiones comerciales.
_ATL_DEBUG_QI
Escribe todas las llamadas en QueryInterface a la ventana de salida.
#define _ATL_DEBUG_QI
Comentarios
Si se produce un error en una llamada a QueryInterface, la ventana de salida mostrará:
nombre de interfaz - failed
ATLASSERT
La macro ATLASSERT realiza la misma funcionalidad que la macro _ASSERTE que está en la biblioteca en tiempo de ejecución de C.
ATLASSERT(booleanExpression);
Parámetros
booleanExpression
Expresión (incluidos los punteros) que se evalúa como distinto de cero o 0.
Comentarios
En las compilaciones de depuración, ATLASSERT evalúa booleanExpression y genera un informe de depuración cuando el resultado es false.
Requisitos
Encabezado: atldef.h
ATLENSURE
Esta macro se usa para validar los parámetros pasados a una función.
ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);
Parámetros
booleanExpression
Especifica una expresión booleana que se va a probar.
Hr
Especifica un código de error que a devolver.
Comentarios
Estas macros proporcionan un mecanismo para detectar y notificar al usuario el uso incorrecto de los parámetros.
La macro llama a ATLASSERT y si se produce un error en la condición llama a AtlThrow.
En el caso de ATLENSURE, se llama a AtlThrow con E_FAIL.
En el caso de ATLENSURE_THROW, se llama aAtlThrow con el VALOR HRESULT especificado.
La diferencia entre ATLENSURE y ATLASSERT es que ATLENSURE lanza una excepción tanto en las compilaciones de versión como en las de depuración.
Ejemplo
void MyImportantFunction(char* psz)
{
ATLENSURE(NULL != psz);
char mysz[64];
strcpy_s(mysz, sizeof(mysz), psz);
}
Requisitos
Encabezado: afx.h
ATLTRACENOTIMPL
En las compilaciones de depuración de ATL, envía la cadena " funcname no está implementada" al dispositivo de volcado de memoria y devuelve E_NOTIMPL.
ATLTRACENOTIMPL(funcname);
Parámetros
funcname
[in] Cadena que contiene el nombre de la función que no está implementada.
Comentarios
En las compilaciones de versión, simplemente devuelve E_NOTIMPL.
Ejemplo
ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));
Requisitos
Encabezado: atltrace.h
ATLTRACE
Notifica advertencias a un dispositivo de salida, como la ventana del depurador, según las marcas y los niveles indicados. La compatibilidad con versiones anteriores está incluida.
ATLTRACE(exp);
ATLTRACE(
DWORD category,
UINT level,
LPCSTR lpszFormat, ...);
Parámetros
exp
[in] La cadena y las variables que se van a enviar a la ventana de salida o a cualquier aplicación que intercepte estos mensajes.
category
[in] Tipo de evento o método sobre el que se informa. Vea la lista de categorías en los Comentarios.
level
[in] El nivel de seguimiento del que se va a informar. Consulte la sección de comentarios para obtener más información.
lpszFormat
[in] La cadena con formato que se va a enviar al dispositivo de volcado de memoria.
Comentarios
Consulte ATLTRACE2 para obtener una descripción de ATLTRACE. ATLTRACE y ATLTRACE2 tienen el mismo comportamiento, ATLTRACE se incluye por motivos de compatibilidad con versiones anteriores.
ATLTRACE2
Notifica advertencias a un dispositivo de salida, como la ventana del depurador, según las marcas y los niveles indicados.
ATLTRACE2(exp);
ATLTRACE2(
DWORD category,
UINT level,
LPCSTR lpszFormat, ...);
Parámetros
exp
[in] La cadena que se va a enviar a la ventana de salida o a cualquier aplicación que intercepte estos mensajes.
category
[in] Tipo de evento o método sobre el que se informa. Vea la lista de categorías en los Comentarios.
level
[in] El nivel de seguimiento del que se va a informar. Consulte la sección de comentarios para obtener más información.
lpszFormat
[in] La cadena printf de formato -style que se va a usar para crear una cadena que se va a enviar al dispositivo de volcado de memoria.
Comentarios
La forma abreviada de ATLTRACE2 escribe una cadena en la ventana de salida del depurador. La segunda forma de ATLTRACE2 también escribe la salida en la ventana de salida del depurador, pero está sujeta a la configuración de la Herramienta de seguimiento de ATL/MFC (consulte Ejemplo ATLTraceTool). Por ejemplo, si establece el nivel en 4 y la Herramienta de seguimiento de ATL/MFC en el nivel 0, no verá el mensaje. el nivel puede ser 0, 1, 2, 3 o 4. El valor predeterminado, 0, informa solo de los problemas más graves.
El parámetro categoría enumera las marcas de seguimiento que se van a establecer. Estas marcas corresponden a los tipos de métodos de los que quiere informar. En las tablas siguientes se enumeran las marcas de seguimiento válidas que puede usar para el parámetro categoría.
Marcas de seguimiento ATL
| Categoría ATL | Descripción |
|---|---|
atlTraceGeneral |
Informes de todas las aplicaciones ATL. El valor predeterminado. |
atlTraceCOM |
Informes de los métodos COM. |
atlTraceQI |
Informes de las llamadas QueryInterface. |
atlTraceRegistrar |
Informes del registro de objetos. |
atlTraceRefcount |
Informes del número de referencias cambiantes. |
atlTraceWindowing |
Informes de los métodos de Windows; por ejemplo, indica un id. de mapa de mensajes no válido. |
atlTraceControls |
Informes de los controles; por ejemplo, informa cuando se destruye un control o una ventana. |
atlTraceHosting |
Informes de los mensajes hospedados; por ejemplo, informa cuando se activa un cliente en un contenedor. |
atlTraceDBClient |
Informes sobre la plantilla de consumidor OLE DB. Por ejemplo, cuando una llamada a GetData falla, la salida puede contener el HRESULT. |
atlTraceDBProvider |
Informes sobre la plantilla de proveedor OLE DB. Por ejemplo, informa si ha fallado la creación de una columna. |
atlTraceSnapin |
Informes de la aplicación SnapIn de MMC. |
atlTraceNotImpl |
Informa de que la función indicada no está implementada. |
atlTraceAllocation |
Informes de los mensajes impresos por las herramientas de depuración de memoria en atldbgmem.h. |
Marcas de seguimiento de MFC
| Categoría MFC | Descripción |
|---|---|
traceAppMsg |
De uso general, mensajes de MFC. Siempre se recomienda. |
traceDumpContext |
Mensajes de CDumpContext. |
traceWinMsg |
Mensajes del código de control de los mensajes de MFC. |
traceMemory |
Mensajes del código de administración de la memoria de MFC. |
traceCmdRouting |
Mensajes del código de enrutamiento de los comandos de Windows MFC. |
traceHtml |
Se admiten mensajes de diálogo DHTML de MFC. |
traceSocket |
Mensajes de compatibilidad con sockets de MFC. |
traceOle |
Mensajes de compatibilidad con OLE de MFC. |
traceDatabase |
Mensajes de compatibilidad con la base de datos de MFC. |
traceInternet |
Mensajes de compatibilidad con Internet de MFC. |
Para declarar una categoría de seguimiento personalizada, declare una instancia global de la clase CTraceCategory como se indica a continuación:
CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);
El nombre de la categoría, MY_CATEGORY en este ejemplo, es el nombre que se especifica en el parámetro categoría. El primer parámetro es el nombre de la categoría que aparecerá en la Herramienta de seguimiento de ATL/MFC. El segundo parámetro es el nivel de seguimiento predeterminado. Este parámetro es opcional y el nivel de seguimiento predeterminado es 0.
Para usar una categoría definida por el usuario:
ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));
Para especificar que quiere filtrar los mensajes de seguimiento, inserte definiciones para estas macros en Stdafx.h antes de la instrucción #include <atlbase.h>.
También puede establecer el filtro en las directivas de preprocesador en el cuadro de diálogo Páginas de propiedades. Haga clic en la pestaña Preprocesador y, a continuación, inserte el valor global en el cuadro de edición Definiciones del preprocesador.
Atlbase.h contiene definiciones predeterminadas de las macros ATLTRACE2 y estas definiciones se usarán si no define estos símbolos antes de que se procese atlbase.h.
En las compilaciones de versión, ATLTRACE2 se compila a (void) 0.
ATLTRACE2 limita los contenidos de la cadena que se va a enviar al dispositivo de volcado de memoria a no más de 1023 caracteres, después aplicar el formato.
ATLTRACE y ATLTRACE2 tienen el mismo comportamiento, ATLTRACE se incluye por motivos de compatibilidad con versiones anteriores.
Ejemplo
int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'
Vea también
Macros
Funciones globales de depuración e informe de errores