偵錯和錯誤報告巨集

發行項
08/03/2024

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

名稱	描述
_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'

另請參閱

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

共用方式為