共用方式為


偵錯和錯誤報告巨集

這些宏提供實用的偵錯和追蹤設施。

名稱 描述
_ATL_DEBUG_INTERFACES 將呼叫 時 _Module.Term 偵測到的任何介面流失寫入輸出視窗。
_ATL_DEBUG_QI 將所有呼叫 QueryInterface 寫入至輸出視窗。
ATLASSERT 執行與 C 執行時間連結庫中找到_ASSERTE巨集相同的功能
ATLENSURE 執行參數驗證。 如有需要呼叫AtlThrow
ATLTRACENOTIMPL 將訊息傳送至未實作指定函式的傾印裝置。
ATLTRACE 根據指定的旗標和層級,向輸出裝置報告警告,例如調試程序視窗。 包含回溯相容性。
ATLTRACE2 根據指定的旗標和層級,向輸出裝置報告警告,例如調試程序視窗。

_ATL_DEBUG_INTERFACES

先定義此巨集,再包含任何 ATL 頭檔,以追蹤元件介面上的所有 AddRefRelease 呼叫輸出視窗。

#define _ATL_DEBUG_INTERFACES

備註

追蹤輸出隨即出現,如下所示:

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

每個追蹤的第一個部分一律為 ATL: QIThunk。 接下來是識別所使用之特定 介面 Thunk 的值。 介面 Thunk 是用來維護參考計數的物件,並提供此處使用的追蹤功能。 除了介面要求IUnknown之外,每個呼叫QueryInterface都會建立新的介面 Thunk(在此情況下,每次遵守 COM 的身分識別規則時,都會傳回相同的 Thunk)。

接下來,您會看到 AddRefRelease 指出呼叫哪一個方法。 接下來,您會看到一個值,識別介面參考計數已變更的物件。 追蹤的值是 this 物件的指標。

追蹤的參考計數是呼叫 或 Release 之後AddRef該 Thunk 上的參考計數。 請注意,此參考計數可能不符合 對象的參考計數。 每個 Thunk 都會維護自己的參考計數,以協助您完全遵守 COM 的參考計數規則。

追蹤的最後一個資訊片段是 對象的名稱,以及受 或 Release 呼叫影響的AddRef介面。

伺服器關閉 _Module.Term 且呼叫時偵測到的任何介面外泄,都會記錄如下:

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

此處提供的資訊會直接對應至先前追蹤語句中提供的資訊,因此您可以在介面 Thunk 的整個存留期內檢查參考計數。 此外,您會取得該介面 Thunk 上最大參考計數的指示。

注意

_ATL_DEBUG_INTERFACES可用於零售組建。

_ATL_DEBUG_QI

將所有呼叫 QueryInterface 寫入至輸出視窗。

#define _ATL_DEBUG_QI

備註

如果呼叫 QueryInterface 失敗,輸出視窗會顯示:

介面名稱 - failed

ATLASSERT

ATLASSERT 巨集會執行與 C 運行時間連結庫中找到_ASSERTE巨集相同的功能

ATLASSERT(booleanExpression);

參數

booleanExpression
評估為非零或 0 的運算式(包括指標)。

備註

在偵錯組建中,ATLASSERT 會 評估布爾值Expression ,並在結果為 false 時產生偵錯報告。

需求

標頭: atldef.h

ATLENSURE

此巨集用來驗證傳遞至函式的參數。

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

參數

booleanExpression
指定要測試的布爾表達式。

人力資源
指定要傳回的錯誤碼。

備註

這些宏提供一種機制來偵測並通知使用者不正確的參數使用方式。

巨集會呼叫 ATLASSERT,如果條件呼叫 失敗,則為 AtlThrow

在ATLENSURE案例中, AtlThrow 會使用 E_FAIL呼叫。

在ATLENSURE_THROW案例中, AtlThrow 會使用指定的 HRESULT 呼叫。

ATLENSURE 和 ATLASSERT 之間的差異在於 ATLENSURE 會在發行組建和偵錯組建中擲回例外狀況。

範例

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

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

需求

標頭: afx.h

ATLTRACENOTIMPL

在 ATL 的偵錯組建中,將字串 「 funcname 未實作」 傳送至傾印裝置,並傳回E_NOTIMPL。

ATLTRACENOTIMPL(funcname);

參數

funcname
[in]字串,包含未實作之函式的名稱。

備註

在發行組建中,只會傳回E_NOTIMPL。

範例

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

需求

標頭: atltrace.h

ATLTRACE

根據指定的旗標和層級,向輸出裝置報告警告,例如調試程序視窗。 包含回溯相容性。

ATLTRACE(exp);

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

參數

exp
[in]要傳送至輸出視窗的字串和變數,或任何陷設這些訊息的應用程式。

