Documentation‎ > ‎

HV2 Catalogs

posted Nov 11, 2011, 6:58 PM by Robert Chandler   [ updated Sep 11, 2012, 3:31 AM by Robert Chandler ]

There are now 3 types of catalogs but first let's recap on the differences between HV1 and HV2...

Quick Tour

HV1 / HV2

Help Viewer 2.0 is the help system for Vistual Studio 11 (2012).
Help Viewer 1.0/1.1 is the help system for Visual Studio 10 (2010) and VS 10 SP1. 
Previously Visual Studio 200? used a complete different help system called MS Help 2.0.

HV1 Local Store

In HV1 there was a single location (folder) on the PC (called the Help Store or Locale Store or Library Store) where all HV1 catalogs were stored. Each catalog was known by it's Product-ID/Version/Locale. EG. The English VS 10 help catalog was VS/100/en-US and the French help was a separate catalog VS/100/fr-FR. We used HlpLibManager.exe to add/remove/download help content.

HV2 Local Store

HV2 catalog stores have a slightly different structure and can now be located anywhere on the PC. The Help Content Manage is now embedded inside the VS Help Viewer application ("Manage Content"  tab).

HV2 Catalog Structure

Main files and folders that make up a VS locale store:
  • <catalog>\CatalogType.xml  -- Required to enable the adding/removing of content by the VS Content Manager (sets CatalogType=UserManaged).
  • <catalog>\ContentStore\<locale>\ -- Content folder. Stores your .mshc help files and matching .mshi index fragments.  Typically <locale> = "en-US" on an English machine.
  • <catalog>\IndexStore\<locale>\  -- Master index of all ripped data (Meta data, keywords, F1 keywords, search terms, TOC info etc). Updated whenever catalog content is added/removed/modified.

Locale (Language) Codes

What locale codes are used by Microsoft Visual Studio? 
Last time I checked there were 10 core languages (9 + En) that shipped with VS 2010 RTM.

 Language Short code LCID 
 Chinese - Taiwan (Traditional) zh-TW  0x0404 (1028) 
 Chinese - China (Simplified) zh-CN  0x0804 (2052) 
 English - US en-US 0x0409 (1033)
 French - France fr-FR 0x040C (1036) 
 German - Germany de-DE 0x0407 (1031)
 Italian - Italy It-IT 0x0410 (1040)
 Japanese - Japan ja-JP 0x0411 (1041) 
 Korean - Korea ko-KR  0x0412 (1042) 
 Russian - Russia ru-RU 0x0419 (1049) 
 Spanish - Spain es-ES  0x0C0A (3082) *

* Note that MS use modern Spanish LCID (3082) not the traditional Spanish LCID 0x040A (1034).

Other language codes used by MSDN online. There may be others but these are the main locales I've observed.

Language Short code LCID 
 Arabic - Saudi Arabia ar-SA 0x0401 (1025)
 Czech - Czech Republic cs-CZ  0x0405 (1029)
 Polish - Poland pl-PL 0x0415 (1045)
 Portuguese - Brazilian pt-BR 0x0416 (1046)
 Turkish, Turkey tr-TR 0x041F (1055)

Catalog .MSHX File

