Makro Penelusuran Kesalahan dan Pelaporan Kesalahan
Makro ini menyediakan fasilitas penelusuran kesalahan dan pelacakan yang berguna.
| Nama | Deskripsi |
|---|---|
| _ATL_DEBUG_INTERFACES | Menulis, ke jendela output, kebocoran antarmuka apa pun yang terdeteksi ketika _Module.Term dipanggil. |
| _ATL_DEBUG_QI | Menulis semua panggilan ke QueryInterface jendela output. |
| ATLASSERT | Melakukan fungsionalitas yang sama dengan makro _ASSERTE yang ditemukan di pustaka run-time C. |
| ATLENSURE | Melakukan validasi parameter. Panggil AtlThrow jika diperlukan |
| ATLTRACENOTIMPL | Mengirim pesan ke perangkat cadangan bahwa fungsi yang ditentukan tidak diimplementasikan. |
| ATLTRACE | Melaporkan peringatan ke perangkat output, seperti jendela debugger, sesuai dengan bendera dan tingkat yang ditunjukkan. Disertakan untuk kompatibilitas mundur. |
| ATLTRACE2 | Melaporkan peringatan ke perangkat output, seperti jendela debugger, sesuai dengan bendera dan tingkat yang ditunjukkan. |
_ATL_DEBUG_INTERFACES
Tentukan makro ini sebelum menyertakan file header ATL untuk melacak semua AddRef dan Release panggilan pada antarmuka komponen Anda ke jendela output.
#define _ATL_DEBUG_INTERFACES
Keterangan
Output jejak akan muncul seperti yang ditunjukkan di bawah ini:
ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug
Bagian pertama dari setiap jejak akan selalu .ATL: QIThunk Selanjutnya adalah nilai yang mengidentifikasi thunk antarmuka tertentu yang digunakan. Thunk antarmuka adalah objek yang digunakan untuk mempertahankan jumlah referensi dan menyediakan kemampuan pelacakan yang digunakan di sini. Thunk antarmuka baru dibuat pada setiap panggilan kecuali QueryInterface untuk permintaan antarmuka IUnknown (dalam hal ini, thunk yang sama dikembalikan setiap kali untuk mematuhi aturan identitas COM).
Selanjutnya Anda akan melihat AddRef atau Release menunjukkan metode mana yang dipanggil. Setelah itu, Anda akan melihat nilai yang mengidentifikasi objek yang jumlah referensi antarmukanya diubah. Nilai yang this dilacak adalah penunjuk objek.
Jumlah referensi yang ditelusuri adalah jumlah referensi pada thunk tersebut setelah AddRef atau Release dipanggil. Perhatikan bahwa jumlah referensi ini mungkin tidak cocok dengan jumlah referensi untuk objek. Setiap thunk mempertahankan jumlah referensinya sendiri untuk membantu Anda sepenuhnya mematuhi aturan penghitungan referensi COM.
Bagian akhir informasi yang dilacak adalah nama objek dan antarmuka yang terpengaruh oleh AddRef atau Release panggilan.
Setiap kebocoran antarmuka yang terdeteksi ketika server dimatikan dan _Module.Term dipanggil akan dicatat seperti ini:
ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug
Informasi yang diberikan di sini memetakan langsung ke informasi yang disediakan dalam pernyataan pelacakan sebelumnya, sehingga Anda dapat memeriksa jumlah referensi sepanjang masa pakai thunk antarmuka. Selain itu, Anda mendapatkan indikasi jumlah referensi maksimum pada thunk antarmuka tersebut.
Catatan
_ATL_DEBUG_INTERFACES dapat digunakan dalam build ritel.
_ATL_DEBUG_QI
Menulis semua panggilan ke QueryInterface jendela output.
#define _ATL_DEBUG_QI
Keterangan
Jika panggilan QueryInterface gagal, jendela output akan ditampilkan:
nama antarmuka - failed
ATLASSERT
Makro ATLASSERT melakukan fungsionalitas yang sama dengan makro _ASSERTE yang ditemukan di pustaka run-time C.
ATLASSERT(booleanExpression);
Parameter
booleanExpression
Ekspresi (termasuk pointer) yang mengevaluasi ke nonzero atau 0.
Keterangan
Dalam build debug, ATLASSERT mengevaluasi booleanExpression dan menghasilkan laporan debug saat hasilnya salah.
Persyaratan
Header: atldef.h
ATLENSURE
Makro ini digunakan untuk memvalidasi parameter yang diteruskan ke fungsi.
ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);
Parameter
booleanExpression
Menentukan ekspresi boolean yang akan diuji.
Hr
Menentukan kode kesalahan yang akan dikembalikan.
Keterangan
Makro ini menyediakan mekanisme untuk mendeteksi dan memberi tahu pengguna tentang penggunaan parameter yang salah.
Makro memanggil ATLASSERT dan jika kondisi gagal memanggil AtlThrow.
Dalam kasus ATLENSURE, AtlThrow dipanggil dengan E_FAIL.
Dalam kasus ATLENSURE_THROW, AtlThrow dipanggil dengan HRESULT yang ditentukan.
Perbedaan antara ATLENSURE dan ATLASSERT adalah ATLENSURE melemparkan pengecualian dalam build Rilis serta dalam build Debug.
Contoh
void MyImportantFunction(char* psz)
{
ATLENSURE(NULL != psz);
char mysz[64];
strcpy_s(mysz, sizeof(mysz), psz);
}
Persyaratan
Header: afx.h
ATLTRACENOTIMPL
Dalam build debug ATL, mengirim string " funcname tidak diimplementasikan" ke perangkat cadangan dan mengembalikan E_NOTIMPL.
ATLTRACENOTIMPL(funcname);
Parameter
nama funcname
[di] String yang berisi nama fungsi yang tidak diimplementasikan.
Keterangan
Dalam build rilis, hanya mengembalikan E_NOTIMPL.
Contoh
ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));
Persyaratan
Header: atltrace.h
ATLTRACE
Melaporkan peringatan ke perangkat output, seperti jendela debugger, sesuai dengan bendera dan tingkat yang ditunjukkan. Disertakan untuk kompatibilitas mundur.
ATLTRACE(exp);
ATLTRACE(
DWORD category,
UINT level,
LPCSTR lpszFormat, ...);
Parameter
exp
[di] String dan variabel untuk dikirim ke jendela output atau aplikasi apa pun yang menjebak pesan ini.
category
[di] Jenis peristiwa atau metode yang akan dilaporkan. Lihat Keterangan untuk daftar kategori.
tingkat
[di] Tingkat pelacakan untuk dilaporkan. Lihat Keterangan untuk detailnya.
lpszFormat
[di] String yang diformat untuk dikirim ke perangkat cadangan.
Keterangan
Lihat ATLTRACE2 untuk deskripsi ATLTRACE. ATLTRACE dan ATLTRACE2 memiliki perilaku yang sama, ATLTRACE disertakan untuk kompatibilitas mundur.
ATLTRACE2
Melaporkan peringatan ke perangkat output, seperti jendela debugger, sesuai dengan bendera dan tingkat yang ditunjukkan.
ATLTRACE2(exp);
ATLTRACE2(
DWORD category,
UINT level,
LPCSTR lpszFormat, ...);
Parameter
exp
[di] String untuk dikirim ke jendela output atau aplikasi apa pun yang menjebak pesan ini.
category
[di] Jenis peristiwa atau metode yang akan dilaporkan. Lihat Keterangan untuk daftar kategori.
tingkat
[di] Tingkat pelacakan untuk dilaporkan. Lihat Keterangan untuk detailnya.
lpszFormat
[di] printfString format -style yang digunakan untuk membuat string untuk dikirim ke perangkat cadangan.
Keterangan
Bentuk pendek ATLTRACE2 menulis string ke jendela output debugger. Bentuk kedua ATLTRACE2 juga menulis output ke jendela output debugger, tetapi tunduk pada pengaturan Alat Pelacakan ATL/MFC (lihat Sampel ATLTraceTool). Misalnya, jika Anda mengatur tingkat ke 4 dan Alat Pelacakan ATL/MFC ke tingkat 0, Anda tidak akan melihat pesan. levelnya bisa 0, 1, 2, 3, atau 4. Defaultnya, 0, hanya melaporkan masalah yang paling serius.
Parameter kategori mencantumkan bendera pelacakan yang akan diatur. Bendera ini sesuai dengan jenis metode yang ingin Anda laporkan. Tabel di bawah ini mencantumkan bendera pelacakan yang valid yang dapat Anda gunakan untuk parameter kategori .
Bendera Pelacakan ATL
| Kategori ATL | Deskripsi |
|---|---|
atlTraceGeneral |
Laporan tentang semua aplikasi ATL. Default. |
atlTraceCOM |
Laporan tentang metode COM. |
atlTraceQI |
Laporan tentang panggilan QueryInterface. |
atlTraceRegistrar |
Laporan tentang pendaftaran objek. |
atlTraceRefcount |
Laporan tentang mengubah jumlah referensi. |
atlTraceWindowing |
Laporan tentang metode windows; misalnya, melaporkan ID peta pesan yang tidak valid. |
atlTraceControls |
Laporan tentang kontrol; misalnya, melaporkan ketika kontrol atau jendelanya dihancurkan. |
atlTraceHosting |
Laporan menghosting pesan; misalnya, melaporkan ketika klien dalam kontainer diaktifkan. |
atlTraceDBClient |
Laporan tentang Templat Konsumen OLE DB; misalnya, ketika panggilan ke GetData gagal, output dapat berisi HRESULT. |
atlTraceDBProvider |
Laporan tentang Templat Penyedia OLE DB; misalnya, melaporkan jika pembuatan kolom gagal. |
atlTraceSnapin |
Laporan untuk aplikasi MMC SnapIn. |
atlTraceNotImpl |
Melaporkan bahwa fungsi yang ditunjukkan tidak diimplementasikan. |
atlTraceAllocation |
Melaporkan pesan yang dicetak oleh alat penelusuran kesalahan memori di atldbgmem.h. |
Bendera Pelacakan MFC
| Kategori MFC | Deskripsi |
|---|---|
traceAppMsg |
Tujuan umum, pesan MFC. Selalu disarankan. |
traceDumpContext |
Pesan dari CDumpContext. |
traceWinMsg |
Pesan dari kode penanganan pesan MFC. |
traceMemory |
Pesan dari kode manajemen memori MFC. |
traceCmdRouting |
Pesan dari kode perutean perintah Windows MFC. |
traceHtml |
Pesan dari dukungan dialog DHTML MFC. |
traceSocket |
Pesan dari dukungan soket MFC. |
traceOle |
Pesan dari dukungan OLE MFC. |
traceDatabase |
Pesan dari dukungan database MFC. |
traceInternet |
Pesan dari dukungan Internet MFC. |
Untuk mendeklarasikan kategori pelacakan kustom, deklarasikan instans CTraceCategory global kelas sebagai berikut:
CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);
Nama kategori, MY_CATEGORY dalam contoh ini, adalah nama yang Anda tentukan ke parameter kategori . Parameter pertama adalah nama kategori yang akan muncul di ALAT Pelacakan ATL/MFC. Parameter kedua adalah tingkat pelacakan default. Parameter ini bersifat opsional, dan tingkat pelacakan default adalah 0.
Untuk menggunakan kategori yang ditentukan pengguna:
ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));
Untuk menentukan bahwa Anda ingin memfilter pesan pelacakan, sisipkan definisi untuk makro ini ke Stdafx.h sebelum #include <atlbase.h> pernyataan.
Atau, Anda dapat mengatur filter dalam direktif prapemrosan dalam kotak dialog Halaman Properti. Klik tab Prapemroseduran lalu sisipkan global ke dalam kotak edit Definisi Prapemroseduran .
Atlbase.h berisi definisi default makro ATLTRACE2 dan definisi ini akan digunakan jika Anda tidak menentukan simbol-simbol ini sebelum atlbase.h diproses.
Dalam build rilis, ATLTRACE2 dikompilasi ke (void) 0.
ATLTRACE2 membatasi konten string yang akan dikirim ke perangkat cadangan hingga tidak lebih dari 1023 karakter, setelah pemformatan.
ATLTRACE dan ATLTRACE2 memiliki perilaku yang sama, ATLTRACE disertakan untuk kompatibilitas mundur.
Contoh
int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'
Lihat juga
Macro
Penelusuran Kesalahan dan Pelaporan Kesalahan Fungsi Global