偵錯和錯誤報告巨集
這些宏提供實用的偵錯和追蹤設施。
| 名稱 | 描述 |
|---|---|
| _ATL_DEBUG_INTERFACES | 將呼叫 時 _Module.Term 偵測到的任何介面流失寫入輸出視窗。 |
| _ATL_DEBUG_QI | 將所有呼叫 QueryInterface 寫入至輸出視窗。 |
| ATLASSERT | 執行與 C 執行時間程式庫中找到_ASSERTE 宏相同的功能 。 |
| ATLENSURE | 執行參數驗證。 如有需要呼叫 AtlThrow |
| ATLTRACENOTIMPL | 將訊息傳送至未實作指定函式的傾印裝置。 |
| ATLTRACE | 根據指定的旗標和層級，向輸出裝置報告警告，例如偵錯工具視窗。 包含回溯相容性。 |
| ATLTRACE2 | 根據指定的旗標和層級，向輸出裝置報告警告，例如偵錯工具視窗。 |
_ATL_DEBUG_INTERFACES
先定義這個宏，再包含任何 ATL 標頭檔，以追蹤元件介面上的所有 AddRef 和 Release 呼叫輸出視窗。
#define _ATL_DEBUG_INTERFACES
備註
追蹤輸出隨即出現，如下所示：
ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug
每個追蹤的第一個部分一律為 ATL: QIThunk 。 接下來是識別所使用之特定 介面 Thunk 的值。 介面 Thunk 是用來維護參考計數的物件，並提供此處使用的追蹤功能。 除了介面要求 IUnknown 之外，每個呼叫 QueryInterface 都會建立新的介面 Thunk（在此情況下，每次遵守 COM 的身分識別規則時，都會傳回相同的 Thunk）。
接下來，您會看到 AddRef 或 Release 指出呼叫哪一個方法。 接下來，您會看到一個值，識別介面參考計數已變更的物件。 追蹤的值是 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'
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應