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

Introduction

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: 
http://msdn.microsoft.com/en-us/library/dd776252(VS.100).aspx

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 http://127.0.0.1/help/1/  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 http://hv2.helpmvp.com/

General FAQ

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

Topics

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).

Example:

• 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="http://www.w3.org/1999/xhtml"> <head> <title>An optional title that can be useful for tools used to generate these files.</title> </head> <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> <div class="package-list"> <div class="package"> <span class="name">package1</span> <a class="current-link" href="packages\package1.mshc">package1.mshc</a> </div> <div class="package"> <span class="name">package2</span> <a class="current-link" href="packages\package2.mshc">package2.mshc</a> </div> </div> </body> </html>

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 /?)

Notes:

• 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:

 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help]

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

  "LocalStore"="C:\\ProgramData\\Microsoft\\HelpLibrary\\"

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."

Installation

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="http://www.w3.org/1999/xhtml">.

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: http://www.w3schools.com/xhtml/xhtml_intro.asp

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" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> ...

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="http://www.w3.org/1999/xhtml"> 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" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> ...

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> ...

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> ...

 

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:

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.

HelpID

Each HTML topic file must be give a unique ID.
<meta name="Microsoft.Help.Id" content="TopicIdentifier" /> 
 

Title

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" /> and 
<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.

 

Keywords

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".
Examples:
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.
Examples:
H2: <MSHelp:Keyword Index="F" Term="VS.Ambient" />
HS: <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" />
HS: <meta name="Microsoft.Help.Locale" content="en-us" />
HS: <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" />
HS: <meta name="Microsoft.Help.ProductVersion" content="08.00.60815.10000" />    ???????
 

<MSHelp:Vtopic>

Virtual topics are not supported.
 

<MSHelp:NoSearch>

Not supported.
 

<MSHelp:Include>

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">
<HelpIndex
	Name="K"
	Visible="Yes"
	DTDVersion="1.0"
	FileVersion="1.0"
	LangId="1033">

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

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.

API & URLs

See also online doc: 

• HV1 (VS 2010) -- http://mshcmigrate.helpmvp.com/faq/api
• HV2 (VS 2012/Windows8) -- http://hv2.helpmvp.com/

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 http://127.0.0.1:47873/help/1/ms.help/ URL and open it in the viewer.

Help Agent listens to all http: traffic on port 47873 -- http://127.0.0.1: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.

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

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 http://127.0.0.1:47873/help/1/ 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)

Example:

Required parameters: method=f1, query, product, productversion.
Optional: locale, lcid, category, format, targetframeworkmoniker, 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:
    .NETFramework,Version=v2.0
    .NETFramework,Version=v3.0
    .NETFramework,Version=v3.5
    .NETFramework,Version=v4.0
    Silverlight,Version=v2.0
    Silverlight,Version=v3.0
    Silverlight,Version=v4.0

"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.

Example:

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

"id" - This is the topic id (see topic meta microsoft.help.id=). 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.

Example:

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.

Example:

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.

Example:

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.

Example:

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.

Example:

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.

Example:

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.

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

•  http://127.0.0.1:47873 /help/1/ms.help?method=f1&query=system.string&product=vs&productversion=100&locale=en-us

This URL wont show the navigation

•  http://127.0.0.1:47873 /help/1/ms.help?method=f1&query=system.string&product=vs&productversion=100&locale=en-us&embedded=true

Notes

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

More Info

• You can find a lot more useful stuff at  http://mshcmigrate.helpmvp.com/faq
• Free Help Viewer with full Index and TOC: http://mshcmigrate.helpmvp.com/viewer
• How to override the default viewer: http://mshcmigrate.helpmvp.com/news/overridingthedefaultviewer
• Migrate utility: http://mshcmigrate.helpmvp.com/home