H2Reg Home Page

Contents

See Also: | MS Help H2 Info Page | FAR Home Page |

Windows Vista UAC. What is it?
This article is important to read if you are migrating your install setup to Windows Vista.

- H2Reg & Windows Vista Compatibility

Download

Last Update:  V1.6.0, 3pm, 6-Jan-2007 (EST Australia)

Version Download H2Reg.EXE Web Site
H2Reg
1.6.0		 h2reg_setup160.exe
(536KB)		 Helpware.net

| Change Notes | Get the DLL version of H2Reg |

 

About H2Reg Install

By default H2Reg is installed under the folder c:\program files\Helpware\H2Reg\.
H2Reg install actually uses H2Reg.exe to plug it's documentation into any VS .NET collection it can find on your PC. So this is a good working demonstration of how the H2Reg registration system works. You will also find a .CHM version of H2Reg help in this folder.

To add H2Reg registration to your own project simply copy the installed H2Reg.exe, H2Reg.ini and H2Reg_cmd.ini to the folder containing your help file(s) and modify H2Reg_cmd.ini so that your help files are registered (see script example).

 

Download the latest Beta:  V1.7.0, 12am, 27-Jun-2007 (EST Australia)

Beta Version Download H2Reg Beta Web Site
H2Reg
1.7.0		 h2reg_setup170.exe
(543KB)		 Helpware.net

| Change Notes |

 

Download Old Versions:

Description

H2Reg.exe is a small utility (180K), that allows you to register MS Help 2.x Collections: Namespaces, Titles, Plug-ins, and Filters without using MSI (Microsoft Installer). Unlike the MS MSI solution, registration using H2Reg is very straight forward. Here's how we register a collection using H2Reg.exe:

  1. Create a H2Reg.INI Command Script file (contains registration commands - View example script file). See Note#1.
  2. Install H2Reg.exe, H2Reg.ini and a command script file, with your MS Help 2 (.Hx?) files.
  3. Configure your installer to run "H2Reg.exe -r" during installation, which registers your H2 documentation.
  4. Configure your installer to run "H2Reg.exe -u" during uninstallation, which unregisters the H2 documentation.

That's it. All you need is a flexible installer program that allows you to include the command "H2Reg.exe -r" (register) at the end of the install section and "H2Reg.exe -u" (unregister) at the start of it's Uninstall.

Special thanks to MS Help team members, and also Mr Michael Waltuch from ESRI for the valuable assistance in getting H2Reg off the ground.

H2Reg.DLL, H2RegLib.DLL

We also have a DLL version of H2Reg.exe. Very useful for developers who need to code highly customized installations.

