Debuggen und Fehlerberichterstattungs-Makros

Diese Makros bieten nützliche Debug- und Ablaufverfolgungsfunktionen.

Name	Beschreibung
_ATL_DEBUG_INTERFACES	Schreibt in das Ausgabefenster alle Schnittstellenlecks, die beim _Module.Term Aufrufen erkannt werden.
_ATL_DEBUG_QI	Schreibt alle Aufrufe in QueryInterface das Ausgabefenster.
ATLASSERT	Führt dieselbe Funktionalität wie das _ASSERTE Makros in der C-Laufzeitbibliothek aus.
ATLENSURE	Führt die Parameterüberprüfung aus. Bei Bedarf anrufen AtlThrow
ATLTRACENOTIMPL	Sendet eine Nachricht an das Dumpgerät, dass die angegebene Funktion nicht implementiert ist.
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.
ATLTRACE2	Meldet Warnungen an ein Ausgabegerät, z. B. das Debuggerfenster, entsprechend den angegebenen Flags und Ebenen.

_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 Standard 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-Standard eine eigene Referenzanzahl, die Ihnen dabei hilft, 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.

Hinweis

_ATL_DEBUG_INTERFACES können in Einzelhandelsbuilds verwendet werden.

_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

ATL-Kategorie	Beschreibung
atlTraceGeneral	Meldet alle ATL-Anwendungen. Der Standardwert.
atlTraceCOM	Berichte zu COM-Methoden.
atlTraceQI	Berichte zu QueryInterface-Aufrufen.
atlTraceRegistrar	Meldet die Registrierung von Objekten.
atlTraceRefcount	Berichte zur Änderung der Bezugsanzahl.
atlTraceWindowing	Berichte zu Fenstermethoden; Meldet beispielsweise eine ungültige Nachrichtenzuordnungs-ID.
atlTraceControls	Berichte zu Kontrollen; Meldet beispielsweise, wenn ein Steuerelement oder sein Fenster zerstört wird.
atlTraceHosting	Meldet das Hosten von Nachrichten; Meldet beispielsweise, wenn ein Client in einem Container aktiviert wird.
atlTraceDBClient	Berichte zu OLE DB Consumer Template; Wenn beispielsweise ein Aufruf von GetData fehlschlägt, kann die Ausgabe das HRESULT enthalten.
atlTraceDBProvider	Berichte zur OLE DB-Anbietervorlage; Meldet beispielsweise, wenn die Erstellung einer Spalte fehlgeschlagen ist.
atlTraceSnapin	Berichte für die MMC SnapIn-Anwendung.
atlTraceNotImpl	Meldet, dass die angegebene Funktion nicht implementiert ist.
atlTraceAllocation	Meldet Nachrichten, die von den Speicherdebuggingtools in atldbgmem.h gedruckt werden.

MFC-Ablaufverfolgungskennzeichnungen

MFC-Kategorie	Beschreibung
traceAppMsg	Allgemeiner Zweck, MFC-Nachrichten. Immer empfohlen.
traceDumpContext	Nachrichten von CDumpContext.
traceWinMsg	Nachrichten aus dem Nachrichtenverarbeitungscode von MFC.
traceMemory	Nachrichten aus dem Speicherverwaltungscode von MFC.
traceCmdRouting	Nachrichten aus dem Windows-Befehlsroutingcode von MFC.
traceHtml	Unterstützung von Nachrichten aus dem DHTML-Dialogfeld von MFC.
traceSocket	Nachrichten von der Socketunterstützung von MFC.
traceOle	Nachrichten von der OLE-Unterstützung von MFC.
traceDatabase	Nachrichten von der Datenbankunterstützung von MFC.
traceInternet	Nachrichten von der Internetunterstützung von MFC.

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