デバッグとエラー報告に関するマクロ

[アーティクル]
04/03/2023

これらのマクロによって、便利なデバッグ機能およびトレース機能が提供されます。

名前	説明
_ATL_DEBUG_INTERFACES	`_Module.Term` の呼び出し時に検出されるすべてのインターフェイスリークを出力ウィンドウに書き込みます。
_ATL_DEBUG_QI	`QueryInterface` へのすべての呼び出しを出力ウィンドウに書き込みます。
ATLASSERT	C ランタイムライブラリにある _ASSERTE マクロと同じ機能を実行します。
ATLENSURE	パラメーターの検証を実行します。必要に応じて `AtlThrow` を呼び出します。
ATLTRACENOTIMPL	指定した関数が実装されていないというメッセージをダンプデバイスに送信します。
ATLTRACE	指定されたフラグとレベルに従って、デバッガーウィンドウなどの出力デバイスに警告を報告します。下位互換性のために含まれています。
ATLTRACE2	指定されたフラグとレベルに従って、デバッガーウィンドウなどの出力デバイスに警告を報告します。

_ATL_DEBUG_INTERFACES

コンポーネントのインターフェイスでのすべての AddRef 呼び出しと Release 呼び出しを出力ウィンドウでトレースするためには、ATL ヘッダーファイルを組み込む前にこのマクロを定義します。

#define _ATL_DEBUG_INTERFACES

解説

トレース出力は次のように表示されます。

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

各トレースの最初の部分は常に ATL: QIThunk です。その次は、使用される特定の "インターフェイスサンク" を示す値です。インターフェイスサンクは、参照数を保持し、ここで使用されるトレース機能を提供するために使用されるオブジェクトです。 QueryInterface を呼び出すたびに新しいインターフェイスサンクが作成されますが、IUnknown インターフェイスへの要求は除外されます (このケースでは、COM のID 規則に準拠するために毎回同じサンクが返されます)。

次には、呼び出されたメソッドを示す AddRef または Release が表示されます。その後には、インターフェイス参照数が変更されたオブジェクトを示す値が表示されます。トレースされる値は、オブジェクトの this ポインターです。

トレースされる参照数は、AddRef または Release が呼び出された後のサンクの参照数です。この参照数はオブジェクトの参照数と一致しない場合があることに注意してください。各サンクは、COM の参照数規則に完全に準拠できるように、参照数を独自に保持します。

トレースされる情報の最後の部分は、AddRef または Release 呼び出しによって影響を受けるオブジェクトの名前とインターフェイスです。

サーバーがシャットダウンして _Module.Term が呼び出されたときに検出されるインターフェイスリークは、次のようにログに記録されます。

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

ここで提供される情報は、前のトレースステートメントで提供された情報に直接マップされます。したがって、インターフェイスサンクの有効期間全体を通して参照数を調べることができます。また、そのインターフェイスサンクに対する最大参照数の表示を確認できます。

Note

_ATL_DEBUG_INTERFACES は、製品版ビルドで使用できます。

_ATL_DEBUG_QI

QueryInterface へのすべての呼び出しを出力ウィンドウに書き込みます。

#define _ATL_DEBUG_QI

解説

QueryInterface への呼び出しが失敗すると、出力ウィンドウに次のように表示されます。

インターフェイス名 - failed

ATLASSERT

ATLASSERT マクロは、C ランタイムライブラリにある _ASSERTE マクロと同じ機能を実行します。

ATLASSERT(booleanExpression);

パラメーター

booleanExpression
ゼロ以外または 0 に評価される式 (ポインターを含む)。

解説

デバッグビルドで、ATLASSERT は booleanExpression を評価し、結果が 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 is not implemented" をダンプデバイスに送信し、E_NOTIMPL を返します。

ATLTRACENOTIMPL(funcname);

パラメーター

funcname
[入力] 実装されていない関数の名前を含む文字列。

解説

リリースビルドでは、単に E_NOTIMPL が返されます。

例

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

要件

ヘッダー: atltrace.h

ATLTRACE

指定されたフラグとレベルに従って、デバッガーウィンドウなどの出力デバイスに警告を報告します。下位互換性のために含まれています。

ATLTRACE(exp);

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

パラメーター

exp
[入力] 出力ウィンドウまたはこれらのメッセージをトラップする任意のアプリケーションに送信する文字列と変数。

category
[入力] 報告するイベントまたはメソッドの種類。カテゴリの一覧については、「解説」を参照してください。

level
[入力] 報告するトレースレベル。詳細については、「解説」を参照してください。