FAR HTML (Note#1)

FAR 3.3.16 can now generate a H2Reg command script file from an existing H2 collection. To do this:
 
  1. Open the FAR H2 Utilities window
  2. Select the namespace(s) you want to export
  3. Right-click the namespace(s) and select "H2Reg Export" from the popup menu.
  4. Open the script file using Notepad and check and fine tune the registration settings.

FAR can also Execute (Import) a H2Reg script file, just like H2Reg.exe can. Thus you can use FAR to create and test your script files. You can also use it to backup your collections. EG. Before experimenting on MS.VSCC, export the registration info to a H2Reg command script file. Thus you can quickly restore the MS.VSCC collection should it become corrupted during your testing. The alternative is usually to reinstall VStudio.

Also note that FAR contains MS Help 2 Collection Wizards which make creating collection level Hx files and H2Reg script very simple.

INNO Installer (an excellent free installer)

We used the free INNO installer to package the H2Reg download. During installation, Setup registers our H2 document files under the Namespace "hw.H2Reg". It registers a Filter under "hw.h2reg", and even performs a plug-in of "hw.h2reg" into the VS .NET help collection "ms.vscc" (VS 7.0), or "ms.vscc.2003" (VS 7.1), or "ms.vsipcc.v80" (VS 2005), or "ms.vsipcc.v90" (VS 2008)  whatever is found. Notice that the filter appears in the MS.VSCC since we have plugged into that collection. Then when you uninstall, it unregisters what was registered. H2Reg documentation also comes in .CHM file format.

Wise for Windows Installer 4.02 Professional Edition

Tim Hitchings from Infragistics has kindly written some instructions to help Wise users.

NDOC

NDoc is a free utility for generating class library documentation from .NET assemblies and the XML documentation files generated by the C# compiler. NDoc users add-on documenters to generate documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-online style web pages.

The following article by Fons Sonnemans describes how to Integrate NDoc HTML Help 2 into Visual Studio.NET with the help of H2Reg.

The NDOC web site describes how to setup NDOC to generate H2Reg script.

West Wind Html Help Builder 4.0 (beta 2)

Rick Strahl from West Wind Technologies describes

Doc-O-Matic

Doc-O-Matic is another popular authoring tool that uses H2Reg

MSI (Microsoft Installer)

If you create a .MSI install package using say Visual Studio 2005 (a Setup Project) then you can specify a "Custom Actions" to run H2Reg.exe on install and uninstall. Just remember that H2Reg.exe is now marked to run in elevated mode, so execution will can fail because MSI impersonation is on by default. Simplest fix is to create a Setup.exe file to launch your .MSI file. Setup.exe will run in elevated mode and so will the .MSI so any elevated helpers (shuch as H2Reg.exe) will also run correctly. More info here on elevating execution and Windows Vista.

 

Support Groups
Troubleshooting

Here are some typical registration problems. Currently there are no known problems with H2Reg.exe itself.

  1. a) My TOC does not appear in Master collection after plugging in.
    b) Registration works on the development machines only. Plug-in fails on customer machines.

    Collection level .Hx? files must not contain reference to a DTD file.
    The customer wont have VSHIK installed and thus wont have the DTD files.

    See H2 Collection Tutorial - 3.6 Do Not Add the DTD
     
  2. MSI & Corruption.

    Unfortunately it happens. MSI (MS Installer) can screw up and stop the customer from repairing/uninstalling/reinstalling parts of VS. Although not a H2Reg problem a damaged VS installation can stop H2 Registration from working correctly. Often the only way forward is to remove VS or the Help 2 Engine by force and reinstall VS.

    See MS Help Wiki: Visual Studio 7.x Installation Problems
     
  3. H2Reg gives a "locked by another process" error.

    The H2 registration API calls can only do one thing at a time on a Windows system.
    Every time you register something the calls are
    1. Lock (Start H2 Transaction)
    2. Perform one or more registrations
    3. UnLock (End H2 Transaction)

    Problems occur when another Windows application attempts to perform a registration call during step 2. If this occurs applications such as H2Reg and FAR will keep trying until they eventual Time-out with a message "locked by another process".

    We find this problem typically arises when your installer runs H2Reg.exe in "NoWait Mode" or attempts to run more than one program (that makes H2 API calls) at once. The solution inevitably is set your Installer to run H2Reg.exe in "Run and wait mode". Clearing this error may requires a reboot.
     
  4. Another "locked by another process" error.

    H2 API can get itself confused and not release locked files even after a reboot:  see H2 Posts
     
  5. Disappearing TOC

    One of our clients reported the disappearing TOC problem could be caused by registering a collection with an empty TOC under VS 2002 (they plugged other collections into that collection). They found that installing .NET Framework 1.1 SDK updates the help from V2.1 to V2.2 and fixes the problem. Obviously Help 2.2, which is normally installed by VS 2003 is more stable. See also H2 Registration help
     
  6. Some Attributes I declared don't work

    In the H2Reg documentation Tim Grantham from Themo picked up an unusual problem. Index.htm uses a HTML comment in the XML data Island. Although the compiler allows this syntax, the effect is that those attributes with Names used more than once are effectively neutralized (as if they had never been declared). So please refrain from using HTML comments in your XML data islands. The problem was discovered in VS 2003 and has been reported to the MS Help team.

    <xml>
    ...
    <!-- VS Studio Attributes -->
    <MSHelp:Attr Name="Information Type" Value="Orientation"/>
    <MSHelp:Attr Name="Information Type" Value="Reference"/>
    <MSHelp:Attr Name="DocSet" Value="Visual Basic"/>
    <MSHelp:Attr Name="DocSet" Value="Visual Studio"/>
    <MSHelp:Attr Name="TargetOS" Value="Windows"/>
    <MSHelp:Attr Name="Locale" Value="kbEnglish"/>
    <MSHelp:Attr Name="LinkGroup" Value="GettingStarted"/>
    </xml>
     
  7. No DExplore auto-detect merge under VS 2005 Beta 2  [2005-06-25]

    Watch out for this one. Under VS 2005 Beta 2 only, you need to force a merge so that your collection can be viewed. Most of us depend on DExplorer performing an auto-detect/merge after we register our collection. VS 2005 RTM (Release to Manufacturing) version is OK and will auto merge. See FAQ for more.
     
  8. VS 2005 - Where's my TOC?

    We noticed that under VS 2005 RTM our Table of Contents would not display (merge) in the VS 2005 collection TOC. Well actually the introduction page displayed OK in the TOC but no other pages. On closer examination we found that only the introduction page had a full complement of XML data island elements. After adding these XML tags to the other pages, all H2Reg help topics appeared correctly in the VS 2005 TOC. Obviously VS 8 is more fussy about attributes. This is the reason for the H2Reg v1.4.4 minor update.

    Here is the XML data Island we placed in the header of each topic of our help. Obviously the two Title items must be adjusted for each topic and you wont need our Helpware Attribute item:

    <xml>
    <MSHelp:TOCTitle Title="H2Reg Template"/>
    <MSHelp:RLTitle Title="H2Reg Template"/>
    <MSHelp:Attr Name="helpware" Value="h2reg"/>
    <MSHelp:Keyword Index="F" Term="VS.Ambient"/>
    <MSHelp:Attr Name="Information Type" Value="Orientation"/>
    <MSHelp:Attr Name="Information Type" Value="Reference"/>
    <MSHelp:Attr Name="DocSet" Value="Visual Basic"/>
    <MSHelp:Attr Name="DocSet" Value="Visual Studio"/>
    <MSHelp:Attr Name="TargetOS" Value="Windows"/>
    <MSHelp:Attr Name="Locale" Value="kbEnglish"/>
    <MSHelp:Attr Name="LinkGroup" Value="GettingStarted"/>
    </xml>
     
  9. VS 2005 Pre-Merge [2006-05-03]

    Here is H2Reg script required to pre-merge a VS 2005 collection at registration time. We found that both MS.VSIPCC.v80 and MS.VSCC.v80 need to be merged. Otherwise you will still see the merge update message when you open the VS 2005 document viewer.

    To merge all versions of VS use

    [Merge_Namespace]
    ms.vsipcc+
    ms.vscc+

    To merge VS 2003 and above

    [Merge_Namespace]
    ms.vscc.2003
    ms.vsipcc+
    ms.vscc.v*


    To merge only VS 2003 + VS 2005  + VS 2008

    [Merge_Namespace]
    ms.vscc.2003
    ms.vsipcc.v80
    ms.vscc.v80
    ms.vsipcc.v90
    ms.vscc.v90

  10. VS 2005 Express Pre-Merge [2006-06-24]

    We've had a few folks asking how to integrate content into VS 2005 Express (the cut-down version of VS 2005). Is it the same as VS 2005?
    With Express you still plug into MS.VSIPCC.V80 (so plug-in section does not change).

    Express uses a collection called MS.VSExpressCC.v80 instead of ms.vscc.v80.
    So if you use a pre-merge section (also requires the h2reg.exe -M command switch )
    then you need to add this extra collection name.

    To merge all versions of VS use

    [Merge_Namespace]
    ms.vsipcc+
    ms.vscc+
    ms.vsexpresscc+

    To merge VS 2003 and above

    [Merge_Namespace]
    ms.vscc.2003
    ms.vsipcc+
    ms.vscc.v*
    ms.vsexpresscc+


    To merge only VS 2003 + VS 2005 + VS 2008

    [Merge_Namespace]
    ms.vscc.2003
    ms.vsipcc.v80
    ms.vscc.v80
    ms.vsexpresscc.v80
    ms.vscc.v90
    ms.vsexpresscc.v90

    28-June-2006

    MS did not plan on 3rd party plug-ins in VS 2005 Express. If you want your plug-ins to appear in Express then an extra attribute "DocSet=ExpressLibVS" is required in the XML data Island of all HTML files. See thread in MSHelp2 Yahoo Group.

    <xml>
    <MSHelp:Attr Name="DocSet" Value="ExpressLibVS" />
    ...
    </xml>
     

  11. How to Customize Visual Studio 2005/2008 Search [2006-09-08]

    Under VS 2002 & VS 2003 you could register filters that would effect the TOC, Index and Search.
    However under VS 2005 registered filters only effect the TOC and Index.

    Q. Can H2Reg create VS 2005/2008 search filters?
    A. No Microsoft have provided a new mechanism for setting up VS 2005 filters.

    The following article will help you setup VS 2005/2008 search filters:
    > Extending Visual Studio 2005 Search


 

