Menguji penangan filter

Suite pengujian IFilter memvalidasi pengelola filter Anda. Rangkaian pengujian melakukannya dengan: memanggil metodeIFilterdan memeriksa nilai yang dikembalikan untuk kepatuhan dengan spesifikasi antarmuka IFilter; dan memeriksa bahwa pengidentifikasi gugus unik dan meningkat, bahwa antarmuka IFilter berperilaku konsisten setelah inisialisasi ulang, dan bahwa setiap panggilan metode IFilter dengan parameter yang tidak valid mengembalikan kode kesalahan yang diharapkan. Program rangkaian pengujian juga membuang output file yang difilter oleh handler filter, dan memeriksa informasi pendaftaran IFilter di registri.

Topik ini diatur sebagai berikut:

Nota

Jika handler filter baru untuk jenis file sedang diinstal sebagai pengganti pendaftaran filter yang ada, alat penginstal harus menyimpan pendaftaran saat ini dan memulihkannya jika handler filter baru dihapus instalasinya. Tidak ada mekanisme untuk menautkan filter. Oleh karena itu, handler filter baru bertanggung jawab untuk mereplikasi fungsionalitas filter lama yang diperlukan.

Pemanggilan baris perintah

Rangkaian pengujianIFilterterdiri dari tiga aplikasi baris perintah - ifilttst.exe, filtdump.exe, dan filtreg.exe dan file inisialisasi, ifilttst.ini.

Penting

Di Windows 7 dan yang lebih baru, filter yang ditulis dalam kode terkelola secara eksplisit diblokir. Filter HARUS ditulis dalam kode asli karena potensi masalah penerapan versi runtime bahasa umum (CLR) dengan proses yang dijalankan beberapa add-in.

Ifilttst.exe

Program ifilttst.exe menjalankan beberapa pengujian untuk memvalidasi handler filter. Contoh berikut mengilustrasikan cara memanggil program ifilttst.exe dari baris perintah:

ifilttst /i test.htm /l /d /v 1

Contoh melakukan tugas-tugas berikut:

  • Mengarahkan program untuk memfilter file test.htm
  • Mengalihkan pesan log ke test.htm.log
  • Mengalihkan pesan dump ke file test.htm.dmp
  • Mengatur verbositas ke 1

Agar perintah sebelumnya berfungsi, tiga file harus terletak di direktori kerja saat ini: test.htm, ifilttst.exe, dan ifilttst.ini. Sakelar baris perintah tercantum dalam tabel berikut.

Beralih dan kemungkinan variabel Deskripsi
nama file /i File input atau direktori yang akan difilter. Nama file dapat berisi karakter wildcard * dan ?.
/l Pesan log diarahkan ke file alih-alih layar. Pesan log menjelaskan pengujian individual yang dilakukan dan hasil lulus/gagal dari pengujian. Nama file log sama dengan nama file input tetapi dengan ekstensi .log.
/d Pesan cadangan diarahkan ke file alih-alih layar. Pesan dump menjelaskan isi potongan. Struktur gugus dibuang ketika tingkat verbositas adalah 3. Nama file cadangan sama dengan nama file input tetapi dengan ekstensi .dmp.
/-l Nonaktifkan pengelogan. Bendera ini mengambil alih sakelar /l.
/-d Nonaktifkan pembuangan. Bendera ini mengambil alih sakelar /d.
bilangan bulat /v Tingkat verbositas. Defaultnya adalah 3.
  • 0 - Log pengujian hanya mencatat pesan mengenai kegagalan antarmuka IFilter tertentu. Pengujian membuang isi potongan.
  • 1 - Log pengujian mencatat pesan peringatan serta pesan untuk tingkat 0.
  • 2 - Pengujian mencatat pesan mengenai tes yang lulus serta untuk tingkat 1.
  • 3 - Pengujian mencatat pesan-pesan informatif serta pesan-pesan untuk tingkat 2. Selain itu, pengujian membuang struktur potongan.
