Unlike HTML Help 1 (CHM) files, an MS Help Viewer package or book must be installed in order to view it. This makes deploying MS Help Viewer documentation more complex than simply delivering a single file and creating a shortcut to it. However, it is much simpler than its predecessor, MS Help 2.

Tip
Due to the requirement that MS Help Viewer files be installed before you can view them which can be time consuming, it is recommended that you generate one of the other help formats such as Help 1 or website while developing and proofreading your help file.

When producing an MS Help Viewer file, the help file builder produces a valid help content setup file suitable for use by the Help Library Manager. It also includes a Help Library Manager launcher utility that takes care of the standard housekeeping tasks required when installing and removing MS Help Viewer content. It is a command line tool that can be included by scripted installers as well as Windows Installer packages as a custom action. In order to deploy the generated MS Help Viewer file, follow these steps:

1. Set the MS Help Viewer project properties as needed. At the minimum, you should set the Vendor Name and Product Title properties to something other than their default values.

2. Build the help project.

3. In order to install an MS Help Viewer file, a help content setup file is required. The help file builder automatically creates a help content setup file for you named after the help file but with a .msha extension. This allows you to build and deploy multiple MS Help Viewer files to the same location.

   Important
   For MS Help Viewer 1.0, the name of the help content setup file used during installation must be HelpContentSetup.msha. If you only have one help file, you can rename the setup file created by the help file builder to HelpContentSetup.msha. If you have multiple help files, you can rename one of the setup files and merge the package information from the others into it.

4. Include all of the generated help files (the .mshc files) as well as the HelpContentSetup.msha and the HelpLibraryManagerLauncher.exe executable in your installer.

5. During installation, copy the help files, the help content setup file, and HelpLibraryManagerLauncher.exe to their installed location.

6. Execute the Help Library Manager launcher or a script to install the help file. This step will vary based on whether or not you are using signed cabinet files to deploy your help content. Note that silent installs are only allowed with signed cabinet files. For unsigned files, the Help Library Manager will always appear and confirm the installation. Below is an example of the script that the help file builder creates to install the help file (lines wrapped for display purposes).

   Copy

   @ECHO OFF
   CLS
   
   REM This is an example script to show how to use the Help Library Manager
   REM Launcher to install an MS Help Viewer file.  You can use this as an example
   REM for creating a script to run from your product's installer.
   
   REM NOTE: If not executed from within the same folder as the executable, a full
   REM path is required on the executable and the HelpContentSetup.msha file.
   
   IF "%1%"=="H2" GOTO HelpViewer2
   IF "%1%"=="h2" GOTO HelpViewer2
   IF "%1%"=="H21" GOTO HelpViewer21
   IF "%1%"=="h21" GOTO HelpViewer21
   
   REM Help Viewer 1.0
   REM Uninstall first in case it is already there.  If not, it won't install
   REM below.  We'll ignore any error output by redirecting it to NUL.
   HelpLibraryManagerLauncher.exe /product "VS" /version "100" /locale en-us
           /uninstall /silent /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /mediaBookList "Sandcastle Test Case Library" > NUL
   
   REM For Help Viewer 1.0. the setup name must be HelpContentSetup.msha so make
   REM sure we copy the setup file to that name.  SHFB names it after the help
   REM file so that multiple files can be deployed to the same output older at
   REM build time.
   IF EXIST "TestCaseProject.msha" COPY /Y "TestCaseProject.msha" HelpContentSetup.msha
   
   REM Install the new content.
   HelpLibraryManagerLauncher.exe /product "VS" /version "100" /locale en-us
           /sourceMedia "%CD%\HelpContentSetup.msha"
   
   GOTO Exit
   
   :HelpViewer2
   
   REM Help Viewer 2.0
   REM Uninstall first in case it is already there.  If not, it won't install
   REM below.  We'll ignore any error output by redirecting it to NUL.
   HelpLibraryManagerLauncher.exe /viewerVersion 2.0 /catalogName VisualStudio11
           /locale en-us /wait 0 /operation uninstall /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /bookList "Sandcastle Test Case Library" > NUL
   
   REM Install the new content.
   HelpLibraryManagerLauncher.exe /viewerVersion 2.0 /catalogName VisualStudio11
           /locale en-us /wait 0 /operation install /sourceUri "%CD%\TestCaseProject.msha"
   
   GOTO Exit
   
   :HelpViewer21
   
   REM Help Viewer 2.1
   REM Uninstall first in case it is already there.  If not, it won't install
   REM below.  We'll ignore any error output by redirecting it to NUL.
   HelpLibraryManagerLauncher.exe /viewerVersion 2.1 /catalogName VisualStudio12
           /locale en-us /wait 0 /operation uninstall /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /bookList "Sandcastle Test Case Library" > NUL
   
   REM Install the new content.
   HelpLibraryManagerLauncher.exe /viewerVersion 2.1 /catalogName VisualStudio12
           /locale en-us /wait 0 /operation install /sourceUri "%CD%\TestCaseProject.msha"
   
   :Exit

7. During uninstallation, before the help files are removed, execute the Help Library Manager launcher to uninstall your help file. Below is an example of the script that the help file builder creates to remove the help file (lines wrapped for display purposes).

   Copy

   @ECHO OFF
   CLS
   
   REM This is an example script to show how to use the Help Library Manager
   REM Launcher to remove an MS Help Viewer file.  You can use this as an example
   REM for creating a script to run from your product's uninstaller.
   
   REM NOTE: If not executed from within the same folder as the executable, a full
   REM path is required on the executable.
   
   IF "%1%"=="H2" GOTO HelpViewer2
   IF "%1%"=="h2" GOTO HelpViewer2
   IF "%1%"=="H21" GOTO HelpViewer21
   IF "%1%"=="h21" GOTO HelpViewer21
   
   REM Help Viewer 1.0
   HelpLibraryManagerLauncher.exe /product "VS" /version "100" /locale en-us
           /uninstall /silent /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /mediaBookList "Sandcastle Test Case Library"
   
   GOTO Exit
   
   :HelpViewer2
   
   REM Help Viewer 2.0
   HelpLibraryManagerLauncher.exe /viewerVersion 2.0 /catalogName VisualStudio11
           /locale en-us /wait 0 /operation uninstall /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /bookList "Sandcastle Test Case Library" > NUL
   
   GOTO Exit
   
   :HelpViewer21
   
   REM Help Viewer 2.1
   HelpLibraryManagerLauncher.exe /viewerVersion 2.1 /catalogName VisualStudio12
           /locale en-us /wait 0 /operation uninstall /vendor "EWSoftware"
           /productName "Sandcastle Help File Builder Example Project"
           /bookList "Sandcastle Test Case Library" > NUL
   
   :Exit

Your product's installer can create a shortcut to open your Help Viewer file by executing the following command (lines wrapped for display purposes):

"ms-xhelp:///?method=page&id=57301AAE-7D51-4006-A9EF-C82B6C0FF21E&product=vs&
productversion=100&locale=en-us"

Substitute the ID of a page in your product's help file and adjust the product, version, and locale as needed in the example above. See the Getting Started with HV 1.0 page at the HelpWare Group website for more information on installing help files and viewing help content. A standalone viewer (H3Viewer.exe) is also available there.

Other Resources