H2Reg Diagnostics

Diagnostics

H2Reg is an excellent tool for remote diagnostics. Firstly you can ask the customer to email you the log file (H2Reg_Log.txt). This contains lots of useful information.

If this provides no clues, the next step is to get a complete snapshot of the customers registration system. This will show up any collections that are partially registered or have collection files that are missing (MSI problems).

The H2Reg log file provides the following information:

How to make a diagnostics kit

To capture a  snapshot of the customers PC:

  1. Take a copy of h2Reg.exe and h2Reg.ini
     
  2. Add the following dummy line to h2Reg.ini so that H2Reg.exe will run...
    [Reg_Namespace]
    ;<nsName>|<nsColfile>|<nsDesc>
    xx|xx.hxc|xx
     
  3. Make sure h2Reg.ini has DumpNSToLog_before=1 for verbose logging (normally 0).
     
  4. Create a file Test.bat file which contains
    H2Reg.exe -r
     
  5. Zip up the 3 files and send to customer.

Instructions for the customer:

  1. Unzip the 3 files to an empty folder
     
  2. Run Test.bat
     
  3. Email back the log file H2Reg_Log.txt
     
H2Reg FAQ

See also H2 Posts & H2 FAQ

Q. Can I plug into non-VS collections such as Borland C# Builder help?
A Yes. There are no limits with H2Reg.
 