bilangan bulat /t Jumlah utas yang akan diluncurkan. Defaultnya adalah 1.
bilangan bulat /r] Secara rekursif memfilter subdirektori. Parameter bilangan bulat opsional menentukan kedalaman untuk menjalankan rekursi. Jika tidak ada bilangan bulat yang ditentukan, atau jika bilangan bulat adalah 0, rekursi penuh diasumsikan. Secara default, kedalaman rekursi adalah 1.
/c bilangan bulat Jumlah kali pengulangan. Jika bilangan bulat adalah 0, pengujian akan mengulang tanpa batas. Secara default, pengujian hanya mengulang sekali.

Nota

Anda harus menyertakan spasi antara opsi baris perintah dan nilai.

Filtdump.exe

Program filtdump.exe memuat handler filter untuk dokumen tertentu dan mencetak output yang dihasilkan oleh IFilter DLL. Contoh berikut mengilustrasikan cara memanggil program filtdump.exe.

filtdump filename.ext

Filtdump.exe menggunakan metode ILoadFilter::LoadIFilter untuk memuat IFilter DLL yang sesuai untuk ekstensi nama file yang ditentukan dan mencetak hasilnya. Misalnya, perintah berikut menginstruksikan filtdump.exe untuk memuat handler filter smpfilt.dll untuk ekstensi .smp, mengekstrak semua teks dan properti dari file myfile.smp, dan mencetak hasilnya.

filtdump myfile.smp

Filtreg.exe

Program filtreg.exe memeriksa informasi penginstalan IFilter di registri. Anda memanggil program filtreg.exe dari baris perintah dengan mengetik namanya, seperti dalam contoh berikut.

filtreg

Filtreg.exe menghitung semua ekstensi nama file yang memiliki handler filter yang terkait dengannya dengan mencetak ekstensi nama file dan nama IFilter DLL untuk ekstensi. Ini adalah cara sederhana untuk memverifikasi penginstalan IFilteryang benar.

Ifilttst.ini

AntarmukaIFilterdiinisialisasi dengan memanggil metode IFilter::Init. Metode IFilter::Init mengambil empat parameter berikut:

  1. grfFlags
  2. cAttributes
  3. aAttributes
  4. pdwFlags

Pengguna program ifilttst.exe dari rangkaian pengujian IFilter dapat menentukan nilai untuk parameter ini dalam file yang disebut ifilttst.ini. Tabel berikut menjelaskan entri dalam file ifilttst.ini yang menentukan tiga parameter pertama (parameter input). Untuk file sampel, lihat Sampel ifilttst.ini File.

Nota

Tidak ada entri tabel untuk parameter pdwFlags karena ini adalah parameter output; tidak perlu memiliki nilai khusus sebelum panggilan ke metode IFilter::Init.

  Pintu Masuk Deskripsi
Bendera Nama-nama bendera IFILTER_INIT yang akan digabungkan dengan operator OR untuk membentuk parameter grfFlags dari metode IFilter::Init. Nama bendera semuanya harus huruf besar, dan pada baris yang sama.
cAttributes Bilangan bulat desimal yang mewakili nilai parameter cAttributes.
aAttributes Entri ini harus dimulai dengan aAttributes dan harus berbeda dari entri aAttributes lainnya di dalam bagian. Nama resmi untuk entri aAttributes adalah: aAttributes, aAttributes1, aAttributes2, dan sebagainya. Token pertama harus berupa GUID. GUID harus diformat persis seperti yang diilustrasikan di bagian [Test3] dari Sampel File ifilttst.ini. Token kedua dapat berupa pengidentifikasi properti (PID) yang terdiri dari angka dalam notasi heksadesimal, atau penunjuk ke string karakter lebar (lpwstr). lpwstr dapat ditentukan dengan mengapit string dalam tanda kutip ganda, sebagaimana diilustrasikan dalam bagian [Test6] dari File Sample ifilttst.ini.

