Microsoft Help Viewer 1.0 is the format used in VS Help and MSDN for VS version 2010 and higher. After you generate MS Help Viewer (.msh? files) documentation you cannot view it immediately by pressing Show Documentation button on compilation dialog.

MS Help Viewer documents must be installed first. After that you can view them in VS help.

Unlike e.g. HTML Help with one CHM file, MS Help Viewer documentation usually consists of two files:

• MSHC...compiled help
• MSHA...product manifest

When VSdocman generates your MS Help Viewer files, it automatically registers (installs) them on your computer. See Deploying section below.

By installing your documentation in MS Help Viewer system we mean:

1. Your documentation will be accessible in MS Help Viewer system as a new book.
2. Your help is plugged in Visual Studio help catalog so that it is visible in VS help. That means you will see your help in Contents, your items will be in Index and you can perform search on your help.
3. Your help is integrated in VS dynamic F1 help.

Note: By default, it is not possible to install MS Help Viewer documentation silently. So a Help Library Manager window will pop-up after generating the help and you must manually confirm the installation. To install help silently on target computer, you must create signed CAB file, see Deploying section below.

For more information, read Getting Started with MS Help Viewer.

Viewing

After you install your documentation, you can see it in VS Help. By default, VS Help opens in your default web browser. You should see your help in Contents, your items will be in Index and you can perform search on your help. However, viewing in browser provides only limited functionality - no full TOC, no Index. So you can use 3rd party viewer:

• H3Viewer.exe - A free viewer by Helpware, Standalone viewer like DExplore; Full TOC; Full Index; Multi-tab.
• HelpViewerKeywordIndex - By the MS Help team. Integrates into VS IDE. Provides search and index.
• Help Viewer Power Tool - A free tool which adds keyword index capability to the Help Viewer with an option to display help in a standalone window.

An F1 help should work as well.

Here is a sample of MS Help Viewer topic shown in H3Viewer:

When you recompile your help, it needs to be installed again which may take several minutes. Therefore we recommend you to compile HTML Help 1.x (chm_msdn2) documentation for test purposes and use MS Help Viewer format when you are satisfied with your documentation.

Installation

When deploying your documentation you need to install it on the target computer. This assumes that the following conditions are met:

1. The MS Help Viewer runtime must be installed. It is automatically installed when VS 2010 is installed.
2. VS 2010 help catalog must be installed because we want to install our help into it. This requires that VS 2010 help was installed during VS 2010 installation or separately later.

As already mentioned, VSdocman generates two files - PROJECT_NAME.mshc and helpcontentsetup.msha. Remember that you cannot rename helpcontentsetup.msha, otherwise the installation would fail.

The MS Help Viewer runtime contains Help Library Manager (HelpLibManager.exe) which is used for installing and uninstalling the help packages. It works in GUI mode (if invoked for example from VS Help menu) and command line mode. We will use the command line mode. See a full list of command line parameters for HelpLibManager.

For the installation use the following syntax:

HelpLibManager.exe /product "VS" /version "100" /locale "en-us" /sourceMedia "REAL_PATH\helpcontentsetup.msha"

The first three parameters uniquely identify the help catalog which the installed package will belong to. In our case it is VS+100+en-us catalog which is VS 2010 help. The /sourceMedia parameter specifies the path to our manifest file which contains all information necessary for installation. Unfortunately, when installing this way, the HelpLibManager.exe will show in GUI mode. It will automatically add specified help package in the list of packages but you need to manually finish the installation. The following picture shows this dialog for "TestDLL Reference" help package.

You need to click the Add link next to installed package.

Press Update button after that. An alert will appear.

Confirm installation with Yes button. The installation starts to merge indexes. This may take some time. You can exit Help Library Manager when the help is installed.

Important: When you attempt to install newer version of already installed package, the installation has no effect. So it's recommended to always uninstall before installation. Uninstalling not installed package doesn't cause any problems.

Silent installation

As you can see, this approach requires user intervention. However, it is possible to install silently but you need to use signed CAB files. The CAB file is used instead of MSHC file.

1. Pack your generated .mshc file into the .cab file with the same name and sign it. See How to generate signed .cab file from your .mshc file.
2. Open your generated helpcontentsetup.msha file in a text editor and change .mshc to .cab in it.
3. For installation use abovementioned command line but append also /silent switch at the end.

Uninstallation

For the uninstallation use the following syntax:

HelpLibManager.exe /product "VS" /version "100" /locale "en-us" /uninstall /silent 
  /vendor "Helixoft" /mediaBookList "TestDLL Reference" /productName "TestDLL Reference"

Unlike the installation, the uninstallation works in silent mode even when no signed .cab files were used. The first three parameters uniquely identify the help catalog which the package will be uninstalled from. The /vendor, /mediaBookList and /productName were specified in generated helpcontentsetup.msha file during installation.

HelpLibManagerLauncher

When you install your documentation on target computer, you need to take care of the following:

1. Find path to HelpLibManager.exe. Handle situation when it is not found which means that MS Help Viewer runtime is not installed.
2. Detect if HelpLibManager.exe is already running. If yes, the user must close it first.
3. Detect installed locale of specified catalog. The /locale parameter is required for both, installation and uninstallation. For English VS help it is en-us but we cannot rely on it. There are various language versions of VS help or any other help catalog.
4. When installing, the HelpLibManager.exe needs to "run as administrator". This is not necessary when uninstalling.

Therefore we developed small command line tool HelpLibManagerLauncher.exe that does all the job. It simply calls HelpLibManager.exe but before this, it takes care of the abovementioned issues. Registered users of VSdocman can distribute it with their documentation.

Files to Deploy

As already mentioned, MS Help Viewer documentation consists of several files. You need to distribute all of them to other computers. VSdocman prepares deployment ready directory with all necessary files in output_path/FINAL_HV10_DOC folder:

• HelpLibManagerLauncher.exe - help installation utility.
• register_PROJECT_NAME.bat - it simply calls HelpLibManagerLauncher.exe utility with proper arguments. All you need to do is to call it during installation. Make sure you specify a correct full path to your .msha file in it.
• unregister_PROJECT_NAME.bat - when user uninstalls your component, you should also uninstall the documentation. Again, this script can do it for you. It simply calls HelpLibManagerLauncher.exe utility with proper arguments. You should call it from your uninstaller.
• PROJECT_NAME.mshc - MS Help Viewer package file.
• helpcontentsetup.msha - MS Help Viewer manifest file.

All you need to do is to copy all those files in one folder on target machine and call register_PROJECT_NAME.bat during installation. Or use commands from this script and call them directly. This is probably preferred method because generated script file doesn't contain correct full path to your .msha file.

When user uninstalls your component, you should also uninstall the documentation. Just call unregister_PROJECT_NAME.bat from your uninstaller.

View and Deploy HTML Help 1.x Documentation | View and Deploy HTML Documentation | View and Deploy Help & Manual Documentation | View and Deploy Solution Documentation | View and Deploy Context Help