FAQ‎ > ‎

How to Install Help

Let's look at how to install our help packages into MS Help Viewer.

Preparation

  1. Compile your .mshc help files.
  2. Optionally you can wrap each .mshc help file in .cab file and sign the .cab file.
  3. Create a .msha manifest file to define your book and its packages.
Most of this can be achieved using the free mshcMigrate utility.
Note that for MS Help Viewer 1.0 the manifest file must have the name "helpcontentsetup.msha".

Installation

On the surface installation is simple. After installing your help files to the hard disk, run HelpLibManager.exe passing your help manifest file via the command line.

HelpLibManager.exe /product VS /version 100 /locale en-us /silent /sourceMedia "c:\path\helpcontentsetup.msha"

/product VS /version 100 /locale en-us -- represents the target catalog (VS\100\en-us).
/install /sourceMedia "c:\path\helpcontentsetup.msha" -- tells HLM to install help using the specified .msha manifest file.
/silent -- is optional and only works with signed content.

Note: Pre-RTM builds also had a /install switch. However this is no longer required now since /sourceMedia or /sourceWeb is enough to indicate an install.

We need to find the location of HelpLibManager.exe as well as the VS Help catalog locale. VS 2010 help catalog is always VS\100\<locale>.
So for advanced installations we will need the help of a programmer to write some custom code (an installation helper) that our Setup.exe can run.

Installation Helper
Your installer will need to do the following:
  1. Find the location of HelpLibManager.exe. Report if MS Help Viewer is not install (HLM not found).
  2. If HLM is already running we need to ask the user to close it (after letting any current activity complete). Only one install can run at a time.
  3. Sniff out the current catalog locale so we can install into the correct language version of the VS\100\<locale> catalog.
  4. Finally run HelpLibManager.exe specifying your .msha manifest on the command line (see example above).
That's it. HLM is part of MS Help Viewer 1.0. The /sourceMedia install switch copies the help files into the Help Library Store, indexes your help (if you didn't supply an .mshi index file) and merges your help with the catalog master index. 

NOTE: If help is already installed then /sourceMedia install has no effect, even if the help file is newer. So as general rule I suggest you always run HLM /uninstall /silent before using HLM /install.

Location of HelpLibManager.exe
To find the location of HelpLibManager.exe you can look in the registry. 

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help]
"AppRoot"="C:\\Program Files\\Microsoft Help Viewer\\v1.0\\"
"LocalStore"="C:\\ProgramData\\Microsoft\\HelpLibrary\\"

But since HV 1.0 is always installed to the same location you could simply run...

%programfiles%\Microsoft Help Viewer\v1.0\HelpLibManager.exe

Detecting the current help documentation language

We can't really assume that VS Help will always be en-us (well unless your install disk is clearly labeled "For VS 2010 English Only").

The main help catalog for VS help is called VS\100\en-us. On French PC this may be VS\100\fr-fr. etc.
As help integrators we need to sniff out the locale of the VS help catalog.
Microsoft test and ship 10 different languages for VS. See http://mshcmigrate.helpmvp.com/news/languageandbranding

Paul O'Rear [MSFT]: 
There is currently no formal way to find all installed language versions. 
Look for all instances of the AppID’s satellite DLL, located in <VS Install Directory>\Common7\IDE\<LCID> 
(e.g., {PF}\Microsoft Visual Studio 10.0\Common7\IDE\1033\msenvmui.dll).

Rob: 
You could also look into the Library Data Store since all Microsoft documentation files are marked with "en-us" type identifier. Even an empty catalog will contain the HelpOnHelp package, so this should be a reliable way to find the language id.

5-Feb-2011:  Paul O'Rear [MSFT]: 
For Visual Studio SKUs, you can sniff languages that are installed using the following keys: 
(32-bit OS)
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DevDiv\vs\Servicing\10.0\$(var.ProductEdition)\$(var.LCID)
(64-bit OS)
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\DevDiv\vs\Servicing\10.0\$(var.ProductEdition)\$(var.LCID)

Where var.ProductEdition can be: 
Visual Studio 2010 Ultimate:              VSTSCore
Visual Studio 2010 Premium:             VSTDCore
Visual Studio 2010 Professional:         PROCore
Visual Studio 2010 Shell (Integrated):  IntShell
Visual Studio Express: ??

Source: 

Help Library Manager (HLM) Exit Codes
When you run HelpLibManager.exe /silent (install or uninstall), HLM runs with no visible User Interface.
On completion HLM automatically closes and returns an exit code telling you how successful install or uninstall was. The exit code tells you if HLM was succeeded or not.

If your content is unsigned then silent mode is unavailable and exit codes wont be of much use (since your users will be installing help manually). Exit code are listed on the FAQ page.

