MS Help Viewer‎ > ‎

HV1 Info

Introducing MS Help Viewer 1.0

10-Mar-2009 - Original document by Rob Chandler. Thanks MVP Dana Worley for the Edit.
17-Oct-2009 - Update info for Beta 2 release. Name change from MS Help 3 to release name of "MS Help Viewer".
21-Oct-2009 - Microsoft now say the official name is "MS Help Viewer" and this name won't change.
12-Feb-2010 - Cleanup (coincides with RC release).
16-Feb-2010 - Remove JSON format reference since JSON wont be shipping with this first release.
26-Feb-2010 - New offline URL param called embedded=true that hides the embedded topic navigation pane.
27-Feb-2010 - General cleanup of API & URLs.
01-Apr-2010 -  Update Microsoft.Help.Category info.

Introduction | Help Components | Product Manifest |  Help Library Manager | XHTML | Meta Tags | Converting H2  | API & URLs


Sept 2010:  The official Help Viewer 1.0 SDK is now available so covers much of the material in this document.  It also contains some basic C# code for HV 1.0.

You may still find this one page overview useful to read.

March 2012: Details of Help Viewer 2.0 SDK is now available.



This page contains information for developers & authors who need to prepare for the Visual Studio 2010 release.

Thanks to Paul O'Rear and Sheridan Harrison (MS Help team PMs) for early documentation updates and guidance.

The official name is Microsoft Help Viewer 1.0.  The pre-release was known as MS Help 3.
(the last help system (help 2) was known in Visual Studio as MS Document Explorer)

Microsoft have made available some basic documentation here:

MS Help Viewer 1.0 consists of:

  • Help Library Manager - Application for installing, uninstalling, updating help content.
  • Help Library Agent - Application associated with ms-xhelp:// protocol. Opens H3 URLs in the default web browser. Monitors Help 3 links like  and fetches and serves up the correct page from the data store.

These names were agreed on after VS 2010 Beta 2 shipped. You will see them in the RC and RTM releases.

Comment from Rob:

It's a strange name since the "help viewer" is actually your default browser.  In the past the viewer's name was "Document Explorer" so that's probably where they are coming from. Given such a generic and misleading name, I'll probably refer to the help system more as "VS 2010 Help system" or "MS Help 3" (although MS want to move away from the help 3 branding).

Help Viewer 2.0

The info on this page that relates to help file format is the same for both HV1 (VS 2010) and HV2 (VS 2012/Win 8). However the help engine and executables for HV2 is completely different.

For HV2 please see


General FAQ

What is MS Help Viewer 1.0?
MS Help Viewer is the new help engine for Visual Studio 2010 (version 10) and beyond. 
It replaces MS Help 2.x, which is the help engine for VS 2002/2003/2005/2008 (VS version 7.0/7.1/8/9).
Will MS Help Viewer 1.0 eventually replace HTML Help (.CHM) help?
The current focus is VS 2010 help. If it becomes popular maybe it will. We hope so.
Can MS Help Viewer 1.0 be used outside the Visual Studio environment?
Yes, you can create standalone help systems just like in MS Help 2.
Where is the offline Help Viewer?
By default offline help opens in your default browser. There is a registry item you can use to override the viewer. EG. Make H3Viewer (free 3rd party viewer) the default.
Will MS Help Viewer 1.0 be a full featured release?
The help team won’t have time to implement everything in this first release. Some features such as filters (for Search, TOC, Index scoping) will probably be pushed out to a future release, along with API support etc. The next version should be richer in features and target ISVs (Independent Software Vendors who make Help Authoring Tools).
Why a new help system?
It's time to change. Help 2.x has served us well but has some flaws such as: Lengthy merge times that lock up VS and Help; Complex registration requirements; Search and F1 results not 100% reliable.  Over help 2.x's lifetime they tried to improve search and F1 but users were never satisfied with it.
So how is MS Help Viewer 1.0 better?
MS Help Viewer has been designed with simplicity, relevance and speed in mind. There is no complex registration script required. The topic tagging system is much simpler than in Help 2. Complex attribute and A Link tags are gone. Merging is asynchronous and happens in the background.  Also the Hep 3 code is now completely separate from the VS code.
Will search restrict us to a 500 hit maximum again?
No. All results are available no matter how many hits you get.

Give it to me in a nutshell

  • HTML topics must now be in XHTML format.
    • Microsoft recommend XHTML 1.0 Transitional or better.
    • The basic requirement of the rendering engine is well formed XML with all tags closed and nested correctly (e.g., <p>..</p>, <br />).
  • A new topic attribute system uses standard HTML meta tags.
    • Search and TOC require that every topic has a unique help ID.
    • TOC, Index, F1 keywords are all defined using topic meta tags. No longer defined in separate files.
  • Packaging is simple. Zip it and ship it. No compiler required.
    • Zip your help content and rename the zip to .MSHC (MS Help Container). That's your help file.
    • No SDK or Help Workshop is required, although a good authoring tool always makes the job easier.
    • Your help is indexed & merged at installation time.
  • The help viewer is any modern web browser.
    • For this first release there is Search, but no visible Index.
    • TOC is currently the MSDN Loband format.