Jika Flags dan cAttributes entri tidak ditentukan, maka nilai default mereka adalah 0. Jika Anda mengatur cAttributes sama dengan 2, Anda harus menentukan dua nama aAttributes. Pada bagian sampel [Test5], cAttributes adalah 1, tetapi tidak ada aAttributes yang telah ditentukan. Pengujian kemudian memanggil metode IFilter::Init dengan cAttributes sama dengan 1 dan aAttributes sama dengan NULL. Ini adalah kasus pengujian yang berguna karena kemungkinan menyebabkan pelanggaran akses dalam metode IFilter::Init.

Jika ifilttst.exe tidak dapat menemukan file bernama ifilttst.ini di direktori kerja, konfigurasi default digunakan untuk menginisialisasi objek IFilter::Init. Contoh berikut mengilustrasikan konfigurasi default.

[default]
            grfFlags = IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
            cAttributes = 0

Contoh file ifilttst.ini

File ifilttst.ini diatur ke dalam bagian-bagian, dengan nama setiap bagian diapit tanda kurung siku. Dalam contoh, bagian diberi nama [Test1], [Test2], dan sebagainya. Semua nama bagian harus unik. Pengujian membaca nilai dari bagian pertama dan menginisialisasi IFilter dengan nilai tersebut. Kemudian semua pengujian dijalankan menggunakan konfigurasi IFilter ini. Kemudian IFilter dirilis dan diinisialisasi ulang, menggunakan parameter yang tercantum di atas. Proses ini diulang hingga semua konfigurasi diuji.

; Only extract text from the object
            [Test1]
            Flags =
            cAttributes = 0

            // Get all attributes (text-type and internal value-type properties.
            [Test2]
            Flags = IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
            cAttributes = 0

            // This also extracts just text from the object (the GUID is PSGUID_STORAGE, and the propid is
            // PID_STG_CONTENTS).
            [Test3]
            Flags = IFILTER_INIT_CANON_PARAGRAPHS IFILTER_INIT_HARD_LINE_BREAKS
            cAttributes = 1
            aAttributes1 = b725f130-47ef-101a-a5f1-02608c9eebac 13

            // Only extract requested attribute from the html object (the GUID corresponds to the HTML IFilter.
            [Test4]
            Flags = IFILTER_INIT_CANON_HYPHENS IFILTER_INIT_CANON_SPACES
            cAttributes = 1
            aAttributes1 = 70eb7a10-55d9-11cf-b75b-00aa0051fe20 2

            // Question: what happens if cAttributes is nonzero, but aAttributes is empty?
            [Test5]
            Flags = IFILTER_INIT_CANON_SPACES IFILTER_INIT_APPLY_INDEX_ATTRIBUTES IFILTER_INIT_APPLY_OTHER_ATTRIBUTES
            cAttributes = 1

            // Here is an attribute with a lpwstr instead of a propid (the lpwstr is enclosed in quotes).
            // The GUID corresponds to the meta tag clsid for the HTML IFilter.
            [Test6]
            Flags =
            cAttributes = 1
            aAttributes1 = D1B5D3F0-C0B3-11CF-9A92-00A0C908DBF1 "GENERATOR"

Prosedur pengujian IFilter

Setelah IFilter diinisialisasi, program ifilttst.exe melakukan serangkaian tes pada IFilter. Selain mengikuti prosedur pengujian IFilter, pastikan implementasi IFilter Anda menggunakan praktik kode yang aman. Lihat "Praktik Kode Aman untuk Pencarian Windows" di Penerapan Pengelola Filter dalam Pencarian Windows.

Uji validasi

Pengujian validasi melangkah melalui objek satu gugus sekaligus, memverifikasi setiap potongan individu dan semua kode pengembalian. Pengujian validasi menyimpan semua struktur STAT_CHUNK yang dikembalikan dalam daftar.

