デバッグとエラー報告に関するマクロ
これらのマクロによって、便利なデバッグ機能およびトレース機能が提供されます。
| 名前 | 説明 |
|---|---|
| _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'
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示