Debuggen und Fehlerberichterstattungs-Makros

Diese Makros bieten nützliche Debug- und Ablaufverfolgungsfunktionen.

_ATL_DEBUG_INTERFACES

Definieren Sie dieses Makro, bevor Sie ATL-Headerdateien einschließen, um alle AddRef Aufrufe Release der Schnittstellen Ihrer Komponenten zum Ausgabefenster nachzuverfolgen.

#define _ATL_DEBUG_INTERFACES

Hinweise

Die Ablaufverfolgungsausgabe wird wie unten dargestellt angezeigt:

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

Der erste Teil jeder Ablaufverfolgung ist ATL: QIThunkimmer . Als Nächstes ist ein Wert, der die spezifische Schnittstelle thunk identifiziert, die verwendet wird. Eine Schnittstelle thunk ist ein Objekt, das verwendet wird, um eine Referenzanzahl zu verwalten und die hier verwendete Ablaufverfolgungsfunktion bereitzustellen. Eine neue Schnittstelle thunk wird auf jedem Aufruf erstellt, QueryInterface mit Ausnahme von Anforderungen für die IUnknown Schnittstelle (in diesem Fall wird das gleiche Thunk jedes Mal zurückgegeben, um die Identitätsregeln von COM einzuhalten).

Als Nächstes werden Sie sehen AddRef oder Release angeben, welche Methode aufgerufen wurde. Anschließend wird ein Wert angezeigt, der das Objekt identifiziert, dessen Schnittstellenverweisanzahl geändert wurde. Der Ablaufverfolgungswert ist der this Zeiger des Objekts.

Die Referenzanzahl, die nachverfolgt wird, ist die Referenzanzahl für diesen Thunk nach AddRef oder Release wurde aufgerufen. Beachten Sie, dass diese Verweisanzahl möglicherweise nicht mit der Referenzanzahl für das Objekt übereinstimmt. Jeder Thunk verwaltet seine eigene Referenzanzahl, um Ihnen dabei zu helfen, die Referenzzählungsregeln der COM vollständig einzuhalten.

Der letzte Teil der Informationen, die nachverfolgt werden, ist der Name des Objekts und die Schnittstelle, die AddRef vom Aufruf Release betroffen ist.

Alle Schnittstellenlecks, die erkannt werden, wenn der Server heruntergefahren wird und _Module.Term aufgerufen wird, werden wie folgt protokolliert:

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

Die hier bereitgestellten Informationen beziehen sich direkt auf die in den vorherigen Ablaufverfolgungsanweisungen angegebenen Informationen, sodass Sie die Referenzanzahl während der gesamten Lebensdauer einer Schnittstelle thunk untersuchen können. Darüber hinaus erhalten Sie einen Hinweis auf die maximale Referenzanzahl auf dieser Schnittstelle Thunk.

_ATL_DEBUG_QI

Schreibt alle Aufrufe in QueryInterface das Ausgabefenster.

#define _ATL_DEBUG_QI

Hinweise

Wenn ein Aufruf QueryInterface fehlgeschlagen ist, wird das Ausgabefenster angezeigt:

Schnittstellenname - failed

ATLASSERT

Das ATLASSERT-Makro führt dieselbe Funktionalität wie das _ASSERTE Makros in der C-Laufzeitbibliothek aus.

ATLASSERT(booleanExpression);

Parameter

booleanExpression
Ausdruck (einschließlich Zeigern), der als "nonzero" oder "0" ausgewertet wird.

Hinweise

In Debugbuilds wertet ATLASSERT booleanExpression aus und generiert einen Debugbericht, wenn das Ergebnis falsch ist.

Anforderungen

Kopfzeile: atldef.h

ATLENSURE

Dieses Makro wird verwendet, um Parameter zu überprüfen, die an eine Funktion übergeben werden.

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

Parameter

booleanExpression
Gibt einen booleschen Ausdruck an, der getestet werden soll.

Hr
Gibt einen fehlercode an, der zurückgegeben werden soll.

Hinweise

Diese Makros bieten einen Mechanismus zum Erkennen und Benachrichtigen des Benutzers über die falsche Parameterverwendung.

Das Makro ruft ATLASSERT auf und wenn die Bedingung fehlschlägt, werden Aufrufe ausgeführt AtlThrow.

Im ATLENSURE-Fall AtlThrow wird mit E_FAIL aufgerufen.

Im ATLENSURE_THROW Fall AtlThrow wird mit dem angegebenen HRESULT aufgerufen.

Der Unterschied zwischen ATLENSURE und ATLASSERT besteht darin, dass ATLENSURE eine Ausnahme in Releasebuilds sowie in Debugbuilds auslöst.

Beispiel

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

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

Anforderungen

Header: afx.h

ATLTRACENOTIMPL

Sendet in Debugbuilds von ATL die Zeichenfolge " Funcname is not implemented" an das Dump-Gerät und gibt E_NOTIMPL zurück.

ATLTRACENOTIMPL(funcname);

Parameter

Funcname
[in] Eine Zeichenfolge mit dem Namen der Funktion, die nicht implementiert ist.

Hinweise

Gibt in Releasebuilds einfach E_NOTIMPL zurück.

