測試篩選處理常式

IFilter測試套件會驗證您的篩選處理常式。 測試套件會藉由呼叫 IFilter 方法，並檢查傳回的值是否符合 IFilter 介面規格;並檢查區塊識別碼是否是唯一且增加的， IFilter 介面會在重新初始化之後一致地運作，而且任何具有無效參數的 IFilter 方法呼叫都會傳回預期的錯誤碼。 測試套件程式也會傾印篩選處理常式篩選的檔案輸出，並檢查登錄中的 IFilter 註冊資訊。

本主題的組織方式如下：

• 命令列調用
  • ifilttst.exe
  • filtdump.exe
  • filtreg.exe
  • ifilttst.ini
• IFilter 測試程式
  • 驗證測試
  • 一致性測試
  • 不正確輸入測試
  • 測試不同的 IFilter 組態
• 確保已註冊的專案已編制索引
  • 範例記錄檔
  • 範例傾印檔案
• 其他資源
• 相關主題

注意

如果正在安裝檔案類型的新篩選處理常式做為現有篩選註冊的取代專案，安裝程式應該儲存目前的註冊，並在卸載新的篩選處理常式時還原它。 沒有鏈結篩選的機制。 因此，新的篩選處理常式會負責複寫舊篩選器的任何必要功能。

Command-Line調用

IFilter測試套件包含三個命令列應用程式： ifilttst.exe、 filtdump.exe和filtreg.exe和初始化檔案， ifilttst.ini。

重要

在 Windows 7 和更新版本中，明確封鎖以 Managed 程式碼撰寫的篩選。 篩選必須以原生程式碼撰寫，因為可能會有常見的語言執行平臺 (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。 下表列出命令列參數。

切換和可能的變數	Description
/i 檔案名	要篩選的輸入檔或目錄。 檔案名可以包含萬用字元 * 和 ? 。
/我	記錄訊息會導向檔案，而不是畫面。 記錄訊息描述執行的個別測試，以及測試的通過/失敗結果。 記錄檔名稱與輸入檔案名相同，但副檔名為 .log。
/d	傾印訊息會導向檔案，而不是畫面。 傾印訊息描述區塊的內容。 區塊結構會在詳細資訊層級為 3 時傾印。 傾印檔案名與輸入檔案名相同，但副檔名為 .dmp。
/-我	停用記錄。 此旗標會 /l 覆寫 參數。
/-D	停用傾印。 此旗標會 /d 覆寫 參數。
/v 整數	詳細等級。 預設值為 3。 0 - 測試只會記錄有關特定 IFilter 介面失敗的訊息。 測試會傾印區塊內容。 1 - 測試會記錄警告訊息，以及層級 0 的警告訊息。 2 - 測試會記錄有關通過的測試以及層級 1 的測試訊息。 3 - 測試會記錄資訊訊息，以及層級 2 的資訊訊息。 此外，測試會傾印區塊的結構。
/t 整數	要啟動的執行緒數目。 預設值是 1。
/r 整數]	以遞迴方式篩選子目錄。 選擇性的整數參數會指定要練習遞迴的深度。 如果未指定整數，或如果整數為 0，則會假設為完整遞迴。 根據預設，遞迴深度為 1。
/c 整數	迴圈的次數。 如果整數為 0，則測試會無限迴圈。 根據預設，測試只會迴圈一次。

注意

您必須在命令列參數與值之間包含空格。

filtdump.exe

filtdump.exe程式會載入指定檔的篩選處理常式，並列印 IFilter DLL 所產生的輸出。 下列範例說明如何叫用filtdump.exe程式。

filtdump filename.ext

Filtdump.exe使用 ILoadFilter：：LoadIFilter 方法來載入適用于指定副檔名的 IFilter DLL，並列印結果。 例如，下列命令會指示filtdump.exe載入副檔名 .smp 的smpfilt.dll篩選處理常式、從 myfile.smp 檔案擷取所有文字和屬性，以及列印結果。

filtdump myfile.smp

filtreg.exe

filtreg.exe程式會檢查登錄中的 IFilter 安裝資訊。 您可以從命令列叫用filtreg.exe程式，方法是輸入其名稱，如下列範例所示。

filtreg

Filtreg.exe藉由列印副檔名和副檔名 的 IFilter DLL 名稱，列舉所有具有關聯篩選處理常式的副檔名。 這是驗證 IFilter正確安裝的簡單方式。

ifilttst.ini

呼叫IFilter：：Init方法，初始化IFilter介面。 IFilter：：Init方法採用下列四個參數：

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

IFilter測試套件ifilttst.exe程式的使用者可以在名為 ifilttst.ini 的檔案中指定這些參數的值。 下表描述ifilttst.ini檔案中指定前三個參數的專案， (輸入參數) 。 如需範例檔案，請參閱 範例ifilttst.ini檔案。