Pengujian validasi memverifikasi kondisi berikut:

  • STAT_CHUNK.idChunk ID gugus harus unik dan meningkat.
  • STAT_CHUNK.parameter bendera adalah status gugus yang dikenali, seperti CHUNKSTATE, CHUNK_TEXT, atau konstanta CenabledHUNK_VALUE.
  • STAT_CHUNK.parameter breakType adalah jenis jeda yang dikenali (0, 1, 2, 3, 4).
  • Jika atribut inisialisasiIFiltermenentukan bahwa IFilter harus mengembalikan hanya gugus yang berisi properti jenis nilai internal, maka idChunkSource harus sama dengan 0.
  • Jika gugus tidak diturunkan yaitu, jika bukan properti jenis nilai internal, maka STAT_CHUNK. idChunkSource harus sama dengan STAT_CHUNK.idChunk.
  • IFilter::GetChunk mengembalikan S_OK atau nilai pengembalian lain yang dapat diterima, seperti FILTER_E_END_OF_CHUNKS, FILTER_E_LINK_UNAVAILABLE, dan sebagainya.
  • Jika gugus berisi teks, IFilter::GetText mengembalikan S_OK, FILTER_S_LAST_TEXT, atau FILTER_E_NO_MORE_TEXT.
  • Jika IFilter::GetText mengembalikan FILTER_S_LAST_TEXT, panggilan berikutnya ke IFilter::GetText mengembalikan FILTER_E_NO_MORE_TEXT.
  • Jika gugus berisi nilai, IFilter::GetValue mengembalikan S_OK atau FILTER_E_NO_MORE_VALUES.

Uji konsistensi

Program ifilttxt.exe menginisialisasi ulang antarmukaIFilterdengan parameter yang sama seperti dalam pengujian validasi dan melakukan pengujian konsistensi. Jika implementasi IFilter telah diinisialisasi dengan bendera IFILTER_INIT IFILTER_INIT_INDEXING_ONLY, pengujian merilis antarmuka IFilter dan mengikatnya kembali sebelum melakukan panggilan lain ke metode IFilter::Init.

Pengujian konsistensi memverifikasi kondisi berikut:

  • Setiap struktur STAT_CHUNK yang dikembalikan oleh metode IFilter::GetChunk identik dengan STAT_CHUNK yang sesuai yang dikembalikan dalam pengujian validasi.
  • IFilter::GetChunk mengembalikan S_OK atau nilai pengembalian lain yang dapat diterima, seperti FILTER_E_END_OF_CHUNKS, FILTER_E_LINK_UNAVAILABLE, dan sebagainya.

Uji input tidak valid

Program ifilttst.exe menginisialisasi ulang antarmukaIFilterdengan parameter yang sama, dan melakukan pengujian input yang tidak valid. Pengujian ini melangkah melalui dokumen satu bagian pada satu waktu dengan melakukan panggilan fungsi yang salah, seperti memanggil metode IFilter::GetValue ketika bagian saat ini berisi teks. Pengujian memeriksa semua kode pengembalian untuk kepatuhan dengan spesifikasi IFilter.

Pengujian input yang tidak valid memverifikasi kondisi berikut:

  • Jika potongan saat ini berisi teks, IFilter::GetValue mengembalikan FILTER_E_NO_VALUES, dan panggilan ke IFilter::GetText berhasil.
  • Jika gugus saat ini berisi nilai, IFilter::GetText mengembalikan FILTER_E_NO_TEXT, dan panggilan ke IFilter::GetValue berhasil.
  • Jika panggilan sebelumnya ke IFilter::GetText mengembalikan FILTER_E_NO_MORE_TEXT, panggilan berturut-turut ke IFilter::GetText mengembalikan FILTER_E_NO_MORE_TEXT.
  • Jika panggilan sebelumnya ke IFilter::GetValue mengembalikan FILTER_E_NO_MORE_VALUES, panggilan berturut-turut ke IFilter::GetValue mengembalikan FILTER_E_NO_MORE_VALUES.
  • Jika panggilan sebelumnya ke IFilter::GetChunk mengembalikan FILTER_E_END_OF_CHUNKS, maka panggilan berturut-turut ke IFilter::GetChunk juga mengembalikan FILTER_E_END_OF_CHUNKS.