HV2 introduces an all-in-one compressed file format (almost like a .chm except it can't merge with other help files). These files contain a single .mshc help file with the associated .mshi index appended.

HelpIndexer.exe

Utility to create a .mshx file or .mshi index fragment file from a single .mshc help file.  Currently HelpIndexer.exe command line utility is only available by downloading the Windows 8 ADK. Once the ADK is installed you will find HelpIndexer.exe in the folder:  
C:\Program Files\Windows Kits\8.0\Assessment and Deployment Kit\Deployment and Imaging Tools\HelpIndexer\

ADK download location:

The .mshi index files produced by helpindexer.exe work with both HV 1.1 (VS 2010 SP1) and HV 2.0 (VS 2012).

.mshc Help File (help package)

Help files are compatible with both HV1 & HV2 help systems. Take some HTML files, add required Meta tags and zip them to a .mshc file (using WinZip or Windows Zip), and you now have a HV1/HV2 compatible help file. An MS Compiler (Workshop) isn't required since the ripping to .mshi index file is done at install time.

.mshi Index File

There are 2 types of .mshi index files. 

In a VS (managed) catalog you will find a folder <catalog>\ContentStore\<locale> where all the .mshc help files are stored. Beside each help file you will see a matching .mshi index file. These are produced when you install your help, and contain a rip of all the meta data and search terms found in the help file. Microsoft actually ship pre-ripped .mshi index files (see .cab files below) to speed up their installations.

In <catalog>\IndexStore\<locale> the Content Manager generates a single merged index containing all the catalog index fragments. This is updated whenever you add or remove a help package to a catalog. Help Manager stores this large master index as a series of smaller .mshi files.

.cab Help packages

Microsoft help is enormous, so to speed up the adding of help packages, they pre-generate the .mshi help fragment for each .mshc help file and package them into a .cab file which can then be sign and silently installed. The name of the .cab file should be the same as the name of the help and index files (minus the file extension). You can also pre-generate your own help index fragments using the HelpIndexer.exe utility 
  • Pros - .mshi makes installs faster. Signed cab files can be installed silently.
  • Cons - Signing cab files is a pain.

VS 11 Local Store Location

The default location for the VS 11 store is:

C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio11

Catalogs (as used by the VS Help Viewer) are defined in the registry. Here the default catalog "VisualStudio11" is defined.
You can define your own catalogs in a similar fashion (just replace the key VisualStudio11 with your catalog name).
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0]
"AppRoot"="C:\\Program Files\\Microsoft Help Viewer\\v2.0\\"
"DefaultHelpViewerCLSID"="{FE220E43-FE17-47BE-A57E-84D2B9A5635D}"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs]
"ContentStore"="C:\\ProgramData\\Microsoft\\HelpLibrary2\\Catalogs\\"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\VisualStudio11]
"LocationPath"="C:\\ProgramData\\Microsoft\\HelpLibrary2\\Catalogs\\VisualStudio11\\"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\VisualStudio11\en-US]
"SeedFilePath"="C:\\Program Files\\Microsoft Help Viewer\\v2.0\\CatalogInfo\\VS11_en-us.cab"
"catalogName"="Visual Studio 2011 Help Documentation"

MS are not currently shipping a 64 -bit version of the help runtime (like in VH 1.x help running on Win 7 64-bit). So on a Win 64-bit PC look in the Wow6432Node area of the registry...
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0
 
... and the 32-bit run-time files would be here:
C:\Program Files (x86)\Microsoft Help Viewer\v2.0
 
The VS 11 store can be relocated using the VS 11 Help Viewer, so there is normally no reason to modify these registry settings unless you want to register your own catalog for viewing with HlpViewer.exe (the VS 11 Help Viewer).


A registry dump from my 64-bit machine...
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help]

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0]
"AppRoot"="C:\\Program Files (x86)\\Microsoft Help Viewer\\v2.0\\"
"DefaultHelpViewerCLSID"="{FE220E43-FE17-47BE-A57E-84D2B9A5635D}"

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\Catalogs]
"ContentStore"="C:\\ProgramData\\Microsoft\\HelpLibrary2\\Catalogs\\"

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\Catalogs\VisualStudio11]
"LocationPath"="C:\\ProgramData\\Microsoft\\HelpLibrary2\\Catalogs\\VisualStudio11\\"
"LastUpdated"="08/17/2012 07:43:39"

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\Catalogs\VisualStudio11\en-US]
"SeedFilePath"="C:\\Program Files (x86)\\Microsoft Help Viewer\\v2.0\\CatalogInfo\\VS11_en-us.cab"
"catalogName"="Visual Studio 2012 Documentation"

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\Setup]
"AppRoot"="C:\\Program Files (x86)\\Microsoft Help Viewer\\v2.0\\"
"Install"=dword:00000001
"Version"="2.0.50727"

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\VSDocsShortcut]

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Help\v2.0\VSDocsShortcut\1033]
"installed"="50727"

Register a Catalog for VS 11 Viewer

Any help catalog can be viewed in VS 11 HlpViewer.exe as long as it is first registered. We do this by adding a catalog alias and associated catalog folder path to the registry.