Beispiel

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

Anforderungen

Kopfzeile: atltrace.h

ATLTRACE

Meldet Warnungen an ein Ausgabegerät, z. B. das Debuggerfenster, entsprechend den angegebenen Flags und Ebenen. Aus Gründen der Abwärtskompatibilität enthalten.

ATLTRACE(exp);

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

Parameter

exp
[in] Die Zeichenfolge und Variablen, die an das Ausgabefenster oder eine beliebige Anwendung gesendet werden sollen, die diese Nachrichten abfangen soll.

category
[in] Typ des Ereignisses oder der Methode, für das bzw. die Bericht erstellt werden soll. Eine Liste der Kategorien finden Sie in den Hinweisen.

level
[in] Die Ebene der zu meldenden Ablaufverfolgung. Ausführliche Informationen finden Sie in den Hinweisen.

lpszFormat
[in] Die formatierte Zeichenfolge, die an das Speicherabbildgerät gesendet werden soll.

Hinweise

Eine Beschreibung von ATLTRACE finden Sie unter ATLTRACE2 . ATLTRACE und ATLTRACE2 haben das gleiche Verhalten, ATLTRACE ist aus Gründen der Abwärtskompatibilität enthalten.

ATLTRACE2

Meldet Warnungen an ein Ausgabegerät, z. B. das Debuggerfenster, entsprechend den angegebenen Flags und Ebenen.

ATLTRACE2(exp);

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

Parameter

exp
[in] Die Zeichenfolge, die an das Ausgabefenster oder eine beliebige Anwendung gesendet werden soll, die diese Nachrichten abfangen soll.

category
[in] Typ des Ereignisses oder der Methode, für das bzw. die Bericht erstellt werden soll. Eine Liste der Kategorien finden Sie in den Hinweisen.

level
[in] Die Ebene der zu meldenden Ablaufverfolgung. Ausführliche Informationen finden Sie in den Hinweisen.

lpszFormat
[in] Die printfFormatzeichenfolge -Formatvorlage, die zum Erstellen einer Zeichenfolge zum Senden an das Dumpgerät verwendet werden soll.

Hinweise

Die kurze Form von ATLTRACE2 schreibt eine Zeichenfolge in das Ausgabefenster des Debuggers. Die zweite Form von ATLTRACE2 schreibt auch die Ausgabe in das Ausgabefenster des Debuggers, unterliegt jedoch den Einstellungen des ATL/MFC-Ablaufverfolgungstools (siehe ATLTraceTool-Beispiel). Wenn Sie beispielsweise die Ebene 4 und das ATL/MFC-Ablaufverfolgungstool auf Ebene 0 festlegen, wird die Meldung nicht angezeigt. Die Ebene kann 0, 1, 2, 3 oder 4 sein. Der Standardwert 0 meldet nur die schwerwiegendsten Probleme.

Der Category-Parameter listet die festzulegenden Ablaufverfolgungskennzeichnungen auf. Diese Flags entsprechen den Methodentypen, für die Sie berichten möchten. In den folgenden Tabellen sind die gültigen Ablaufverfolgungskennzeichnungen aufgeführt, die Sie für den Kategorieparameter verwenden können.

ATL-Ablaufverfolgungskennzeichnungen

MFC-Ablaufverfolgungskennzeichnungen

Um eine benutzerdefinierte Ablaufverfolgungskategorie zu deklarieren, deklarieren Sie eine globale Instanz der CTraceCategory Klasse wie folgt:

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

Der Kategoriename, MY_CATEGORY in diesem Beispiel, ist der Name, den Sie für den Kategorieparameter angeben. Der erste Parameter ist der Kategoriename, der im ATL/MFC-Ablaufverfolgungstool angezeigt wird. Der zweite Parameter ist die Standardablaufverfolgungsebene. Dieser Parameter ist optional, und die Standardablaufverfolgungsebene ist 0.

So verwenden Sie eine benutzerdefinierte Kategorie:

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

Um anzugeben, dass Sie die Ablaufverfolgungsmeldungen filtern möchten, fügen Sie Vor der #include <atlbase.h> Anweisung Definitionen für diese Makros in Stdafx.h ein.

Alternativ können Sie den Filter in den Präprozessordirektiven im Dialogfeld Eigenschaftenseiten festlegen. Klicken Sie auf die Registerkarte "Präprozessor ", und fügen Sie dann das Globale in das Bearbeitungsfeld "Präprozessordefinitionen " ein.

Atlbase.h enthält Standarddefinitionen der ATLTRACE2 Makros, und diese Definitionen werden verwendet, wenn Sie diese Symbole nicht definieren, bevor atlbase.h verarbeitet wird.

In Releasebuilds kompiliert ATLTRACE2 zu (void) 0.

ATLTRACE2 beschränkt den Inhalt der Zeichenfolge, die nach der Formatierung an das Dumpgerät gesendet werden soll, auf maximal 1023 Zeichen.

ATLTRACE und ATLTRACE2 haben das gleiche Verhalten, ATLTRACE ist aus Gründen der Abwärtskompatibilität enthalten.

Beispiel

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

Siehe auch

Makros
Debuggen und globale Funktionen für die Fehlerberichterstattung