Extending VS2005 Help

How to add your own search filters into the Visual Studio 2005 search.

by Rob Chandler, MS Help MVP

Published: 06-Sept-2006

1. Introduction

Visual Studio 2005 introduced a new kind of VS/MSDN documentation search. Three filter categories (Language, Technology and Content Type) each contain a drop down list of filters (checkboxes). This filters are OR'd together, so for example if Language checkboxes "C#" and "Visual Basic" are checked then your search results will show hits for both C# and Visual Basic docs. When you hit the search button a search filter is created using the three filter categories like this: (Language OR Technology) AND Content Type.

Notice that if all filters in a categories are unchecked then this is effectively the same as checking them all.

Also checkout the various DExplore search options via the "Tools > Options" menu.

Max Number of Search Results

As with all prior version of DExplore the maximum number of search results for a local search is 500 hits. Microsoft have worked hard to make sure the most relevant hits are always displayed first in the list of results.

Search Filter Vs TOC/Index Filter

Note that in past versions of Visual Studio there was simply one filter that effected everything (TOC/Index/Search). In VS 2005 the search filter is completely independent of the TOC / Index filter selection.

Integrating your own filters into VS 2005 Search

Intro over. Down to business.

2. Customizing VS 2005 Search

The 3rd release of VS 2005 SDK is suppose to ship with a document describing how to customize search filters to VS 2005. This SDK will be titled something like "Visual Studio 2005 SDK - v3 Sept 2006" and be available from the usual place (see below) . At the time of writing "Visual Studio 2005 SDK v3 August 2006 CTP" is on the server. This is a "Community Technology Preview" and does not contain the document we want. The real thing should be available soon.

VS 2005 SDK Download:

http://msdn2.microsoft.com/en-us/vstudio/aa700819.aspx

Quick Start

All search filters live in the following folder (English is 1033). Make a copy of an existing XML filter file and edit it to what you want.

\Program Files\Common Files\Microsoft Shared\VS Help Data\8.0\Filters\1033\

To enable your filter go to the following registry location and add your file name (without the .XML file extension) as a DWORD (like the others) and set its value to 1.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Help\VisibleFilters]

"MyXMLFilterFile"=dword:00000001

That's it. Next time you restart Dexplore you should see your filter in the list.

File Format

Here's a file I'm using called HelpwareH2Reg.XML (placed in the VS Filters directory with the other XML filter files).

In the <FilterAttribute> section <Id> and <Name ..> have been left at "Technology", so my filter will appear in the existing filter category called "Technology".

In the <FilterValue> section <Id>H2Reg</Id> gives my filter a unique ID and <Name ...> provides the visible text for the filter checkbox.

This Id must be unique! If I had a second file also using the same <Id>H2Reg</Id> then only one filter would show.

The <LocalFilterString> section defines the filter. This will effect local search only.

The <OnlineFilterString> defines where content is found in the MSDN online content.

<?xml version="1.0" encoding="utf-8"?> <SearchFilter xmlns="http://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>H2Reg</Id> <Name _locID="name.2">Helpware H2Reg documentation</Name> <Meaning> <LocalFilterString>("helpware"="h2reg")</LocalFilterString> <TocInclude></TocInclude> <OnlineFilterString> <![CDATA[ <StringTest Name="ExtendedProperty" Operator="Equals" Value="ms0TCRXH" ExtendedProperty="MSCategory"/> ]]> </OnlineFilterString> </Meaning> </FilterValue> </FilterAttribute> </SearchFilter>

Document Attributes

Each of the documents in my H2Reg collection (which I plugged into the VS document collection) are stamped with the attribute "helpware"="h2reg". Below is a sample of a document header. The other seven attributes you see here are required so that my TOC and Index correctly integrated into the VS collection.

<html>

<head>

<title>About H2Reg</title>

<xml>

<MSHelp:TOCTitle Title="H2Reg Introduction"/>

<MSHelp:RLTitle Title="H2Reg Introduction"/>

<MSHelp:Attr Name="helpware" Value="h2reg"/>

<MSHelp:Keyword Index="F" Term="H2Reg Intro"/>

<MSHelp:Keyword Index="F" Term="H2Reg"/>

<MSHelp:Keyword Index="F" Term="VS.Ambient"/>

<MSHelp:Attr Name="Information Type" Value="Orientation"/>

<MSHelp:Attr Name="Information Type" Value="Reference"/>

<MSHelp:Attr Name="DocSet" Value="Visual Basic"/>

<MSHelp:Attr Name="DocSet" Value="Visual Studio"/>

<MSHelp:Attr Name="TargetOS" Value="Windows"/>

<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

<MSHelp:Attr Name="LinkGroup" Value="GettingStarted"/>

</xml>

</head>

Adding a New Category

So lets now add two filters under a new Category called "Helpware Software".

Since each filter needs its own XML file we have created two XML filter files, HelpwareH2Reg.XML and HelpwareH2Reg-2.XML.

Installation:

Both files are placed into their correct location (default Eng location)

\Program Files\Common Files\Microsoft Shared\VS Help Data\8.0\Filters\1033\

Both files are enabled via the registry entry

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Help\VisibleFilters]

"HelpwareH2Reg"=dword:00000001

"HelpwareH2Reg-2"=dword:00000001

Each XML file has 3 main main sections that we care about.

<FilterAttribute> defines the top level filter category (like Language, Technology, Content Type).
<FilterValue> defines the entry in the filter dropdown list.
<Meaning> defines the actual filter used in the search.

Once we restart DExplore here's what we see in the Search tab.

<FilterAttribute> <Id>Helpware</Id>

Each XML file has been given the same FilterAttribute Id of "Helpware" as we want the two new filters to appear under a single new category name called "Helpware Software". If the files used different FilterAttribute Ids you would see two new categories appear instead of one.

Note that the user never sees the "Helpware" Id. You could name it "Fred" and it would still work.

Note that the "Helpware" Ids are used to sort the filter category names. So what if we renamed the FilterAttribute Id from "Helpware" to "ZZHelpware"?

The category name would be sorted to the bottom of the list.

<Name _locID="name.1">Helpware Software</Name>

As you guessed this is simply the filter category display name.

<FilterValue> <Id>H2Reg</Id>

<FilterValue> <Id>H2Reg-2</Id>

As mentioned before the FilterValue Id for each file must be unique otherwise some filters wont show, since they will walk over each other.

Note that you can not control the FilterValue sort order. They are always sorted by <FilterValue> Name.

<FilterValue> <Name _locID="name.2">H2Reg documentation</Name>

This is the filter name that is displayed in the checked list.

<LocalFilterString>("helpware"="h2reg")</LocalFilterString>

This is the actual filter. This filter will find all docs containing attribute "helpware"="h2reg" (as this next HTML doc snippet shows).

<head>

<xml>

<MSHelp:Attr Name="helpware" Value="h2reg"/>

...

</xml>

...

<LocalFilterString>("DocSet"="Visual Studio") AND ("helpware"="h2reg")</LocalFilterString>

This filter would show only those HTML files which contained attributes "DocSet"="Visual Studio" AND "helpware"="h2reg".

<LocalFilterString>("DocSet"="Visual Studio") OR ("helpware"="h2reg")</LocalFilterString>

This filter would find HTML docs which contained _either_ "DocSet"="Visual Studio" OR "helpware"="h2reg" OR both.

This section is used with MSDN online content. If you find any info on this section let us know and we will publish it here.

Appendix

Additional reading

H2 Attributes and Filters
- H2 FAQ --> How do I find the Path to the VS .NET Folders?

Page updated

Report abuse