Condividi tramite


Macro di debug e segnalazione errori

Queste macro forniscono utili funzionalità di debug e traccia.

Nome Descrizione
_ATL_DEBUG_INTERFACES Scrive, nella finestra di output, eventuali perdite di interfaccia rilevate quando _Module.Term viene chiamato .
_ATL_DEBUG_QI Scrive tutte le chiamate alla QueryInterface finestra di output.
ATLASSERT Esegue la stessa funzionalità della macro _ASSERTE presente nella libreria di runtime C.
ATLENSURE Esegue la convalida dei parametri. Chiamare AtlThrow se necessario
ATLTRACENOTIMPL Invia un messaggio al dispositivo di dump che la funzione specificata non è implementata.
ATLTRACE Segnala avvisi a un dispositivo di output, ad esempio la finestra del debugger, in base ai flag e ai livelli indicati. Incluso per la compatibilità con le versioni precedenti.
ATLTRACE2 Segnala avvisi a un dispositivo di output, ad esempio la finestra del debugger, in base ai flag e ai livelli indicati.

_ATL_DEBUG_INTERFACES

Definire questa macro prima di includere tutti i file di intestazione ATL per tracciare tutte le AddRef chiamate alle Release interfacce dei componenti nella finestra di output.

#define _ATL_DEBUG_INTERFACES

Osservazioni:

L'output di traccia verrà visualizzato come illustrato di seguito:

ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug

La prima parte di ogni traccia sarà ATL: QIThunksempre . Successivamente è un valore che identifica la particolare interfaccia usata. Un'interfacciaa è un oggetto usato per mantenere un conteggio dei riferimenti e fornire la funzionalità di traccia usata qui. Ogni chiamata a ogni chiamata viene QueryInterface creata una nuova interfaccia, ad eccezione delle richieste per l'interfaccia IUnknown (in questo caso, viene restituito lo stesso thunk ogni volta per rispettare le regole di identità com).

Verrà quindi visualizzato AddRef o Release indicato quale metodo è stato chiamato. Successivamente, verrà visualizzato un valore che identifica l'oggetto il cui conteggio dei riferimenti dell'interfaccia è stato modificato. Il valore tracciato è il this puntatore dell'oggetto .

Il conteggio dei riferimenti tracciato è il conteggio dei riferimenti su tale thunk dopo AddRef o Release è stato chiamato. Si noti che questo conteggio dei riferimenti potrebbe non corrispondere al conteggio dei riferimenti per l'oggetto . Ogni thunk mantiene il proprio conteggio dei riferimenti per aiutarti a rispettare pienamente le regole di conteggio dei riferimenti COM.

L'ultima parte di informazioni tracciata è il nome dell'oggetto e l'interfaccia interessata dalla AddRef chiamata o Release .

Eventuali perdite di interfaccia rilevate quando il server viene arrestato e _Module.Term viene chiamato verranno registrate come segue:

ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug

Le informazioni fornite in questo articolo sono mappate direttamente alle informazioni fornite nelle istruzioni di traccia precedenti, in modo da poter esaminare i conteggi dei riferimenti per tutta la durata di un'interfaccia. Inoltre, si ottiene un'indicazione del conteggio massimo dei riferimenti per tale interfaccia.

Nota

_ATL_DEBUG_INTERFACES possono essere usati nelle build di vendita al dettaglio.

_ATL_DEBUG_QI

Scrive tutte le chiamate alla QueryInterface finestra di output.

#define _ATL_DEBUG_QI

Osservazioni:

Se una chiamata a QueryInterface non è riuscita, verrà visualizzata la finestra di output:

nome dell'interfaccia - failed

ATLASSERT

La macro ATLASSERT esegue la stessa funzionalità della macro _ASSERTE disponibile nella libreria di runtime C.

ATLASSERT(booleanExpression);

Parametri

booleanExpression
Espressione (inclusi i puntatori) che restituisce un valore diverso da zero oppure 0.