Here a catalog alias "ACME" points to english help in the catalog folder D:\MSHelpProject\ACMECatalog\.
"catalogName"= is the name displayed in the title bar of the HlpViewer.exe application window.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\ACME]
"LocationPath"="D:\\MSHelpProject\\ACMECatalog"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\ACME\en-US]
"catalogName"="ACME Example Catalog"

    To open this catalog in HlpViewer.exe, run HlpViewer.exe /catalogName ACME

    See also "Creating a Catalog" (below) and VS 11 Help Viewer Window.

    Blow Away the Store

    Stuff happens (eg. hard disk corruption) and sometimes we may need to delete the VS 11 Help Store by hand and rebuild it.
    1. Delete or rename the old store folder (the location is in the registry - see above)
      C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio11\
    2. Create a new store folder (same name)
    3. Create the UTF-8 text file CatalogType.xml
      C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio11\CatalogType.xml
      and fill it with this text (this enables the user to add content to the catalog): 
      <?xml version="1.0" encoding="utf-8"?><catalogType>UserManaged</catalogType>
    4. Lastly open the VS 11 Help Viewer and use the "Manage Content" tab to download content.
      To open the help viewer outside of VS 11 run HlpViewer.exe /catalogName VisualStudio11

    Creating a Managed Catalog

    How to create, register and view your own catalog using HlpViewer.exe:

    1. Choose an empty folder to hold the the catalog. Mine is D:\MSHelpProject\ACMECatalog\

    2. Add to this folder a UTF-8 file text file called Catalogtype.xml  and add to it the following text:

      <?xml version="1.0" encoding="utf-8"?><catalogType>UserManaged</catalogType>

      Or copy it from another catalog folder. The file enables the catalog to be modified (Add/Remove content).

    3. Register the catalog by adding the following registry items (HlpViewer.exe can only view registered catalogs).  
      Here the key "ACME" is my "catalog alias" under which is the actual folder path of my catalog.  
      The key "en-US" has been added because my help is English. Under that is a "catalogName", a descriptive name displayed in the title bar of the HlpViewer.exe window.

      [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\ACME]
      "LocationPath"="D:\\MSHelpProject\\ACMECatalog"

      [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help\v2.0\Catalogs\ACME\en-US]
      "catalogName"="ACME Example Catalog" 

    4. Now I can open my catalog in HlpViewer.exe.

      HlpViewer.exe /catalogName ACME

    5. To add packages go to the Manage Content tab (of HlpViewer.exe) and enter the path to a .msha installation manifest file.

    Unmanaged & .MSHX Catalogs

    So far we've talked about the VS 11 "Managed" catalogs which are maintained by the VS 11 Content Manager (via the Manage tab in the VS 11 Help Viewer or the VS 11 Help Content Manager command-line utility).

    You can also create "Unmanaged" catalogs and .MSHX single help file catalogs that you maintain yourself.  These catalog types are incompatible with the VS 11 Help Viewer, and can only be opened by HV2 Help API calls.

    The code examples on this site allow you to explore and open these type of catalogs.

    "Unmanaged" Catalogs

    Windows 8 uses unmanaged catalogs and this is why HelpIndexer.exe (see above) ships with the Win 8 ADK deployment kit. IE. So you can generate the required .mshi index file.

    For Windows OEM help what happens is this... 
    1. Company X adds their .mshc help file to the folder: c:\windows\help\OEM\ContentStore\en-US\ (or fr-FR for French content etc)
    2. And the matching .mshi Index file is added to folder:  c:\windows\help\OEM\IndexStore\en-US\ 
    That's it! No other XML or catalog files are required. 

    Each OEM drops in there own .mshc/.mshi files (as above) and when the API Catalog.Open() call opens the catalog via Open("c:\windows\help\OEM", "en-US"), we see a merged help system of all content (similar to HTML Help .chm merge). But you will need a viewer (which we will be providing at some stage).

    Generating the .mshi Index

    Normally we would use the HelpIndex.exe utility to create the matching .mshi index file from the .mshc content file.  
    Note that the code examples contains a GUI interface for HelpIndexer.exe.

    Generating a .mshx 

    The 3rd type of catalog is .mshx file. These are just a single a .mshc help file with matching .mshi index appended. They cannot be merged with other help or opened in VS 11 help viewer, but can be open using the HV2 API.

    These are great for single help file systems and do not require all the folder structure of managed or unmanaged stores.
    Like other catalogs they can be located anywhere on the hard disk.

    Use the HelpIndex.exe utility to create the .mshx from the .mshc help file. 

    Last Word

    By now you are getting the picture. 

    Only VS 11 "managed catalogs" can be opened in VS HlpManager.exe and updated using the "Manager Content" tab in VS 11 Help Viewer or the VS Content Manager command line utility (we did the same in HV1 using HelpLibManager.exe). 

    If your customers have VS 11 then you can create managed catalogs, and customers can use the VS 11 Viewer & Content Manager tools to add/remove/update/View content. And remember that the access point for updates can be any web site (as long as it has the correct file content). So your customers can get quite a rich experience.

    On systems that do not have VS 11, your choice are:
    1. Run a 3rd party viewer and maintain your own "Unmanaged" catalog store.
    2. For single .mshc help create a .mshx help. Both of these are perfect for small scale application help, and can be installed into program files right along side your executables. 
    3. Large scale help (like MSDN) you would want to create managed help on your VS 11 development PC (to get the full merged index), and ship the full catalog to the customer. If the customer has VS 11 then they could use VS 11 viewer and update system. If not then they will have to rely on updating the old fashion way (an install disk or download). Managed catalogs always give you best performance.