次の方法で共有


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

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

名前 説明
_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'

関連項目

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