注意

pdwFlags參數沒有資料表專案，因為它是輸出參數;在呼叫 IFilter：：Init方法之前，不需要有任何特殊值。

	進入	描述
Flags	要由 OR 運算子聯結的IFILTER_INIT旗標名稱，以形成IFilter：：Init方法的grfFlags參數。 旗標名稱全都必須是大寫，而且在同一行。
cAttributes	十進位整數，表示 cAttributes 參數的值。
aAttributes	此專案必須以 aAttributes 開頭，而且必須與 區段中的其他 aAttributes 專案不同。 aAttributes專案的法律名稱包括：aAttributes、aAttributes1、aAttributes2等等。 第一個權杖必須是 GUID。 GUID 的格式必須完全如範例ifilttst.ini檔案一節所示 [Test3] 。 第二個標記可以是屬性識別碼 (PID) 由十六進位標記法組成的數位，或是寬字元字串的指標 (lpwstr) 。 您可以使用雙引號括住字串來指定 lpwstr，如範例ifilttst.ini檔案一節所示 [Test6] 。

如果未指定 Flags 和 cAttributes 專案，則預設為 0。 如果您將 cAttributes 設定為 2，您應該指定兩 個 aAttributes 名稱。 [Test5]在範例的 區段中，cAttributes為 1，但未指定aAttributes。 測試接著會呼叫 IFilter：：Init 方法 ，cAttributes 等於 1，而 aAttributes 等於 Null。 這是有用的測試案例，因為它很可能會在 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 實作採用安全程式碼做法。 See "Secure Code Practices for Windows Search" in Implementing Filter Handlers in Windows Search.

驗證測試

驗證測試會逐一執行物件一個區塊，並驗證每個個別區塊和所有傳回碼。 驗證測試會將所有傳回 STAT_CHUNK 結構儲存在清單中。

驗證測試會驗證下列條件：

• STAT_CHUNK。idChunk區塊識別碼必須是唯一且增加的。
• 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 介面，並執行不正確輸入測試。 此測試會逐步執行檔一次進行不正確地呼叫函式，例如當目前的 chuck 包含文字時呼叫 IFilter：：GetValue 方法。 測試會檢查所有傳回碼是否符合 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。

注意

不正確輸入測試會將目前的區塊結構與驗證測試中傳回的區塊結構進行比較，以確定它們完全相同。

測試不同的 IFilter 組態

ifilttst.exe程式會釋放 IFilter 介面並重新系結，這次會使用下一組參數初始化它。 測試會重複迴圈：驗證測試、一致性測試和不正確輸入測試，直到測試ifilttst.ini檔案中指定的所有所需IFilter組態為止。

確保已註冊的專案已編制索引

IFilter的最終測試可確保已正確註冊IFilter，並叫用它來編制您註冊使用專案索引。 您可以使用目錄管理員起始重新編制索引，或使用編目範圍管理員 (CSM) 來設定預設規則，指出您想要索引子編目的 URL。 編制索引完成之後，請使用 Windows 搜尋 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 的區塊。 例如，如果 Flags 專案中未指定IFILTER_INIT_APPLY_INDEX_ATTRIBUTES或IFILTER_INIT_APPLY_OTHER_ATTRIBUTES，而且 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

前九行會描述目前的區塊結構。 GUID 和 PID 會對應至PSGUID_STORAGE/PID_STG_CONTENTS。 這是包含純文字的區塊。 文字位於下列區塊結構中：

10. This is an HTML IFilter test page

下一個區塊從第 11 行開始，有不同的 GUID，對應至 HTML IFilter ，而不同的 PID 則對應至 HTML HREF。 這是由 匯出 HTML IFilter 的內部實值型別屬性。

從第 21 行開始的下一個區塊具有相同的 GUID 和 PID，但其區塊狀態不是 VALUETEXT 。 請注意，這兩個區塊中的文字與第一個區塊的文字相同。 但因為 IFilter 是針對純文字 (三個屬性所設計，HTML HREF 即文字，而 HTML HREF 作為要套用至此片語的值) ，所以結果會以三個不同的區塊發出。

其他資源

• GitHub上提供的IFilterSample程式碼範例示範如何建立 IFilter 基類來實作IFilter介面。
• 如需編制索引程式的概觀，請參閱 編制索引進程。
• 如需檔案類型的概觀，請參閱 檔案類型。
• 若要查詢檔案類型的檔案關聯屬性，請參閱 PerceivedTypes、SystemFileAssociations 和應用程式註冊。

相關主題

開發篩選處理常式

關於 Windows 搜尋中的篩選處理常式

在 Windows 搜尋中建立篩選處理常式的最佳做法

從篩選處理常式傳回屬性

隨附于 Windows 的篩選處理常式

在 Windows 搜尋中實作篩選處理常式

註冊篩選處理常式