Creating Custom Search Filters

Microsoft Document Explorer, which is the Help viewer that is included with Visual Studio 2008, features a new way to filter search results. The user interface (UI) for Search lets users filter their searches by technology, language, and content type. This topic will discuss how you can add custom search filters to the UI.

Search Filter Implementation

In Document Explorer, users can choose how search results are returned by selecting check boxes next to the languages, technologies, and content types they want. Each of these filters is described by an .xml file that is located in a common folder on the local hard disk. Also, the registry must contain a reference to the file.

Custom Search Filter XML File

The filter .xml files provide information that is used by the Help search engine, such as the name of the filter as it will appear in the Search UI and a filter string that will be matched against the attributes of returned documents.

In each .xml file, the FilterAttribute element and its child element, FilterValue, encapsulate all the information that is used by the Help engine to process a search according to the filter. The FilterAttribute element contains its ID and the string that is used to identify the filter category in the UI. The FilterValue element contains its ID and the string that is used to identify the filter itself in the UI. The FilterValue element also encapsulates a LocalFilterString element, which contains document attributes that are matched as part of the search.

Creating, Installing, and Configuring a Custom Search Filter

You can create your own search filters by customizing the code shown in the example below, replacing the values in the FilterAttribute and FilterValue elements as needed.

Custom filter .xml files must be installed in a common folder and must be registered in the registry. At run time, the Help engine looks in the registry to determine which custom filters are installed.

By default, custom filter .xml files are installed in \Program Files\Common Files\Microsoft Shared\Visual Studio Help Data\9.0\Filters\1033\.

To enable a custom filter, you must create a registry entry that the Help engine can reference when it enumerates available filters. Create this registry entry in \HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\9.0\Help\VisibleFilters\. The name of the registry key must be the same as your .xml file name but without the extension. The key must have a DWORD value of 0x00000001.

Example

The following example shows the XML for a search filter that is installed with the Visual Studio SDK. The filter category is "Technology", and the filter name is " Visual Studio 2008."

<?xml version="1.0" encoding="utf-8"?>
<SearchFilter xmlns="https://schemas.microsoft.com/VisualStudio/2004/08/Help/SearchFilter" Version="0.1.0.0">
    <FilterAttribute>
        <Id>Technology</Id>
        <Name _locID="name.1">Technology</Name>
        <FilterValue>
         <Id>VisualStudioIDE</Id>
         <Name _locID="name.2">Visual Studio 2005</Name>
         <Meaning>
            <LocalFilterString>
            ("DocSet"="Visual Studio" OR
            "DocSet"="Visual Source Safe" OR 
            "tnDocSet"="vbnetkb" OR
            "tnDocSet"="vcsharpnetkb" OR
            "tnDocSet"="vcnetkb" OR
            "tnDocSet"="vjsharpnetkb" OR
            "tnDocSet"="vstudionetkb" OR
            "tnDocSet"="ssafe")
            </LocalFilterString>
            <TocInclude></TocInclude>
            <OnlineFilterString>
            <![CDATA[
               <StringTest Name="ExtendedProperty" Operator="Equals"
                 Value="ms0GXJ3N" ExtendedProperty="MSCategory"/>
               ]]>
             </OnlineFilterString>
         </Meaning>
      </FilterValue>
   </FilterAttribute>
</SearchFilter>