Deploying an MS Help Viewer File

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.

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 Launcher
   REM to install an MS Help Viewer file.  You can use this as an example for creating
   REM a script to run from your product's installer.
   
   REM NOTE: If not executed from within the same folder as the executable, a full path
   REM is required on the executable and the HelpContentSetup.msha file.
   
   IF "%1%"=="" GOTO MissingVersion
   IF "%1%"=="1.0" GOTO HelpViewer1
   
   GOTO HelpViewer2:
   
   :HelpViewer1
   
   REM Help Viewer 1.0
   REM Uninstall first in case it is already there.  If not, it won't install below.
   REM 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 sure
   REM we copy the setup file to that name.  SHFB names it after the help file so that
   REM multiple files can be deployed to the same output older at 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.x
   REM Uninstall first in case it is already there.  If not, it won't install below.
   REM We'll ignore any error output by redirecting it to NUL.
   HelpLibraryManagerLauncher.exe /viewerVersion %1 /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 %1 /locale en-us /wait 0
       /operation install /sourceUri "%CD%\TestCaseProject.msha"
   
   GOTO Exit
   
   :MissingVersion
   ECHO A help viewer version parameter is required
   
   :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 Launcher
   REM to remove an MS Help Viewer file.  You can use this as an example for creating
   REM a script to run from your product's uninstaller.
   
   REM NOTE: If not executed from within the same folder as the executable, a full path
   REM is required on the executable.
   
   IF "%1%"=="" GOTO MissingVersion
   IF "%1%"=="1.0" GOTO HelpViewer1
   
   GOTO HelpViewer2
   
   :HelpViewer1
   
   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.x
   HelpLibraryManagerLauncher.exe /viewerVersion %1 /locale en-us /wait 0
       /operation uninstall /vendor "EWSoftware"
       /productName "Sandcastle Help File Builder Example Project"
       /bookList "Sandcastle Test Case Library"
   
   GOTO Exit
   
   :MissingVersion
   ECHO A help viewer version parameter is required
   
   :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.