Help Library Store not initialized
There is a situations you should be aware of. If the user installed VS 2010 without pressing the Blue documentation button, then help wont be initialized (although runtime executables will be). The Library store path is defined in the registry, however the Library path wont actually exist yet. And the VS\100\<locale> catalog wont have been created.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Help]

"LocalStore"="C:\\ProgramData\\Microsoft\\HelpLibrary\\"


By simply running HLM VS\100\<locale> + install params... This will show the user the customary HLM window to select the Library path, and create the VS\100\<locale> catalog (along with the Help On Help default package). If the user selects a location other than the default, then the "LocalStore" registry path will be updated to reflect the change.

Note that the Blue button that installs the VS documentation, specifies the Dev10 branding package on the HLM command line. This gives VS it's customary branding ... This includes the VS logo and feedback links for each topic. I think you also get that special VS Home page as well.

To ensure your users see the customary VS Branding for the VS\100\<locale> catalog, please add the "/brandingPackage dev10.mshc" params to your HLM command line.

"%programfiles%\Microsoft Help Viewer\v1.0\HelpLibManager.exe" /product VS /version 100 /locale en-us /brandingPackage dev10.mshc

Silent Install with Uninitialize Library
Caveat: 
If you run HLM in silent mode (and Library store is uninitialized), then library store initialization will fail. So your installation will fail. 

For this case I see 3 options. So once you detect an unintialized Library condition you can either:
  1. Cancel setup. Inform the user they first need to complete documentation set using VS Setup & the Blue button.
  2. Open HLM without the /silent switch. Include /brandingPackage switch (see above). Once Initialization is completed you can run your silent install.
  3. Open HLM with the /silent switch. You must also use the /content switch which specifies where to create the library folder. You can specify the /brandingPackage, the /content and the /sourceMedia switches all on the same command line. 
Note that for 3) you can get the default /content path by reading LocalStore= from the registry (see FAQ page).

Oh one more problem. Apparently if you use /content path on Windows XP, the path will contain spaces and will require quotes around it. However the quotes make the command fail (a bug). My only suggestion here is to use the short path name for the path segment containing the space. Programmers will know how to do this.

Uninstall
To uninstall help call HLM with the /uninstall /silent switches (works with both signed and unsigned content). 
The names you used in the .msha manifest during installation are now passed via the command line using the /vendor, /mediaBookList, /productname switches.

HelpLibManager.exe /product VS /version 100 /locale en-us /uninstall /silent /vendor "ACME" /mediaBookList "Name of My Book" /productName "Name of My Product"

Again as a general rule I suggest you always use /uninstall /silent before using /install.

FAQ

What if Help Library manager is already running?
You should detect if HLM is already running. Programmers can do this by searching for the process (see C# code below). Don't use FindWindow() since in silent mode there is no window to find. If HLM is running you should ask the user to let the current task finish, then close HLM so that installation can continue. Since Windows usually restricts you to running one installation at a time you generally wont have a problem with multiple apps trying to run HLM at the same time.

// Get all instances of HLM running on the local
// computer. If you get any processes back then you know HLM is running.
Process [] localByName = Process.GetProcessesByName("HelpLibManager");

Why wont my help update?

You need to first uninstall the existing help then add the new help otherwise the updated help wont merge.

[paorear] Correct. There are some exceptions to this in a scenario we describe as an Enterprise install, where a local update server could be used to redirect where updates are looked for and downloaded from, but this will not be a common scenario for most VSIPs. If I’m wrong, let me know!

[rob] Suggest you always run HelpLibManager.exe /uninstall /silent before running install. That way any updates of existing help will be successful. This is very quick to do. Also note that some developers may be experimenting by using multiple catalogs. In this case the help needs to removed from all catalogs before updating.

Other Notes

  • Signing
    • Only signed help can be install silently (using the /silent switch). 
    • When signing make sure your .cab\.mshc\.mshi files all have the same base file name.
    • To sign your help, you must ship each .mshc help file in its own .cab package.
    • Paul O'Rear's "The Help Guy" weblog has some good tips on signing help:
    • Microsoft are now saying they recommend companies use non-silent install (interactive install). 
  • Shipping and Index
    • Signed .cab files can optionally contain an index (.mshi) file. This can speed up installation (since no ripping phase). See Add an Index to your .Cab Help Package.
    • Microsoft themselves do ship .mshi Index files with all their .cab packages. For HV 1.0 Microsoft are not expecting 3rd parties to ship indexes.
  • Uninstall
    • Uninstall always requires the silent switch (/uninstall /silent). 
    • Uninstall does not require signing.
  • Unsigned Help
    • .Cab and Indexes (.mshi) not allowed. 
    • Install (with no /silent) shows the Help Library Manager window and waits for user responses. 
    • A poll I ran in our MSHelpViewer Yahoo Group suggests that most companies wont be signing their help.
  • Other
    • For Visual Studio 2010 English the target catalog is VS\100\en-us.


Comments