lpszFormat
[入力] ダンプデバイスに送信する書式設定された文字列。

解説

ATLTRACE の説明については、「ATLTRACE2」を参照してください。 ATLTRACE と ATLTRACE2 の動作は同じです。ATLTRACE は下位互換性のために含まれています。

ATLTRACE2

指定されたフラグとレベルに従って、デバッガーウィンドウなどの出力デバイスに警告を報告します。

ATLTRACE2(exp);

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

パラメーター

exp
[入力] 出力ウィンドウまたはこれらのメッセージをトラップする任意のアプリケーションに送信する文字列。

category
[入力] 報告するイベントまたはメソッドの種類。カテゴリの一覧については、「解説」を参照してください。

level
[入力] 報告するトレースレベル。詳細については、「解説」を参照してください。

lpszFormat
[入力] ダンプデバイスに送信する文字列の作成に使用する printf 形式の書式指定文字列。

解説

ATLTRACE2 の短い形式では、デバッガーの出力ウィンドウに文字列が書き込まれます。 ATLTRACE2 の 2 番目の形式でもデバッガーの出力ウィンドウに文字列が書き込まれますが、ATL/MFC トレースツールの設定によって変わります (ATLTraceTool のサンプルに関するページを参照してください)。たとえば、"レベル" を 4 に設定して、ATL/MFC トレースツールのレベルを 0 に設定した場合、メッセージは表示されません。 level は、0、1、2、3 または 4 のいずれかです。既定値の 0 では、最も重大な問題のみが報告されます。

category パラメーターを使用して、設定するトレースフラグを指定します。これらのフラグは、報告するメソッドの種類に対応します。次の表に、category パラメーターで使用できる有効なトレースフラグを示します。

ATL トレースフラグ

ATL カテゴリ	説明
`atlTraceGeneral`	すべての ATL アプリケーションに関するレポート。これが既定値です。
`atlTraceCOM`	COM メソッドに関するレポート。
`atlTraceQI`	QueryInterface 呼び出しに関するレポート。
`atlTraceRegistrar`	オブジェクトの登録に関するレポート。
`atlTraceRefcount`	参照数の変化に関するレポート。
`atlTraceWindowing`	Windows メソッドに関するレポート。たとえば、無効なメッセージマップ ID を報告します。
`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 トレースツールに表示されるカテゴリ名です。 2 番目のパラメーターは、既定のトレースレベルです。このパラメーターは省略可能で、既定のトレースレベルは 0 です。

ユーザー定義カテゴリを使用するには:

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

トレースメッセージをフィルター処理するように指定するには、これらのマクロの定義を Stdafx.h の #include <atlbase.h> ステートメントの前に挿入します。

または、[プロパティページ] ダイアログボックスでプリプロセッサディレクティブにフィルターを設定できます。 [プリプロセッサ] タブをクリックしてから、グローバルを [プリプロセッサの定義] 編集ボックスに挿入します。

atlbase.h には ATLTRACE2 マクロの既定定義が含まれます。これらの定義は、atlbase.h が処理される前にこれらのシンボルを定義しない場合に使用されます。

リリースビルドでは、ATLTRACE2 は (void) 0 にコンパイルされます。

ATLTRACE2 では、ダンプデバイスに送信される、書式設定後の文字列の内容が 1,023 文字以下に制限されます。

ATLTRACE と ATLTRACE2 の動作は同じです。ATLTRACE は下位互換性のために含まれています。

例

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

次の方法で共有

デバッグとエラー報告に関するマクロ

_ATL_DEBUG_INTERFACES

解説

_ATL_DEBUG_QI

解説

ATLASSERT

パラメーター

解説

要件

ATLENSURE

パラメーター

解説

例

要件

ATLTRACENOTIMPL

パラメーター

解説

例

要件

ATLTRACE

パラメーター

解説

ATLTRACE2

パラメーター

解説

ATL トレースフラグ

MFC トレースフラグ

例

関連項目

フィードバック

その他のリソース

次の方法で共有

デバッグとエラー報告に関するマクロ

_ATL_DEBUG_INTERFACES

解説

_ATL_DEBUG_QI

解説

ATLASSERT

パラメーター

解説

要件

ATLENSURE

パラメーター

解説

例

要件

ATLTRACENOTIMPL

パラメーター

解説

例

要件

ATLTRACE

パラメーター

解説

ATLTRACE2

パラメーター

解説

ATL トレース フラグ

MFC トレース フラグ

例

関連項目

フィードバック

その他のリソース

ATL トレースフラグ

MFC トレースフラグ