Installation

When deploying your documentation, you need to install it on a 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/2012/2013/2015 or 2017 is installed.

2.VS 2010/2012/2013/2015 or 2017 help catalog must be installed because we want to install our help into it. This requires that VS 2010/2012/2013/2015 or 2017 help was installed during VS 2010/2012/2013/2015 or 2017 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.

Installation of MSHV 1.1 and MSHV 2.x slightly differs. But VSdocman generates a single batch file which will work with any version. So you don't have to do anything special. The following text explains in detail what's happening behind the scenes.

MS Help Viewer 1.x

The MS Help Viewer 1.x 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.

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.

MS Help Viewer 2.x

The process is similar to MSHV 1.x. But instead of  Help Library Manager (HelpLibManager.exe) used in 1.x, version 2.x uses Help Content Manager (HlpCtntmgr.exe) for installing and uninstalling the help packages. It is more powerful than HelpLibManager.exe and therefore no wrapper utility is needed to use HlpCtntmgr.exe. See a full list of command line parameters for HlpCtntmgr.

For the installation use the following syntax:

HlpCtntmgr.exe /operation install /catalogName VisualStudio11|VisualStudio12 /locale en-US /sourceUri "REAL_PATH\helpcontentsetup.msha" /wait 0

The second and third parameter uniquely identify the help catalog which the installed package will belong to. In our case it is VisualStudio11+en-US catalog which is a VS 2012 help. Use VisualStudio14 for VS 2014 and VisualStudio12 for VS 2013. The /sourceUri parameter specifies the path to our manifest file which contains all information necessary for installation. Unfortunately, when installing this way, the HlpCtntmgr.exe will show a prompt to confirm the installation.

Confirm installation with Yes button. The installation starts to merge indexes. This may take some time.

Uninstallation

For the uninstallation use the following syntax:

HlpCtntmgr.exe /operation uninstall /catalogName VisualStudio11|VisualStudio12 /locale en-US /vendor "Helixoft"  /productName "TestDLL Reference" /bookList "TestDLL Reference" /wait 0

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

MS Help Viewer 2.x and 1.x

In previous, the differences between MSHV 1 and 2 were described. Now we are back and the following applies to all MSHV versions.

Silent installation

As you can see, approach mentioned above 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 above-mentioned command lines but append also /silent switch at the end.

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.

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 for MSHV 1.x.

register_PROJECT_NAME.bat - it determines which MSHV version is installed and simply calls HlpCtntmgr.exe or HelpLibManagerLauncher.exe utility with proper arguments. All you need to do is to call it during installation.

unregister_PROJECT_NAME.bat - when user uninstalls your component, you should also uninstall the documentation. Again, this script can do it for you. It it determines which MSHV version is installed and simply calls HlpCtntmgr.exe or HelpLibManagerLauncher.exe utility with proper arguments. You should call it from your uninstaller.

PROJECT_NAME.mshc - MS Help Viewer package file. If you need silent installation, pack this file in signed CAB and edit helpcontentsetup.msha accordingly.

helpcontentsetup.msha - MS Help Viewer manifest file.

All you need to do is to copy all those files in one folder on a target machine and call register_PROJECT_NAME.bat during installation. Or use commands from this script and call them directly.

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

Customizing MSHA manifest file

The generated helpcontentsetup.msha file contains information about the book and package(s) to be registered. VSdocman fills all data automatically. There's however the vendor tag with the default "VendorName" value. You can change this value to your company's name or anything else. Just be sure not to use any underscore characters (_) there. There is a bug in MS Help Viewer 2.0 and higher (VS 2012+). When there's an _ character, the registration will execute OK but you will not be able to see any contents in the help.

 

Distribution Policy

You can distribute your documentation with HelpLibManagerLauncher.exe utility only if you are registered user of VSdocman. You cannot distribute HelpLibManagerLauncher.exe if you are using evaluation (trial) or beta version of VSdocman.

Registered users can distribute HelpLibManagerLauncher.exe royalty-free but only with documentation generated by VSdocman or with documentation which contains parts generated by VSdocman.

See Also