Nota

Pengujian input yang tidak valid membandingkan struktur gugus saat ini dengan yang dikembalikan dalam pengujian validasi untuk memastikan struktur tersebut identik.

Menguji konfigurasi IFilter yang berbeda

Program ifilttst.exe merilis antarmuka dan melakukan pengikatan ulang, kali ini menginisialisasi dengan serangkaian parameter berikutnya. Pengujian mengulangi siklus: pengujian validasi, pengujian konsistensi, dan pengujian input yang tidak valid, hingga semua konfigurasi IFilter yang diinginkan yang ditentukan dalam file ifilttst.ini telah diuji.

Memastikan item terdaftar diindeks

Pengujian akhir IFilter memastikan bahwa IFilter Anda terdaftar dengan benar dan dipanggil untuk mengindeks item yang Anda registrasikan untuk penggunaannya. Anda dapat menggunakan Pengelola Katalog untuk memulai pengindeksan ulang, atau menggunakan Crawl Scope Manager (CSM) untuk menyiapkan aturan default yang menunjukkan URL yang Anda inginkan untuk dirayapi oleh pengindeks. Setelah pengindeksan selesai, gunakan UI Windows Search untuk mencari string di konten atau properti item. Jika item diindeks, item akan muncul di hasil pencarian.

Untuk informasi lebih lanjut tentang pengindeksan ulang, lihat Menggunakan Pengelola Katalog dan Menggunakan Pengelola Lingkup Crawl. Sampel kode ReindexMatchingUrls menunjukkan cara untuk menentukan file mana yang akan diindeks ulang dan caranya. Sampel kode CrawlScopeCommandLine menunjukkan cara menentukan opsi baris perintah untuk operasi pengindeksan Crawl Scope Manager (CSM). Kedua sampel kode tersedia di GitHub.

Contoh file log

Berdasarkan permintaan, program Ifilttst.exe dapat menghasilkan log yang berisi deskripsi langkah-langkah yang diperlukan selama eksekusi. Contoh berikut adalah kutipan dari file log, dengan verbositas diatur ke nilai tertinggi yang mungkin 3.

            1. INFO----**** New configuration ****
            2.
            3. Section name : Test2
            4. grfFlags     : 63
            5. cAttributes  : 0
            6. aAttributes  : NONE
            7. pdwFlags     : 0
            8.
            9. INFO----Successfully bound filter.
            10.
            11. PASS----Init() returned a valid value for pdwFlags.
            12.
            13. INFO----Successfully initialized filter.
            14.
            15. INFO----Performing validation test. In this part of the test, the chunks structures
            16.         returned by the IFilter are checked for correctness, and the return values
            17.         of the IFilter calls are checked.
            18.
            19. PASS----GetChunk() succeeded.
            20.
            21. PASS----The current chunk has a legal value for the flags field.

Baris pertama adalah pesan informasi, menunjukkan bahwa konfigurasi baru telah dimuat dari file ifilttst.ini. Baris (3) menunjukkan nama bagian dalam file ifilttst.ini tempat konfigurasi saat ini telah dibaca. Baris (4) hingga (7) mencantumkan parameter ke IFilter::Init. Baris yang diawali dengan INFO adalah pesan informasi tentang pengikatan IFilter dan awal pengujian validasi. Baris yang dimulai dengan PASS adalah pesan mengenai pengujian tertentu yang telah lulus.

Baris dalam contoh log berikut adalah peringatan. Peringatan menarik perhatian pada perilaku IFilter yang bermasalah, meskipun legal. Peringatan ini menunjukkan bahwa metode IFilter::GetChunk telah mengembalikan potongan teks yang tidak berisi teks.

WARNING-First call to GetText() returned FILTER_E_NO_MORE_TEXT.

Contoh pesan kesalahan berikut menunjukkan bahwa IFilter mengeluarkan potongan yang tidak diminta.

            ERROR---The IFilter has emitted a chunk which it was not requested to emit.
            Check the initialization parameters in section Test1 of the initialization file.
            INFO----Current chunk propid : 0x5