Osservazioni:

Nelle compilazioni di debug ATLASSERT valuta booleanExpression e genera un report di debug quando il risultato è false.

Requisiti

Intestazione: atldef.h

ATLENSURE

Questa macro viene utilizzata per convalidare i parametri passati a una funzione.

ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);

Parametri

booleanExpression
Specifica un'espressione booleana da testare.

Hr
Specifica un codice di errore da restituire.

Osservazioni:

Queste macro forniscono un meccanismo per rilevare e notificare all'utente l'utilizzo di parametri non corretti.

La macro chiama ATLASSERT e se la condizione non riesce chiama AtlThrow.

Nel caso ATLENSURE, AtlThrow viene chiamato con E_FAIL.

Nel caso ATLENSURE_THROW viene AtlThrow chiamato con il valore HRESULT specificato.

La differenza tra ATLENSURE e ATLASSERT è che ATLENSURE genera un'eccezione nelle build di rilascio e nelle compilazioni di debug.

Esempio

void MyImportantFunction(char* psz)
{
   ATLENSURE(NULL != psz);

   char mysz[64];
   strcpy_s(mysz, sizeof(mysz), psz);
}

Requisiti

Intestazione: afx.h

ATLTRACENOTIMPL

Nelle build di debug di ATL, invia la stringa " funcname non è implementato" al dispositivo di dump e restituisce E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

Parametri

funcname
[in] Stringa contenente il nome della funzione non implementata.

Osservazioni:

Nelle build di rilascio, restituisce semplicemente E_NOTIMPL.

Esempio

ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));   

Requisiti

Intestazione: atltrace.h

ATLTRACE

Segnala avvisi a un dispositivo di output, ad esempio la finestra del debugger, in base ai flag e ai livelli indicati. Incluso per la compatibilità con le versioni precedenti.

ATLTRACE(exp);

ATLTRACE(
    DWORD category,
    UINT  level,
    LPCSTR lpszFormat, ...);

Parametri

exp
[in] Stringa e variabili da inviare alla finestra di output o a qualsiasi applicazione che intercettare questi messaggi.

category
[in] Tipo di evento o metodo su cui segnalare. Per un elenco di categorie, vedere le osservazioni.

level
[in] Livello di traccia da segnalare. Per informazioni dettagliate, vedere la sezione Osservazioni.

lpszFormat
[in] Stringa formattata da inviare al dispositivo di dump.

Osservazioni:

Per una descrizione di ATLTRACE, vedere ATLTRACE2 . ATLTRACE e ATLTRACE2 hanno lo stesso comportamento, ATLTRACE è incluso per la compatibilità con le versioni precedenti.

ATLTRACE2

Segnala avvisi a un dispositivo di output, ad esempio la finestra del debugger, in base ai flag e ai livelli indicati.

ATLTRACE2(exp);

ATLTRACE2(
    DWORD category,
    UINT level,
    LPCSTR lpszFormat,  ...);

Parametri

exp
[in] Stringa da inviare alla finestra di output o a qualsiasi applicazione che intercettare questi messaggi.

category
[in] Tipo di evento o metodo su cui segnalare. Per un elenco di categorie, vedere le osservazioni.

level
[in] Livello di traccia da segnalare. Per informazioni dettagliate, vedere la sezione Osservazioni.

lpszFormat
[in] Stringa printfdi formato -style da usare per creare una stringa da inviare al dispositivo di dump.

Osservazioni:

La forma breve di ATLTRACE2 scrive una stringa nella finestra di output del debugger. La seconda forma di ATLTRACE2 scrive anche l'output nella finestra di output del debugger, ma è soggetto alle impostazioni dello strumento di traccia ATL/MFC (vedere Esempio ATLTraceTool). Ad esempio, se si imposta il livello su 4 e lo strumento di traccia ATL/MFC al livello 0, il messaggio non verrà visualizzato. il livello può essere 0, 1, 2, 3 o 4. Il valore predefinito, 0, segnala solo i problemi più gravi.

