フィルター ハンドラーのテスト
IFilter テスト スイートは、フィルター ハンドラーを検証します。 テスト スイートでは、 IFilter メソッドを呼び出し、返された値が IFilter インターフェイス仕様に準拠しているかどうかを確認することで行われます。チャンク識別子が一意で増加していること、再初期化後に IFilter インターフェイスが一貫して動作し、無効なパラメーターを持つ IFilter メソッドが呼び出されると、予期されるエラー コードが返されることを確認します。 テスト スイート プログラムでは、フィルター ハンドラーによってフィルター処理されたファイルの出力もダンプされ、レジストリ内の IFilter 登録情報がチェックされます。
このトピックは次のように整理されています。
Note
ファイルの種類の新しいフィルター ハンドラーが既存のフィルター登録の代わりにインストールされている場合、インストーラーは現在の登録を保存し、新しいフィルター ハンドラーがアンインストールされた場合に復元する必要があります。 フィルターをチェーンするメカニズムはありません。 そのため、新しいフィルター ハンドラーは、古いフィルターの必要な機能をレプリケートする役割を担います。
Command-Line呼び出し
IFilter テスト スイートは、ifilttst.exe、 filtdump.exe、filtreg.exe 、初期化ファイルの 3 つのコマンド ライン アプリケーション ( ifilttst.ini) で構成されます。
重要
Windows 7 以降では、マネージド コードで記述されたフィルターは明示的にブロックされます。 複数のアドインが実行されるプロセスで共通言語ランタイム (CLR) のバージョン管理の問題が発生する可能性があるため、ネイティブ コードでフィルターを記述する必要があります。
ifilttst.exe
ifilttst.exe プログラムは、フィルター ハンドラーを検証するためにいくつかのテストを実行します。 次の例は、コマンド ラインからifilttst.exe プログラムを呼び出す方法を示しています。
ifilttst /i test.htm /l /d /v 1
この例では、次のタスクを実行します。
- ファイルをフィルター処理するようにプログラムに指示test.htm
- ログ メッセージを test.htm.log にリダイレクトします
- ダンプ メッセージを test.htm.dmp にリダイレクトします
- 詳細度を 1 に設定します
上記のコマンドを機能させるには、現在の作業ディレクトリ test.htmに、 、ifilttst.exe、ifilttst.iniの 3 つのファイルが存在する必要があります。 コマンド ライン スイッチを次の表に示します。
| 切り替えと可能な変数 | 説明 |
|---|---|
| /i ファイル名 | フィルター処理する入力ファイルまたはディレクトリ。 ファイル名には、ワイルドカード文字 と ?を*含めることができます。 |
| /L | ログ メッセージは、画面ではなくファイルに送信されます。 ログ メッセージには、実行された個々のテストと、テストの合格/不合格の結果が記述されます。 ログ ファイル名は入力ファイル名と同じですが、拡張子は .log です。 |
| /d | ダンプ メッセージは、画面ではなくファイルに送信されます。 ダンプ メッセージは、チャンクの内容を記述します。 チャンク構造は、詳細レベルが 3 の場合にダンプされます。 ダンプ ファイル名は入力ファイル名と同じですが、拡張子は .dmp です。 |
| /-L | ログ記録を無効にします。 このフラグは、スイッチをオーバーライドします /l 。 |
| /-D | ダンプを無効にします。 このフラグは、スイッチをオーバーライドします /d 。 |
| /v 整数 | 詳細出力レベル。 既定値は 3 です。
|
| /t integer | 起動するスレッドの数。 既定値は 1 です。 |
| /r integer] | サブディレクトリを再帰的にフィルター処理します。 省略可能な整数パラメーターは、再帰を実行する深さを指定します。 整数が指定されていない場合、または整数が 0 の場合は、完全再帰が想定されます。 既定では、再帰の深さは 1 です。 |
| /c integer | ループする回数。 整数が 0 の場合、テストは無限にループします。 既定では、テストは 1 回だけループします。 |
Note
コマンド ライン スイッチと値の間にスペースを含める必要があります。
filtdump.exe
filtdump.exe プログラムは、指定されたドキュメントのフィルター ハンドラーを読み込み、 IFilter DLL によって生成された出力を出力します。 次の例は、filtdump.exe プログラムを呼び出す方法を示しています。
filtdump filename.ext
Filtdump.exeは 、ILoadFilter::LoadIFilter メソッドを使用して、指定したファイル名拡張子に適した IFilter DLL を読み込み、結果を出力します。 たとえば、次のコマンドは、拡張子 .smp のsmpfilt.dll フィルター ハンドラーを読み込み、myfile.smp ファイルからすべてのテキストとプロパティを抽出し、結果を出力するようにfiltdump.exeに指示します。
filtdump myfile.smp
filtreg.exe
filtreg.exe プログラムは、レジストリ内の IFilter インストール情報を検査します。 コマンド ラインからfiltreg.exe プログラムを呼び出すには、次の例のように名前を入力します。
filtreg
Filtreg.exeは、ファイル名拡張子と拡張子の IFilter DLL の名前を印刷することによって、フィルター ハンドラーが関連付けられているすべてのファイル名拡張子を列挙します。 これは、 IFilter の正しいインストールを確認する簡単な方法です。
ifilttst.ini
IFilter インターフェイスは、IFilter::Init メソッドを呼び出すことによって初期化されます。 IFilter::Init メソッドは、次の 4 つのパラメーターを受け取ります。
- grfFlags
- cAttributes
- aAttributes
- pdwFlags
IFilter テスト スイートのifilttst.exe プログラムのユーザーは、これらのパラメーターの値を ifilttst.ini というファイルで指定できます。 次の表では、最初の 3 つのパラメーター (入力パラメーター) を指定するifilttst.ini ファイル内のエントリについて説明します。 サンプル ファイルについては、「 サンプル ifilttst.ini ファイル」を参照してください。
Note
pdwFlags パラメーターは出力パラメーターであるため、テーブル エントリはありません。IFilter::Init メソッドの呼び出しの前に特別な値を指定する必要はありません。
| 入力 | 説明 | |
|---|---|---|
| フラグ | IFilter::Init メソッドの grfFlags パラメーターを形成するために OR 演算子によって結合されるIFILTER_INIT フラグの名前。 フラグ名はすべて大文字で、同じ行に置く必要があります。 | |
| cAttributes | cAttributes パラメーターの値を表す 10 進整数。 | |
| aAttributes | このエントリは aAttributes で始まる必要があり、セクション内の他 の aAttributes エントリとは異なる必要があります。 aAttributes エントリの有効な名前は、aAttributes、aAttributes1、aAttributes2 などです。 最初のトークンは GUID である必要があります。 GUID は、サンプル ifilttst.ini ファイルのセクションに[Test3]示されているとおりに書式設定する必要があります。 2 番目のトークンには、16 進数表記の数値で構成されるプロパティ識別子 (PID) またはワイド文字列 (lpwstr) へのポインターを指定できます。 lpwstr は、サンプル ifilttst.ini ファイルのセクションに示すように、文字列を二重引用符で [Test6] 囲むことで指定できます。 |
Flags エントリと cAttributes エントリが指定されていない場合、既定値は 0 です。 cAttributes を 2 に設定する場合は、2 つの aAttributes 名を指定する必要があります。 サンプルの [Test5] セクションでは、 cAttributes は 1 ですが、 aAttributes は指定されていません。 次に、cAttributes が 1、aAttributes が NULL である IFilter::Init メソッドを呼び出します。 これは、 IFilter::Init メソッドでアクセス違反を引き起こす可能性があるため、便利なテスト ケースです。
ifilttst.exe作業ディレクトリに ifilttst.ini という名前のファイルが見つからない場合は、既定の構成を使用して IFilter::Init オブジェクトを初期化します。 次の例は、既定の構成を示しています。
[default]
grfFlags = IFILTER_INIT_APPLY_INDEX_ATTRIBUTES
cAttributes = 0
サンプル ifilttst.ini ファイル
ifilttst.ini ファイルはセクションで構成され、セクション名は角かっこで囲まれています。 この例では、セクションの名前 [Test1]は 、 [Test2]、などです。 すべてのセクション名は一意である必要があります。 テストでは、最初のセクションから値を読み取り、それらの値を使用して IFilter を初期化します。 その後、すべてのテストは、この IFilter 構成を使用して実行されます。 その後、上記のパラメーターを使用して、 IFilter が解放され、再初期化されます。 プロセスは、すべての構成がテストされるまで繰り返されます。
; 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"
IFilter テスト プロシージャ
IFilter が初期化されると、ifilttst.exe プログラムは IFilter に対して一連のテストを実行します。 IFilter のテスト手順に従うだけでなく、IFilter 実装でセキュリティで保護されたコード プラクティスが採用されていることを確認します。 「Windows Search での フィルター ハンドラーの実装」の「Windows 検索のセキュリティで保護されたコード プラクティス」を参照してください。
検証テスト
検証テストでは、一度に 1 つのチャンクずつオブジェクトをステップ実行し、個々のチャンクとすべてのリターン コードを確認します。 検証テストでは、返されたすべての STAT_CHUNK 構造体が一覧に保存されます。
検証テストでは、次の条件が検証されます。
- STAT_CHUNK。idChunk チャンク ID は一意であり、増加している必要があります。
- STAT_CHUNK。flags パラメーターは、CHUNKSTATE、CHUNK_TEXT、CenabledHUNK_VALUE定数などの認識されたチャンク状態です。
- STAT_CHUNK。breakType パラメーターは、認識される区切り型 (0、1、2、3、4) です。
- IFilter 初期化属性で IFilter が内部値型プロパティを含むチャンクのみを返すように指定する場合、idChunkSource は 0 である必要があります。
- チャンクが派生していない場合は、内部値型プロパティでない場合は、STAT_CHUNK。idChunkSource はSTAT_CHUNKと等しい必要があります。idChunk。
- IFilter::GetChunk は、S_OKまたはその他の許容される戻り値 (FILTER_E_END_OF_CHUNKS、FILTER_E_LINK_UNAVAILABLEなど) を返します。
- チャンクにテキストが含まれている場合、 IFilter::GetText はS_OK、FILTER_S_LAST_TEXT、またはFILTER_E_NO_MORE_TEXTを返します。
- IFilter::GetText がFILTER_S_LAST_TEXTを返す場合、IFilter::GetText の次の呼び出しはFILTER_E_NO_MORE_TEXTを返します。
- チャンクに値が含まれている場合、 IFilter::GetValue はS_OKまたはFILTER_E_NO_MORE_VALUESを返します。
整合性テスト
ifilttxt.exe プログラムは、検証テストと同じパラメーターを使用して IFilter インターフェイスを再初期化し、整合性テストを実行します。 IFilter 実装が IFILTER_INIT IFILTER_INIT_INDEXING_ONLY フラグを使用して初期化されている場合、テストは IFilter インターフェイスを解放し、IFilter::Init メソッドを別の呼び出しを行う前に再バインドします。
整合性テストでは、次の条件が検証されます。
- IFilter::GetChunk メソッドによって返される各STAT_CHUNK構造体は、検証テストで返される対応するSTAT_CHUNKと同じです。
- IFilter::GetChunk は、S_OKまたはその他の許容される戻り値 (FILTER_E_END_OF_CHUNKS、FILTER_E_LINK_UNAVAILABLEなど) を返します。
入力テストが無効です
ifilttst.exe プログラムは、同じパラメーターを使用して IFilter インターフェイスを再初期化し、無効な入力テストを実行します。 このテストでは、現在のチャックにテキストが含まれている場合に IFilter::GetValue メソッドを呼び出すなど、関数呼び出しを誤って行う一度に 1 つのチャンクずつドキュメントをステップ実行します。 このテストでは、すべてのリターン コードが IFilter 仕様に準拠しているのを確認します。
無効な入力テストでは、次の条件が検証されます。
- 現在のチャンクにテキストが含まれている場合、 IFilter::GetValue はFILTER_E_NO_VALUESを返し、 IFilter::GetText の呼び出しは成功します。
- 現在のチャンクに値が含まれている場合、 IFilter::GetText はFILTER_E_NO_TEXTを返し、 IFilter::GetValue の呼び出しは成功します。
- IFilter::GetText に対する前回の呼び出しがFILTER_E_NO_MORE_TEXT返された場合、IFilter::GetText を連続して呼び出すと、FILTER_E_NO_MORE_TEXTが返されます。
- IFilter::GetValue に対する前回の呼び出しがFILTER_E_NO_MORE_VALUES返された場合、IFilter::GetValue を連続して呼び出すと、FILTER_E_NO_MORE_VALUESが返されます。
- IFilter::GetChunk に対する前回の呼び出しがFILTER_E_END_OF_CHUNKS返された場合、IFilter::GetChunk への連続する呼び出しはFILTER_E_END_OF_CHUNKSを返します。
Note
無効な入力テストでは、現在のチャンク構造と検証テストで返されたものを比較して、それらが同一であることを確認します。
さまざまな IFilter 構成のテスト
ifilttst.exe プログラムは IFilter インターフェイスを解放し、再バインドします。今度は、次のパラメーター セットを使用して初期化します。 このテストでは、検証テスト、整合性テスト、無効な入力テストのサイクルが繰り返され、ファイルで指定されているすべての必要な IFilter 構成 ifilttst.ini テストされます。
登録済みアイテムのインデックス作成の確認
IFilter の最後のテストでは、IFilter が正しく登録されていること、および IFilter を使用するために登録した項目のインデックスを作成するために呼び出されることが確認されます。 カタログ マネージャーを使用してインデックスの再作成を開始するか、クロール スコープ マネージャー (CSM) を使用して、インデクサーがクロールする URL を示す既定のルールを設定できます。 インデックス作成が完了したら、Windows Search UI を使用して、アイテムのコンテンツまたはプロパティ内の文字列を検索します。 インデックスが作成されたアイテムは、検索結果に表示されます。
インデックスの再作成の詳細については、「 カタログ マネージャーの使用 」および 「クロール スコープ マネージャーの使用」を参照してください。 ReindexMatchingUrls コード サンプルでは、インデックスを再作成するファイルとその方法を指定する方法を示します。 CrawlScopeCommandLine コード サンプルは、クロール スコープ マネージャー (CSM) インデックス作成操作のコマンド ライン オプションを定義する方法を示しています。 どちらのコード サンプルも GitHub で入手できます。
サンプル ログ ファイル
要求に応じて、Ifilttst.exe プログラムは、実行中に実行される手順の説明を含むログを生成できます。 次の例は、ログ ファイルからの抜粋であり、詳細度は可能な限り高い値 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.
最初の行は、ifilttst.ini ファイルから新しい構成が読み込まれたことを示す情報メッセージです。 行 (3) は、現在の構成が読み取られたifilttst.ini ファイル内のセクション名を示します。 行 (4) から (7) には 、IFilter::Init へのパラメーターが一覧表示されます。 以降 INFO の行は、 IFilter のバインドと検証テストの開始に関する情報メッセージです。 で始まる PASS 行は、合格した特定のテストに関するメッセージです。
次のログ例の行は警告です。 警告は、問題のある IFilter の動作に注意を呼び出しますが、有効です。 この警告は、 IFilter::GetChunk メソッドがテキストを含まないテキスト チャンクを返したことを示します。
WARNING-First call to GetText() returned FILTER_E_NO_MORE_TEXT.
次のエラー メッセージ例は、 IFilter が要求されなかったチャンクを出力したことを示しています。
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
この例のエラー メッセージの場合、 IFilter は PID が の 0x5チャンクを出力しました。 ifilttst.iniのセクション [Test1] の検査では、 IFilter がこの PID でチャンクを出力しないように構成されたことが示されます。 たとえば、IFILTER_INIT_APPLY_INDEX_ATTRIBUTESもIFILTER_INIT_APPLY_OTHER_ATTRIBUTESも Flags エントリで指定されておらず、 cAttributes が 0 の場合、 IFilter は PID が の 0x13 チャンクのみを出力し、PID_STG_CONTENTSに対応します。
サンプル ダンプ ファイル
要求に応じて、Ifilttst.exe プログラムは、検出されたチャンクとその内容を含むダンプを生成できます。 次の例は、このようなダンプ ファイルからの抜粋です。
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
最初の 9 行は、現在のチャンク構造を表します。 GUID と PID は、PSGUID_STORAGE/PID_STG_CONTENTSに対応します。 これは、プレーン テキストを含むチャンクです。 テキストは次のチャンク構造です。
10. This is an HTML IFilter test page
11 行目以降の次のチャンクには、 に対応する別の GUID と、HTML HREF に HTML IFilter対応する別の PID があります。 これは、 によって HTML IFilterエクスポートされる内部値型プロパティです。
21 行目以降の次のチャンクの GUID と PID は同じですが、チャンクの状態は VALUE ではなく TEXTです。 これら最後の 2 つのチャンクのテキストは、最初のチャンクのテキストと同じであることに注意してください。 ただし、IFilter は、このフレーズに適用される 3 つの属性 (プレーン テキスト、テキストとしての HTML HREF、値としての HTML HREF) 用に設計されているため、結果は 3 つの個別のチャンクで出力されます。
その他のリソース
- GitHub で入手できる IFilterSample コード サンプルは、IFilter インターフェイスを実装するための IFilter 基本クラスを作成する方法を示しています。
- インデックス作成プロセスの概要については、「インデックス作成 プロセス」を参照してください。
- ファイルの種類の概要については、「ファイルの 種類」を参照してください。
- ファイルの種類のファイル関連付け属性を照会するには、「 PerceivedTypes、SystemFileAssociations、およびアプリケーション登録」を参照してください。
関連トピック
Windows Search のフィルター ハンドラーについて
Windows 検索でフィルター ハンドラーを作成するためのベスト プラクティス
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示