Offline vs Online help

To be clear, we are only talking about MSDN offline (local) help. MSDN online help is quite different and does not use .MSHC files. 
When in VS Online mode, F1 will use locally installed help if available. This is an improvement on MS Help 2 where local help did not work in Online mode.


Help Components


All HTML topics must be formatted in XHTML format. The main requirement is that all tags are correctly closed and nested. Microsoft recommend XHTML 1.0 Transitional or greater.

Keywords, TOC, Locale, etc. are all defined in the topic file headers using standard HTML meta tags. Each topic file must contain a unique topic ID meta tag. TOC structure is defined using these topic IDs.

.MSHC (Microsoft Help Container) - Help file

Help files are very simple. If you zip your help content (HTML/Images/etc) to a .zip file and rename to a .mshc file extension, then you have made a valid help file. So you can decompile any .mshc file by renaming to .zip and unzipping the content.

There currently no MS Workshop,  SDK or compiler required. Indexing of help content is performed at installation time.

.MSHI (Microsoft Help Index) - Index fragment

Like MS Help 2 you can ship your help file with, or without, an index file. If you don't ship an index it will be generated automatically at install time.

Microsoft call this an "Index fragment" since it will be merged with the target catalog's master  index. The .mshi file is a proprietary binary file format.

Microsoft ship each .mshi and .mshc file in a signed .cab file.  You can probably merge your help and then extract the index from the Help Library store if you really want to ship an index file.

For release 1.0 all installed help files (.mshc and .mshi) are copied to a central data store (typically <csidl_commonappdata>\Microsoft\HelpLibrary\ - eg c:\ProgramData\Microsoft\HelpLibrary\).

The index fragment is merged with the rest of the catalog to make one enormous master index catalog. At the moment the system breaks this very large master index into several 50MB partitions. Each partition has an .mshi file extension like the .mshi index fragments.

.CAB files - Package

Microsoft ship their .mshc and .mshi files in a signed .cab file. MS call this a "package".  A help package can be a single .mshc help file, a .mshc file wrapped in a signed .cab file, or a pair of .mshc/.mshi files wrapped in a signed .cab file.

Note: Signed CAB files can be installed silently.

Packages, Books & Catalogs

  • A Package is a single .mshc help file. Or a pair of .mshc & .mshi files wrapped in a signed .cab file.
  • A Book is a group of packages that you install together. A package can belong to more than one book.
  • A Catalog is a collection of books. A book can belong to more than one catalog.

Note that a catalog is an offline concept. MS online help is a very different system.

Each catalog is defined by 3 values:  Product ID + Version Number + Locale.

The English Visual Studio catalog is "VS" + "100" + "en-us". Microsoft ship several catalogs since they have several language versions.

A package should contain no more than than 10,000 topics. You can add more, however performance may suffer. A book can contain any number of packages (no upper limit has been defined).


  • Catalog: Product = vs (Visual Studio), Version = 100, Locale = en-us
    • Book: Visual Basic Documentation
      • Packages A, B & C
    • Book: Visual C# Documentation
      • Packages A, D & E

.MSHA Product Manifest

Product definition file (MSHA - MS Help Asset file) defines books and their packages you want to install. We pass it to the HelpLibManager.exe at install time.

In v1.0 the setup file name must be helpcontentsetup.msha.

Help Library Manager

HelpLibManager.exe is the main UI used to install, uninstall, update help files.

  • c:\Program Files\Microsoft Help Viewer\v1.0\HelpLibManager.exe

You communicate with it using the command line. The first 3 arguments define the catalog context. For VS 2010 this is usually:

  • HelpLibManager.exe /product VS /version 100 /locale en-US

When installing new help you also pass in a .msha file that defines the book and package(s) you want to install.

Help Viewer

Both online (web) and offline (local) help display in your default browser. You are not locked into using the Microsoft browser.

You can override the viewer for Offline help via a registry setting.

ms-xhelp:/// Protocol

The ms-xhelp:/// protocol is associated with the Help Library Agent application.  If you ShellExecute() an ms-xhelp:/// help URL the Help Agent will run (appears in the Taskbar tray), pull the data from the data store and send the output to the default browser.

Other Stuff

Stop Words

The indexer library uses the same stop word lists used by the Help 2.x help system. The new help system supports stop words for the following languages: en-us, de-de, es-es, fr-fr, it-it, ru-ru. The StopWord files can be found in the c:\program files\Microsoft Help Viewer\v1.0\ folder.

Search Results and Ranking

When viewing search results you want the most relevant to be listed first. The algorithm to calculate ranking will, I'm sure, be tweaked and tuned for a long time to come. However, typically it is based on criteria such as -- Does the word appear in the title; Does the word appear in keywords; Does the word appear in body content (ordered by frequency).


.MSHA - Product Manifest file

A product definition file defines a book and its package(s) you want to install. You pass this to the Help Library Manager (HelpLibManager.exe) application at install time. In MS Help 2.x the .HxC collection level file had a similar function.

In v1.0 the setup file name must be helpcontentsetup.msha.