category
[in]要報告的事件或方法類型。 如需類別清單,請參閱。

level
[in]要報告的追蹤層級。 如需詳細資訊,請參閱。

lpszFormat
[in]要傳送至傾印裝置的格式化字串。

備註

如需 ATLTRACE 的描述,請參閱 ATLTRACE2 。 ATLTRACE 和ATLTRACE2有相同的行為,ATLTRACE 會包含在回溯相容性中。

ATLTRACE2

根據指定的旗標和層級,向輸出裝置報告警告,例如調試程序視窗。

ATLTRACE2(exp);

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

參數

exp
[in]要傳送至輸出視窗或任何擷取這些訊息的應用程式的字串。

category
[in]要報告的事件或方法類型。 如需類別清單,請參閱。

level
[in]要報告的追蹤層級。 如需詳細資訊,請參閱。

lpszFormat
[in] printf用來建立要傳送至傾印裝置之字串的 -style 格式字串。

備註

ATLTRACE2的簡短形式會將字串寫入調試程序的輸出視窗。 第二種形式的ATLTRACE2也會將輸出寫入調試程序的輸出視窗,但受限於 ATL/MFC 追蹤工具的設定(請參閱 ATLTraceTool 範例)。 例如,如果您將層級設定為 4,並將 ATL/MFC 追蹤工具設定為層級 0,則不會看到訊息。 層級 可以是 0、1、2、3 或 4。 默認值為 0,只會報告最嚴重的問題。

類別參數會列出要設定的追蹤旗標。 這些旗標會對應至您要報告的方法類型。 下表列出可用於 類別 參數的有效追蹤旗標。

ATL 追蹤旗標

ATL 類別 描述
atlTraceGeneral 報告所有 ATL 應用程式。 預設值。
atlTraceCOM COM 方法的報表。
atlTraceQI QueryInterface 呼叫的報表。
atlTraceRegistrar 報告對象的註冊。
atlTraceRefcount 變更參考計數的報告。
atlTraceWindowing Windows 方法的報表;例如,報告無效的訊息對應標識符。
atlTraceControls 控件報告;例如,當控件或其窗口終結時會報告。
atlTraceHosting 報告主控訊息;例如,報告容器中的用戶端何時啟動。
atlTraceDBClient OLE DB 消費者範本的報表;例如,呼叫 GetData 失敗時,輸出可以包含 HRESULT。
atlTraceDBProvider OLE DB 提供者範本的報告;例如,如果建立數據行失敗,則報告。
atlTraceSnapin MMC SnapIn 應用程式的報表。
atlTraceNotImpl 報告未實作指示的函式。
atlTraceAllocation 報告 atldbgmem.h 中記憶體偵錯工具所列印的訊息。

MFC 追蹤旗標

MFC 類別 描述
traceAppMsg 一般用途 MFC 訊息。 一律建議使用。
traceDumpContext 來自 CDumpContext 的訊息。
traceWinMsg 來自 MFC 訊息處理程式碼的訊息。
traceMemory 來自 MFC 記憶體管理程式碼的訊息。
traceCmdRouting 來自 MFC 的 Windows 命令路由程式代碼的訊息。
traceHtml 來自 MFC 的 DHTML 對話框支援的訊息。
traceSocket 來自 MFC 套接字支援的訊息。
traceOle 來自 MFC OLE 支援的訊息。
traceDatabase 來自 MFC 資料庫支援的訊息。
traceInternet 來自 MFC 因特網支援的訊息。

若要宣告自定義追蹤類別,請宣告 類別的 CTraceCategory 全域實例,如下所示:

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

在此範例中,類別名稱MY_CATEGORY是您指定給 category 參數的名稱。 第一個參數是會出現在 ATL/MFC 追蹤工具中的類別名稱。 第二個參數是預設追蹤層級。 此參數是選擇性的,預設追蹤層級為 0。

若要使用使用者定義的類別:

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

若要指定您想要篩選追蹤訊息,請在 語句之前 #include <atlbase.h> ,將這些宏的定義插入 Stdafx.h。

或者,您可以在 [屬性頁] 對話框中的預處理器指示詞中設定篩選。 按兩下 [ 預處理器] 索引 標籤,然後將全域 插入 [預處理器定義 ] 編輯方塊中。

Atlbase.h 包含ATLTRACE2宏的預設定義,如果您在處理 atlbase.h 之前未定義這些符號,則會使用這些定義。

在發行組建中,ATLTRACE2編譯為 (void) 0

ATLTRACE2格式化之後,將字串的內容限制為不超過 1023 個字元的傾印裝置。

ATLTRACE 和ATLTRACE2有相同的行為,ATLTRACE 會包含在回溯相容性中。

範例

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

另請參閱

巨集
偵錯和錯誤報告全域函式