Il parametro category elenca i flag di traccia da impostare. Questi flag corrispondono ai tipi di metodi da segnalare. Le tabelle seguenti elencano i flag di traccia validi che è possibile usare per il parametro category .

Flag di traccia ATL

Categoria ATL Descrizione
atlTraceGeneral Report su tutte le applicazioni ATL. Valore predefinito.
atlTraceCOM Report sui metodi COM.
atlTraceQI Report sulle chiamate QueryInterface.
atlTraceRegistrar Segnala la registrazione degli oggetti.
atlTraceRefcount Report sulla modifica del conteggio dei riferimenti.
atlTraceWindowing Report sui metodi di Windows; Ad esempio, segnala un ID mappa messaggi non valido.
atlTraceControls Rapporti sui controlli; Ad esempio, segnala quando un controllo o la relativa finestra viene eliminato definitivamente.
atlTraceHosting Report che ospitano messaggi; Ad esempio, segnala quando viene attivato un client in un contenitore.
atlTraceDBClient Report sul modello di consumer OLE DB; Ad esempio, quando una chiamata a GetData ha esito negativo, l'output può contenere HRESULT.
atlTraceDBProvider Report sul modello di provider OLE DB; Ad esempio, segnala se la creazione di una colonna non è riuscita.
atlTraceSnapin Report per l'applicazione SnapIn MMC.
atlTraceNotImpl Segnala che la funzione indicata non è implementata.
atlTraceAllocation Segnala i messaggi stampati dagli strumenti di debug della memoria in atldbgmem.h.

Flag di traccia MFC

Categoria MFC Descrizione
traceAppMsg Messaggi MFC per utilizzo generico. Sempre consigliato.
traceDumpContext Messaggi da CDumpContext.
traceWinMsg Messaggi dal codice di gestione dei messaggi di MFC.
traceMemory Messaggi dal codice di gestione della memoria di MFC.
traceCmdRouting Messaggi dal codice di routing dei comandi windows di MFC.
traceHtml Messaggi dal supporto della finestra di dialogo DHTML di MFC.
traceSocket Messaggi dal supporto socket MFC.
traceOle Messaggi dal supporto OLE di MFC.
traceDatabase Messaggi dal supporto del database MFC.
traceInternet Messaggi provenienti dal supporto Internet di MFC.

Per dichiarare una categoria di traccia personalizzata, dichiarare un'istanza globale della CTraceCategory classe come indicato di seguito:

CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);

Il nome della categoria, MY_CATEGORY in questo esempio, è il nome specificato per il parametro category . Il primo parametro è il nome della categoria che verrà visualizzato nello strumento di traccia ATL/MFC. Il secondo parametro è il livello di traccia predefinito. Questo parametro è facoltativo e il livello di traccia predefinito è 0.

Per usare una categoria definita dall'utente:

ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));

Per specificare che si desidera filtrare i messaggi di traccia, inserire definizioni per queste macro in Stdafx.h prima dell'istruzione #include <atlbase.h> .

In alternativa, è possibile impostare il filtro nelle direttive del preprocessore nella finestra di dialogo Pagine delle proprietà. Fare clic sulla scheda Preprocessore e quindi inserire il valore globale nella casella di modifica Definizioni del preprocessore.

Atlbase.h contiene definizioni predefinite delle macro ATLTRACE2 e queste definizioni verranno usate se non si definiscono questi simboli prima dell'elaborazione di atlbase.h.

Nelle build di versione ATLTRACE2 viene compilato in (void) 0.

ATLTRACE2 limita il contenuto della stringa da inviare al dispositivo di dump a non più di 1023 caratteri, dopo la formattazione.

ATLTRACE e ATLTRACE2 hanno lo stesso comportamento, ATLTRACE è incluso per la compatibilità con le versioni precedenti.

Esempio

int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'

Vedi anche

Macro
Funzioni globali di debug e segnalazione errori