Dalam kasus pesan kesalahan contoh ini, IFilter mengeluarkan potongan dengan PID 0x5. Inspeksi bagian [Test1] di ifilttst.ini akan menunjukkan bahwa IFilter dikonfigurasi untuk tidak mengeluarkan gugus dengan PID ini. Misalnya, jika IFILTER_INIT_APPLY_INDEX_ATTRIBUTES atau IFILTER_INIT_APPLY_OTHER_ATTRIBUTES tidak ditentukan dalam entri Bendera dan jika cAttributes adalah 0, maka IFilter hanya akan memancarkan gugus dengan PID 0x13 dan sesuai dengan PID_STG_CONTENTS.

File cadangan sampel

Berdasarkan permintaan, program Ifilttst.exe dapat menghasilkan dump yang berisi gugus yang ditemukan berikut kontennya. Contoh berikut adalah kutipan dari file cadangan tersebut.

                1. Chunk ID: ........... 2
                2. Chunk Break Type: ... END OF SENTENCE
                3. Chunk State: ........ TEXT
                4. Chunk Locale: ....... 0x411
                5. Chunk Source ID: .... 2
                6. Chunk Start Source .. 0x0
                7. Chunk Length Source . 0x0
                8. GUID ................ b725f130-47ef-101a-a5f1-02608c9eebac
                9. Property ID ......... 0x13

                10. This is a HTML IFilter test page

                11. Chunk ID: ........... 3
                12. Chunk Break Type: ... END OF SENTENCE
                13. Chunk State: ........ TEXT
                14. Chunk Locale: ....... 0x411
                15. Chunk Source ID: .... 2
                16. Chunk Start Source .. 0x0
                17. Chunk Length Source . 0x0
                18. GUID ................ f29f85e0-4ff9-1068-ab91-08002b27b3d9
                19. Property ID ......... 0x2

                20. This is a HTML IFilter test page

                21. Chunk ID: ........... 4
                22. Chunk Break Type: ... END OF SENTENCE
                23. Chunk State: ........ VALUE
                24. Chunk Locale: ....... 0x411
                25. Chunk Source ID: .... 2
                26. Chunk Start Source .. 0x0
                27. Chunk Length Source . 0x0
                28. GUID ................ f29f85e0-4ff9-1068-ab91-08002b27b3d9
                29. Property ID ......... 0x2

                30. This is an HTML IFilter test page

Sembilan baris pertama menjelaskan struktur gugus saat ini. GUID dan PID itu berkaitan dengan PSGUID_STORAGE / PID_STG_CONTENTS. Ini adalah bagian yang berisi teks biasa. Teks berada dalam struktur gugus berikut:

10. This is an HTML IFilter test page

Gugus berikutnya, mulai dari baris 11, memiliki GUID yang berbeda, sesuai dengan HTML IFilter, dan PID yang berbeda, sesuai dengan HTML HREF. Ini adalah properti tipe nilai internal yang diekspor oleh HTML IFilter.

Gugus berikutnya, mulai dari baris 21, memiliki GUID dan PID yang sama, tetapi status gugusnya VALUE alih-alih TEXT. Perhatikan bahwa teks dalam dua gugus terakhir ini sama dengan untuk potongan pertama. Tetapi karena IFilter dirancang untuk tiga atribut (teks biasa, HTML HREF sebagai teks, dan HTML HREF sebagai nilai) untuk diterapkan ke frasa ini, hasilnya dipancarkan dalam tiga gugus terpisah.

Sumber daya tambahan

Mengembangkan handler filter

Tentang Penanganan Filter di Windows Search

Praktik Terbaik untuk Membuat Handler Filter di Windows Search

Mengembalikan Properti dari Handler Filter

Pengendali Filter yang Disertakan dengan Windows

Menerapkan Handler Filter di Windows Search

Mendaftarkan Pengendali Filter

  • Terakhir diperbarui pada