Here is a  typical .msha file used to install a book containing 2 packages.

<html xmlns="">
  <title>An optional title that can be useful for tools used
     to generate these files.</title>
<body class="vendor-book">
  <div class="details">
    <span class="vendor">Contoso Corporation</span>
    <span class="locale">en-us</span>
    <span class=”product”>Contoso Widget Studio </span>
    <span class="name">Contoso Widgets</span>
  <div class="package-list">
    <div class="package">
      <span class="name">package1</span>
      <a class="current-link"
    <div class="package">
      <span class="name">package2</span>
      <a class="current-link"

Notice the div tags are like records. The class names are used to name each part. While the <span> and <a> tags are like record data items.

  • <title> is a general purpose field that vendors or anyone can use. It's not used by the help system.
  • The <body> tag must have a class name = "vendor-book".
  • The "details" section describes the book.
    • Vendor - Company that owns the book and packages. Also used for certificate validation.
    • Locale - Must match the catalog locale if this book is to participate.
    • Product - Product name.
    • Name - Name of the book.
  • The "Package-list" section contains one or more "package" sections. A package is a .mshc help file.
    • <span class="name">xxx</span> - Where xxx is the name of the package minus the file extension.
    • <a class="current-link" href="yyy">xxx</a> - Where yyy is a relative link to the package file. The xxx label is not used by the help system but may be useful to vendors.


HelpLibManager.exe - Help Library Manager

The Help Library manager is used to install, uninstall and update help content. For install you pass the .msha file to HelpLibManager.exe as a command line parameter along with the name of the target catalog. Remember a help catalog is always defined by 3 things (a 3 part key) - Product ID + Product Version + Locale.

The Help Library Manager is usually installed here:

  • c:\Program Files\Microsoft Help Viewer\v1.0\HelpLibManager.exe

To simply run Help Library Manager in the VS 2010 help context run:

  • HelpLibManager.exe /product VS /version 100 /locale en-US

You could set up a link for your own help like this. Add /NoOnline to disable web links.

  • HelpLibManager.exe /product MyHelpCatalog /version 100 /locale en-US /NoOnline

To install packages pass the name of the .msha manifest file using the /sourceMedia switch.

  • HelpLibManager.exe /product VS /version 100 /locale en-US  /install /sourceMedia "C:\path\to\HelpContentSetup.msha"


Command line parameters (run HelpLibManager /?)

/product product-ID Required. For VS 2010 help catalog product id = vs
/version product-version Required. For VS 2010 help catalog product version = 100
/locale product-language Required. For VS 2010 help catalog product locale = us-en (for the English version of MSDN)
/install Used to install help into a catalog.
/sourceMedia source-path Used to specify the path to the .msha manifest file.
/sourceWeb source-path Used by MS to connect to web based content. No details currently published by MS.
/content local-store-path Use the /content argument if you can't guarantee that a Local Cache has already been defined. If local store has already been defined then this switch is ignored. Probably more useful to Microsoft than 3rd parties.
/silent In silent mode the Help Library Manager UI is not shown. Help packages must be distributed in a signed cabinet (.cab) file, otherwise using the /silent switch will generate an error. The /silent switch requires either the /sourceMedia or /sourceWeb or /uninstall switch. 
Note that  /uninstall /silent combination can be used on unsigned help.
/NoOnline Help Library Manager will disable online commands. Useful for 3rd party content.
/brandingPackage package-file Specify your own branding package. Do not specify the full path. Instead install the branding .mshc file to the local store path. See branding below.
/uninstall HelpLibManager.exe /product vs /version 100 /locale en-us /uninstall /silent /vendor "Helpware Inc." /mediaBookList "My book 1" "my book 2" "my book 3" /productName "Helpware Library"

The first 3 parameters identify the catalog. The next two indicate an uninstall with no UI displayed. The next 2 parameters identify the vendor (to handle the case where 2 vendors have the same book name), and the list of books to remove.  The parameters are not presumed to be in any order. 

See the definition of a .msha file for more details. 
Note that  /uninstall /silent combination can be used on unsigned help.


  • If you request a catalog that does not exist, HLM will create the catalog and install help on help content.
  • What if HLM is already running when my setup launches? You need to detect it and ask the user to close the applications.

Local Store

Local Store is where all help catalog info is stored (this includes a copy of your .mshc & .mshi files, master mshi index files etc). 
Default location for Windows 7 and Vista is: C:\ProgramData\Microsoft\HelpLibrary\
Default location for Windows XP is: C:\Documents and Settings\All Users\Application Data\Microsoft\HelpLibrary\

You can find the path to the local store as well as the application runtime files in the registry here:

  "AppRoot"="C:\\Program Files\\Microsoft Help Viewer\\v1.0\\"

From Kimberly Wolk's Blog.

"We received a number of requests to lock down the directory where Help Library Manager installs content and we’ve now ACL’ed that directory to restrict permission to update content to members of the HelpLibraryUpdaters security group. This group is created during setup, and by default, it includes the administrators group and the user account that created the local store. To enable support for multiple users (non-admins) to update content on the machine, an administrator must add the additional accounts to the HelpLibraryUpdaters security group. As a further security check, Help Library Manager will also check the digital signature used to sign cabinet files that contain content to be installed locally. When installing content interactively, you can view the certificate of signed MSHCs and approve or reject the content."