Q. Can I plug my collection into multiple targets?
A Yes. Unlike MS MSI registration H2Reg is very flexible. You can register and plug into any number of collections using a single script file. Or run multiple script files to be even more flexible.
 
Q. Can I plug into all MS.VSCC, MS.VSCC.2003, MS.VSIPCC.v80, MS.VSIPCC.v90 etc even if don't know what is installed on the customers machine?
A. Yes. H2Reg supports multiple targets and will fail gracefully if a target is not found.
You can specify multiple targets and use wild cards like MS.VSIPCC+ to future proof your installation and plug into any collection starting with MS.VSIPCC.
 
Q. When I run H2Reg a log file is created which is left behind on uninstall. What can I do?
A. If this is a problem you should install a dummy log file along with H2Reg.exe and H2Reg.ini.
This can then get removed at uninstall time.
 
Q. Is source code available?
A. No because Microsoft have not released the MS Help 2 API documentation to the general public.
 
Q. What support is available for H2Reg?
A.
Q. We use H2Reg but a 3rd party actually distributes our product? Do they also need a H2Reg license?
A. No. If you have purchased a license then what you do with your install package after that is your business.
 
Q. Is the download really the full release version?
A. Yes. There are no restrictions.
 
Q. Am I required to pay an annually license fee?
A. No. The license fee is a one time payment.
 
Q. Do I still need to use the Microsoft VSHIK .MSM MSI Help Registration Files?
A. No. You simply use your own installation program to install all files.
Then run H2Reg.exe to register the help files.
 
Q. We use H2Reg Internally only. Do we have to purchase a license?
A. H2Reg is free for personal use even for business use. As soon as you packaging H2Reg into an installation to be distributed to other (whether internal or external customers) then you must purchase a license.
 
Q. How does the H2Reg DLL license work?
A. The H2Reg license covers both the EXE and DLL forms of H2Reg. Normally you would ship either the EXE or the DLL with your installation solution but not both. See the H2Reg.DLL page.
 
Q. Can I build a general application that uses H2Reg.EXE or H2Reg.DLL to register files?
A. Not without special permission. H2Reg can only be used to help create installation packages. It is illegal for a company or individual to wrap another companies product without permission. An application that enables users to control the registration of MS help 2 files using H2Reg is not allowed. The DLL can only be used to create code used to extend an Installation solution.
 
Q. Is H2Reg just a wrapper for the H2 Registration API calls?
A. No. H2Reg has many built-in smarts and checks to make sure your customers registration is as simple and problem free as possible. The verbose log file alone can save you a lot of time when debugging.
 
Q. Is there a new plug-in location for VS 2005?
A. Yes. MS now want 3rd parties to plug their collections into MS.VSIPCC.v80 (was MS.VSCC.*) to isolate 3rd party collections a little more from the main VS documentation. For more info see our FAQ.
 
Q. How do I adjust my scripts to handle VS 2008?
A. The namespace for VS 2008 is "ms.vsipcc.v90".

Example:
To plug into to VS 2003, VS 2005, VS008 and above continue to plug into ms.vsipcc+

[Reg_Plugin]
MS.VSIPCC+|_DEFAULT|MyNameSpace|...
 

To plug into VS 2008 specifically:

[Reg_Plugin]
MS.VSIPCC.V90|_DEFAULT|MyNameSpace|...
H2Reg Shareware Purchase & Licensing

H2Reg is Copyright (c) 2002, Rob Chandler, The Helpware Group. Please do not redistribute H2Reg without our permission.

Purchase & Licensing Details

Change Notes