Currently when you install, Help Library Manager UI appears and shows the user the books available for installation. To automate installation (no UI displays) use the /silent switch (only works with signed cab files).

Branding - /brandingPackage

You can override the branding (logo, ,css, footer, etc) by specifying your own branding package on the command line.  The default is to use the standard MS supplied branding package which is installed at:

  • c:\Program Files\Microsoft Help Viewer\v1.0\Help3Branding.mshc

If you do override branding you will also need to set each topic's SelfBranded meta tag to true. ?? This area is still pretty fuzzy to us. ??


Help Integration

You can integrate into an existing catalog or install as new catalog. This is similar to what we did in MS Help 2 where we could plug in to an existing namespace or create a standalone new namespace).

Typical VS integration scenarios:

  1. VS Standard Integration - Full integration with VS.
  2. VS Integrated Shell Mode - Application can be installed with or without VS being present. If no VS then only the vendor's content shows. If VS is installed then content is fully integrated with VS.
  3. VS Isolated Shell Mode - Application is part of VS IDE shell but has no shared integration experience. Content lives in its own catalog and does not integrate with VS content.

Paul O'Rear's comment: 2 is say you install a book into VS+100+en-us catalog but Visual Studio content isn't there yet. You will see your content and when VS content is installed you will see that as well. 3 is for standalone help experience.


XHML Bootstrap

You'll need to buy a HTML editor that can validate XHTML. The one we use is MS Expression Web 3.0.

XHTML is like HTML with XML syntax rules applied.

The basic XML rules are:

  • All tags must be closed. <p>...</p>, <br /> etc
  • Correct nesting of tags. This wrong: <p> <a href="xx"></p> </a> -- This is correct:  <p> <a href="xx"></a></p>
  • Attribute values must be wrapped in quotes.  <tag-element attribute-name="attribute-value">
  • Tag elements and attribute names must be lower case. <a href="C:\path\image.gif"> not <A HREF=...>
  • HTML files must have structure <html><head><title>title</title></head><body>..</body></html>

To strictly conform to XHTML:

  • The first line of the file should be the XML declaration <?xml version="1.0" encoding="UTF-8"?>. Although Unicode files may omit this line.
  • The appropriate <!DOCTYPE …> declaration at the start of the file before the <html> tag.  Although help will cope if you omit this.
  • The HTML tag must contain this exact namespace declaration: <html xmlns="">.

Note: VS 2010 online documentation is using XHTML 1.1  -- See MSDN web page example.

The web has many good XHTML reference docs.  Start here:

Here is a basic XHTML 1.1 document header.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
<html xmlns="">

The first line in the file is the XML declaration - <?xml version="1.0" encoding="UTF-8"?>. The w3c say this can be omitted if your file is Unicode encoded (UTF-8 or Unicode).  Older browsers can choke on this statement.

You have 3 choices of XHTML doctypes.  XHTML 1.0 Transtional; XHTML 1.0 Strict; XHTML 1.1;  
(4 choices if you count quirks mode and omit the DOCTYPE declaration).

XHTML 1.0 traditional has the most relaxed requirements. XHTML  1.0 Strict is basically the same as XHTML 1.1. Neither allows you to use tags such as <font>, <iframe>, <nobr>, <s>, <strike>, <u>. You may get away with operating in quirks mode and removing the XHTML doctype declaration completely.

The <html xmlns=""> xml namespace is required for XHTML.

So your header will look something like one of these...

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
<html xmlns="">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
<html xmlns="">


Topic Meta Tags

In MS Help 2.x each topic was required to have an <xml> data island containing various H2 <MSHelp:..> tags. MS Help Viewer 1.0 on the other hand uses standard Meta tags <meta name="property" content="value" /> in the <head> section of each topic. The rules are much simpler. For one thing the H2 Attribute tag and "A" Index Keywords are no longer supported. The other big change is that the TOC and Index standalone files are no longer supported. You now define your TOC and visible Index in your topic HTML files using meta tags.

The following table lists the attributes recognized by the MS Help Viewer indexer.

Column 2 indicates if the tag is required or can be repeated:

1 Tag is required and must appear once in each document.
0/1 Tag is optional and can only appear once in each topic.
0/* Tag is optional and can appear many times in each topic.


Title 1 Each document must have a standard HTML title. Used by TOC, Index and Search Result labels.
<title>Doc Title</title>
Microsoft.Help.Id 1 Every topic must have a unique ID string. The ID is used in search data and for TOC relationships. It can be tricky to think up a unique ID, so MS recommend using GUIDs since these 128-bit integer numbers have a very high degree of certainty of being unique. For .net assembly methods MS suggest using your assembly's class, member and type information as the ID value.
<meta name="Microsoft.Help.Id" content="TopicIdentifier" />

Within the same catalog Microsoft may have different versions of a topic (e.g. .NET Framework 3.0 and 3.5),  or different language versions of topics. In these cases the topics use the same Help IDs, and use Microsoft.Help.Locale or Microsoft.Help.ProductVersion to disambiguate.  Usually TOC items that match the Catalog locale show, and similar with F1 Keyword match (catalog locale match has priority). For Search, all matches are shown no matter what the locale.

Microsoft.Help.Locale 0/1 Word break locale for this doc. Tells the indexer which word-breaker to use when parsing the topic for search terms.  Should appear before other Help tags.
Locale examples: en-us, de-de, es-es, fr-fr, it-it, ru-ru - See a full list of locales
<meta name="Microsoft.Help.Locale" content="language code" />
If omitted use the product locale. If that is omitted defaults to en-us. 
The Help 2 equivalent would be <MSHelp:Attr Name="Locale" Value="kbEnglish" />
MS recommend you include this tag.  
This tag conforms to RFC 4646.

Note that VS test and ship with 9 core languages (as far as I know) -  French, Italian, German, Spanish, Japanese, Chinese, Chinese – Taiwan, Korean, and Russian.

Microsoft.Help.TopicLocale 0/1 Topic Locale is used when there is mixed content in the same catalog and you want to determine the most appropriate match for a lookup. For example, if there were an F keyword lookup on JPN content, which may have both ENU and JPN content installed, the topic with .TopicLocale matching JPN would win out.
Locale Code examples: en-us, de-de, es-es, fr-fr, it-it, ru-ru
<meta name="Microsoft.Help.TopicLocale" content="language code" />
For the kind of values expected see "Short String" column of this table
MS recommend you include this tag. 
This tag conforms to RFC 4646.
Microsoft.Help.SelfBranded 0/1 Set SelfBranded=true to allow your topics to continue to use their own .css, scripts, logo, support link. Set false to use the Microsoft branding. The default is SelfBranded=false.
<meta name="Microsoft.Help.SelfBranded" content="true" />
 -- This will change / expand.
Microsoft.Help.Keywords 0/* Keywords appear in the Help Viewer's Index navigation pane ("Visible Index").
<meta name="Microsoft.Help.Keywords" content="Keyword" />
<meta name="Microsoft.Help.Keywords" content="level 1 item,Keyword" />
Use a comma to make a second level keyword (remember visible indexes are hierarchical).

More than 2 levels are not supported. There is currently no visible index in the help viewer. Keywords allows the topic to be found in a keyword search and gives your topic higher ranking in search results.

The K index items of older help systems can be converted directly to MS Help Viewer keywords.

Microsoft.Help.F1 0/* F1 keyword. Any topics you want to link to should be given an F1 keyword. MS Help Viewer 1.0 does not have a disambiguator (a window showing multiple hits like in help 2). The first keyword found will show. Ideally each topic should contain zero or one F1 Keyword. If 2 topics share the same keyword you can use Microsoft.Help.Category to make your topic show in the correct context.
<meta name="Microsoft.Help.F1" content="ContextID" />
Description 0/1 Optional summary about this document, 256 chars or less. This text is not stored in the index but accessed directly by the query engine. This is the same as the standard HTML description used in HTML documents. This text is used in the search result list.
<meta name="Description" content="topic description" />
Microsoft.Help.TocParent 0/1 Builds the TOC hierarchy. Set the ID = -1 to make the topic appear at the top level of the host TOC. Excluding this tag or specifying an invalid ID will hide the topic from the TOC. To parent your TOC into the MSDN help, set your root topic's TocParent to be the HelpID of the required MSDN topic page.

For version 1 this tag can only appear once per HTML topic.
<meta name="Microsoft.Help.TocParent" content="TopicIdentifier" />

To add your TOC to the top level of the VS master TOC set your topic's TOCParent attribute = -1. To parent to a specific location you would do a "view source" to find the Microsoft.Help.Id of the parent topic.

Microsoft.Help.TocOrder 0/1 Specify the order of the TOC item relative to its peers. If several topics claim the same TocOrder then they will be sorted alphabetically. For version 1 this tag can only appear once per HTML topic.
<meta name="Microsoft.Help.TocOrder" content="some positive integer, 1..n"/>
Microsoft.Help.TocInfo 0/* This is a possibility for version 3 release.

The TocParent and TocOrder (above) are replaced by a single meta tag statement TocInfo. This tag can appear multiple times in a topic file.

<meta name="Microsoft.Help.TocInfo" content="TocParent|TocOrder" />

Another v2 TOC idea is to introduce ProductID + Version. Since a Help file can contain multiple product and version info, this allows you to show TOC nodes for certain product and/or versions only.

<meta name="Microsoft.Help.TocInfo" content="TocParent|TocOrder|ProductID|Version" />

Microsoft.Help.Product 0/1 Product code.
<meta name="Microsoft.Help.Product" content="some product code" /> 
You can also pass this to indexer during product Help file installation.
Microsoft.Help.ProductVersion 0/1 Product Version.
<meta name="Microsoft.Help.ProductVersion" content="some version number" />
You can also pass this to indexer during product Help file installation.
Microsoft.Help.TopicVersion 0/1 Topic Version.
<meta name="Microsoft.Help.TopicVersion" content="some version number" />
Used internally by Microsoft. A number can be entered that display a predefined product version string in search results. 
For more information see Search Results version text
You cannot predefine your own version text for search results. Note however HV2 (VS 2012 help) now has a new tag "Microsoft.Help.DisplayVersion" for this purpose.
Topic Version also helps to disambiguate topics that share the same Help ID. EG. The same topic from different versions of a product.
Microsoft.Help.Category 0/* Identify subsections of content.
<meta name="Microsoft.Help.Category" content="AttributeName:AttributeValue" />

If 2 topics share the same F1 keyword you can use Category as a ti-breaker. 
EG. 2 of topics have F1="100".  If your topic has 
Microsoft.Help.Category="myCompany". Then following URL will open your topic correctly even though there is another F1=100 in the system. This feature relies on you being able to make the F1 calls.

Microsoft also use categories to make topics appear in the correct context. 
MS use 3 different attribute names:  
TargetOS, DevLang, TargetFrameworkMoniker
3rd parties can extend them; e.g., DevLang:MicroFocusCobol.
Visual studio IDE passes these values when F1 is pressed.
EG. Stamp your C# documentation with <meta name="Microsoft.Help.Category" value="DevLang:CSharp" />
When you are in the C# environment of VS 2010, then VS F1 will emit a DevLang parameter in the URL 
VS currently uses the following DevLang values:  C++, VB, CSharp, FSharp, Jscript.

Check the MS documentation when it becomes available.

Microsoft.Help.ContentFilter 0/1 UI selectable values to filter TOC, Index and Search.
<meta name="Microsoft.Help.ContentFilter" content="some_string_value" /> 
Content without a filter always shows no matter what filter is selected.
Help 2 filters can not be easily converted as this is a new system.
Not available in the first release.
Microsoft.Help.ContentType 0/* Allows search results to be sorted so customers can see, for example, all results under “Samples" or “Error Messages".
<meta name="Microsft.Help.ContentType" content="some_value" />
Not available in the first release.

Converting MS Help 2 --> MS Help Viewer 1.0

First up. Can MS Help Viewer and MS Help 2 projects share the same content files? I currently get install errors if I don't comment out the MS Help 2 <MSHelp:...> header tags. I'm hoping we can solve this problem soon then it will be possible to use the same files for both help systems.

Each HTML topic file must be give a unique ID.
<meta name="Microsoft.Help.Id" content="TopicIdentifier" /> 
Topics header must contain a <title>Doc Title</title> tag. In Help 2.x we could also specify a unique title for display in the TOC and Result List using <MSHelp:TOCTitle> and <MSHelp:RLTitle> but these are no longer supported.
TOC and Index files
External TOC and Index files are no longer supported. TOC and Index items can only be defined by using topic meta tags. The job of converting TOC and index files into topic tags really requires the help of a software tool of some kind (unless you have enormous patience).
Every topic must be given a unique help ID (typically a GUID), then you can use 
<meta name="Microsoft.Help.TocParent" content="parent_Id" />
<meta name="Microsoft.Help.TocOrder" content="some positive integer" />
 topic tags to define the TOC. Indexes are similar and use the 
Microsoft.Help.Keywords tag (see below).

TOC items must be defined in topic files, so empty TOC links, items with book marks and remote TOC items are not allowed. Also in MS HV 1.0  a topic can only appear once in the TOC. The Helpware Migrate Utility attempts to get around these limitations by generating place holders topic files.
Topic keywords (K Index) convert easily. These are visible keywords that show up in the viewer's Index navigation control at runtime. Use the meta tag "Microsoft.Help.Keywords".
H2: <MSHelp:Keyword Index="K" Term="SystemBrushes.InactiveCaption property" />
HS: <meta name="Microsoft.Help.Keywords" content="SystemBrushes.InactiveCaption property" />

As with previous help you can use a comma to achieve a level 2 index item. Level 3 and above are not supported.
<meta name="Microsoft.Help.Keywords" content="Level 1 label, Level 2 item A" />
<meta name="Microsoft.Help.Keywords" content="Level 1 label, Level 2 item B" />

Although MS Help Viewer 1.0 may not show these in the UI they are still useful for tweaking the search ranking etc.
See also the section below on Visible Keywords
F1 Keywords
Help 2.x "F" topic Keywords convert fairly easily to F1 topic meta tags. There is no disambiguator so make sure each topic has only one F1 keyword, otherwise the first keyword found will be used.
H2: <MSHelp:Keyword Index="F" Term="VS.Ambient" />
<meta name="Microsoft.Help.F1" content="VS.Ambient" />
"A" Keywords
"A" Links don't exist in MS Help Viewer 1.0. If you were using them then try using the new topic Help ID or F1 keyword instead.
H2: <MSHelp:Keyword Index="A" Term="6c1cac41-dfc9-4a03-b857-0f685d663482" />
Attributes & Filters
MS Help Viewer 1.0 filters will probably be quite different and simpler. Not available in first release.
Topic Locale
Setting the locale is optional. The default is "en-us". 
MS Help 2 defined locale from a different set of strings.
H2: <MSHelp:Attr Name="Locale" Value="kbEnglish" />
: <meta name="Microsoft.Help.Locale" content="en-us" />
: <meta name="Microsoft.Help.TopicLocale" content="en-us" />
Note: MS ship Japanese help with some English topics. So the Product Locale is Japanese but the Topic Locale (meta tag) can be English.
Product Version
Setting the version is optional.
Rob: Help 2 does have a similar setting but may not be exactly the same meaning.
H2: <MSHelp:Attr Name="TopicVersion" Value="08.00.60815.10000" />
<meta name="Microsoft.Help.ProductVersion" content="08.00.60815.10000" />    ???????
Virtual topics are not supported.
Not supported.
Not supported.


Visible Keywords

A few notes on coding for visible keywords (Index Tab of older Help Viewers).

In the MS Help 2.x "K" Index file below, there are 4 types of keywords used (highlighted).

  1. Keyword term that targets a topic file.
    In MS Help Viewer 1.0 the topic file somefile.html would require the tag: 
    <meta name="Microsoft.Help.Keywords" content="Keyword1" />
  2. Level 2 keyword terms.
    MS Help Viewer 1.0 allows up to 2 levels of hierarchy in the index. We use a comma to indicate 2 levels.
    <meta name="Microsoft.Help.Keywords" content="Level 1 Keyword, Level 2 keyword" />
    <meta name="Microsoft.Help.Keywords" content="Level 1 Keyword, Level 3 keyword" />
  3. Keyword term that jumps to another keyword.
    These are not supported in the first release. Instead try and use a normal keyword term (1).
  4. Item opens a list of keywords.
    These are not supported in the first release. Instead try and use 2nd level keywords (2).

Summary: Release 3.0 won't support case #3 and #4.

<?xml version="1.0"?>
<!DOCTYPE HelpIndex SYSTEM "MS-Help://hx/resources/HelpIndex.DTD">

   <Keyword Term="Keyword1">
      <Jump Url="somefile.htm"/>
   <Keyword Term="Level 1 Keyword">
      <Jump Url="somefile.htm"/>
      <Keyword Term="Level 2 keyword">
         <Jump Url="somefile.htm"/>
      <Keyword Term="Label 3 keyword">
         <Jump Url="somefile.htm"/>
   <Keyword Term="JumpToKeyword1" Ref ="Keyword1"/>
   <Keyword Term="KeywordPopuplist">
      <Jump Url="somefile1.htm"/>
      <Jump Url="somefile2.htm"/>


Help TOC

Like the keywords (above) the MS Help Viewer 1.0 TOC system has some major limitations.

  1. Each topic can contain one TOC statement only.
    Or another way of saying this is that each topic can appear only once the TOC. This may change in a future version.
  2. Blank TOC entries are not possible, since TOC tags must be declared in a local topic file.
  3. TOC entries containing Bookmarks are not possible (similar reason).
  4. TOC entries containing remote links are not possible (similar reason) .
  5. MS Help Viewer 1.0 uses the topic <title> for its TOC item label.  So be aware that the Help 2 TOC labels are ignored when migrating to MS Help Viewer 1.0.

The way we got around these limitations in the mshcMigration utility is to generate place temporary holder topic file.



See also online doc: 


The ms-xhelp:// protocol is associated with the HelpLibAgent.exe application so if you ShellExecute() an ms-xhelp://?... URL it will start Help Agent (if not already running), and Agent will change the ms-xhelp:// protocol into a local URL and open it in the viewer.

Help Agent listens to all http: traffic on port 47873 -- (or  http://localhost:47873/) and if it sees these MS Help Viewer URLs it serves up the correct content.


There are several variations of help URLs:

  • ms-xhelp - Offline help via Help Agent. Only MS Help Agent understands this format. If you ShellExecute() this URL then Agent (as the associated application) will fetch the content from Help store and serve up the content to the default browser using the Offline URL format.
  • Offline format -  This form is something the browser can understand with Agents help. Help Agent is listening to http: traffic and will fetch the help content when needed.
  • Online help via MSDN, and Enterprise help using a company’s intranet via an IIS web server.


All use different URL formats however the parameters are the same.

ms-xhelp F1 URL:

  • ms-xhelp:///?method=f1&query=system.string&product=vs&productversion=100&locale=en-us

Local help F1 URL:


  • http://localhost:8007/ianholl-1/

Online help F1 URL:


Enterprise help F1 URL:

  • http://intranetserver/help/

The general format of an ms-xhelp url is as follows:

ms-xhelp:///?method=<method name>&<parameter name>=<parameter value>


You can use ms-xHelp:/// format to talk to Help Library Agent. Open the URL using ShellExecute() and your default browser will show the result.

To get data back from the Agent use the form.  The last number /1/ is the session number. Usually /1/ but may be greater. To get the session number use the wtsapi32.dll function WTSQuerySessionInformation(WTS_CURRENT_SERVER_HANDLE, WTS_CURRENT_SESSION, WTSSessionId, snum, bytes);  The default Port 47873 can be changed if necessary (see the readme release notes in c:\program files\Microsoft Help Viewer\v1.0\  ). For Win32 apps you could use WinINet API functions to make http: calls and capture the returning data into a string.


API Reference - F1

Used for VS context sensitive help.

Supported by: Local/Enterprise, Offline, Online.   (Note: Here I think Offline means Online help hosted on a local ISS server)



Required parameters: method=f1, query, product, productversion.
Optional: locale, lcid, category, format, t
argetframeworkmoniker, devlang, targetos.

"query"  can have multiple values separated by %00 (null).

"locale" - Can be omitted (defaults to thread locale). eg. locale=en-us
"LCID" - Can be omitted (defaults to thread locale). Can be used instead of Locale. eg lcid=1033
"category" - Useful to filter your F1 down to a specific area of the help.
"format" - Return format of the data. html or xml.  XML format wont contain the branding markup.
"targetframeworkmoniker" - MS use this as a tie-breaker for the topics having the same F1 keyword.

targetframeworkmoniker examples:

"devlang" - MS used this as a filter for F1 call. Currently used values are:  C++, VB, CSharp, FSharp, Jscript. 
Your topics can be marked with a DevLang, TargetOS or TargetFrameworkMoniker by using the category meta tag.
eg <meta name="Microsoft.Help.Category" value="DevLang:CSharp" />
eg <meta name="Microsoft.Help.Category" value="TargetFrameworkMoniker:.NETFramework,Version=v4.0" />
See Microsoft.Help.Category reference above. 


API Reference - Page

Display a page.

Supported by: Local/Enterprise, ISS Offline, Web Online.



Required parameters: method=page, id, product, productversion. 
Optional: locale, lcid, format, 
topiclocale, topicversion,

"id" - This is the topic id (see topic meta Other parameters are same as f1 above.
topiclocale" - Locale of the topic within a catalog as non-ENU catalogs could also have ENU topics. [Example value: en-us].
"topicversion" - Version of the topic within a catalog as multiple versions of the same topic can be installed in the same catalog 
      (.NET Framework 3.5 [90] and .NET Framework 4.0 [100] topics can be installed to the same catalog) [Example value: 90]


API Reference - Search

Full text search. Queries can consist of keywords and the logic operators (AND, OR, NOT, trailing *).  
The default action for keywords with spaces between them is AND. 

Supported by: Local/Enterprise, Offline, Online.



Required parameters: method=search, query, product, productversion, PageSize, PageNumber.  
Optional: locale, format

"query"  supports AND, OR, NOT logic (these must be uppercase).  e.g. "console NOT writeln".
"PageSize" - Number of result pages (e.g. 10).
"PageNumber" - 
Page number to display for pagination (1..n).

For parameters description see above.


API Reference - TOC

Returns the TOC for a particular id. Returns abbreviated TOC data consisting of  topics ancestors, children and siblings.

Supported by: Currently only supported by local help.



Required parameters: method=toc, product, productversion.  
Optional: locale, format.

For parameters description see above.

API Reference - Keywords

The returned data consists of all the keywords that begin with the query value.

Supported by: Currently only supported by local help.



Required parameters: method=keyword, query, product, productversion.  
Optional: locale, format, PageSize, PageNumber, 'category=topic'.

"PageSize" - Number of result pages (e.g. 10).
"PageNumber" - 
Page number to display for pagination (1..n).
'category=topic' - For LCTP4 and later releases add "&category=topic" to the URL to get back a single topic.

For parameters description see above.

API Reference - Ancestors

The returned data consists of all the TOC ancestors of the topic up to the root node.

Supported by: Currently only supported by local help.



Required parameters: method=ancestors, id, product, productversion.  
Optional: locale, format.

For parameters description see above.

API Reference - Children

The returned data consists of all the TOC children of the topic up to the root node.

Supported by: Currently only supported by local help.



Required parameters: method=children, id, product, productversion.  
Optional: locale, format (html
 or xml).

For parameters description see above.

API Reference - (Default)

Returns a static file from an .mshc file such as a style sheet, JavaScript, or image file. Returns byte stream.

Supported by: Currently only supported by local help.


ms-xhelp:///?C:\\programData\\Microsoft\\Help Library\\store\\dev10.mshc;/VS-logo.gif

Required parameters: path. Offline help only.

Path - Inner and outer path to the requested file. 
   Note that the inner and outer path are separated by a semi-colon.  
  Also note that the back-slashes are escaped and the internal path is forward slashed (this is important).

Returned format: Native file format as byte stream.

API Reference - Install

Invokes the Help Library Manager with the context of the specified catalog.

Supported by: Currently only supported by local help.

!!ToDo!!  Need Example!!


How to Hide the Embedded Navigation Pane

You will notice that most pages have an embedded search + loBand style navigation pane. In the RC build you can now hide this pane by appended the parameter "&embedded=true". This only works for offline URLs.

This URL will show the navigation

  • /help/1/

This URL wont show the navigation

  • /help/1/


  • File requests other than html are given a cache expiration time of 24 hours from the request time.


More Info


Copyright (c) 1995-2012, Robert Chandler, The Helpware Group