Microsoft Help 2 is the format used in VS Help and MSDN for VS versions 2002-2008. Starting with VS 2010, new format named MS Help Viewer (alias Help 3) is used. After you generate Microsoft Help 2 (.Hx? files) documentation you cannot view it immediately by pressing Show Documentation button on compilation dialog.

Help 2 documents must be registered first. After that you can view them in Visual Studio .NET (in case of VS .NET 2002/2003) or Microsoft Document Explorer - DExplore.exe (in case of VS 2005/2008). Unlike CHM documents, Help 2 documents cannot be viewed externally just by clicking them. Windows has no viewer associated with Help 2. But Visual Studio comes with its Help 2 viewer Document Explorer which can be used outside VS. Document Explorer is usually used inside IDE in the case of VS .NET 2002/2003 and outside the IDE in the case of VS 2005/2008. Whether you will use VS .NET or Document Explorer to view documentation, you must close VS .NET or Document Explorer after compiling documentation.

Unlike e.g. HTML Help with one CHM file, Help 2 documentation consists of several files:

• HxS...compiled help
• HxC...collection definition
• several HxK files...index files
• HxA...attributes
• HxT...contents

VSdocman generates and registers all Help 2 files on your computer. Your Help 2 system updates changes only if you close Visual Studio (if the help is open inside IDE) and/or Microsoft Document Explorer. So after compilation of documentation you should close VS or Document Explorer.

By registering your documentation in Help 2 system we mean:

1. Your documentation will be accessible in Help 2 system under its own namespace named "vbdm.PROJECT_NAME".
2. New filter is created for your documentation named by your project name. So your help will be visible under that filter. You can see the help also under: (no filter), .NET framework SDK, Visual Studio, Visual Basic and Related and some other filters. If you cannot see your documentation, check whether you use correct filter.
3. Your help is plugged in Visual Studio .NET help collection so that it is visible in VS help. That means you will see your help in Contents, your items will be in Index and you can perform search on your help.
4. Your help is integrated in VS dynamic F1 help.

Note: VSdocman tries to register your help in all VS 2002, VS 2003, VS 2005 and VS 2008. If you didn't install all of them, you will see error during compilation that help cannot be registered in some namespace (ms.vscc or ms.vscc.2003 or MS.VSIPCC.v80 or MS.VSIPCC.v90). You can ignore that error.

Viewing in Visual Studio .NET

It may take several minutes to update the changes when you open VS help for the first time after registering your help. After that, you should see your documentation in VS help.

You should see your help in Contents, your items will be in Index and you can perform search on your help. Your own help filter is created as well.

To see Visual Studio dynamic help integration including context-sensitive F1 help, go to code editor and select expression with some method, property or other documented member. For example click on prop1 in expression If prop1 = "hello" Then. Now you should see prop1 Property link in dynamic help window (if open) and if you press F1, the proper topic should appear.

Here is a sample of Help 2 topic:

Viewing in DExplore

Help 2 documentation cannot be viewed by specifying one file because there is no main file but a set of files as described above. Your help is registered under its own namespace named "vbdm.PROJECT_NAME".

DExplore uses namespace to identify which help to show:

DExplore.exe /helpcol ms-help://NAMESPACE_NAME

So if you type something like DExplore.exe /helpcol ms-help://vbdm.myProject, viewer should open your help.

Since your help is registered in VS .NET 2002, VS .NET 2003, VS 2005 and VS 2008, you can view whole Visual Studio collection as if you were in Visual Studio. Just type:

DExplore.exe /helpcol ms-help://ms.vscc

or

DExplore.exe /helpcol ms-help://ms.vscc.2003

or

DExplore.exe /helpcol ms-help://ms.vscc.v80

or

DExplore.exe /helpcol ms-help://ms.vscc.v90

Important

When you compile and thus register your help several times, help system does not update changes even when you reopen Visual Studio IDE or Document Explorer. You help was already registered and help system doesn't reflect that you registered it again with changes. The best way to workaround this is to close VS IDE or Document Explorer, unregister your help, open VS IDE or Document Explorer. You should see that your previously registered help was removed. Close VS IDE or Document Explorer, register new help and open VS IDE or Document Explorer again. Now you should see your new documentation.

VSdocman generates for you two scripts for registering and unregistering your help. They are located in output folder under names register_PROJECT_NAME.bat and unregister_PROJECT_NAME.bat. The help is already registered after compilation. So if you follow the method above, start unregister_PROJECT_NAME.bat for unregistering (previous help) and then register_PROJECT_NAME.bat for registering your (new) help.

Tip: You can view and manage all registered Help 2 namespaces with free Microsoft Namespace# 2.0 utility. Be careful if you decide to manage namespaces manually. You can irreversibly damage your help system. Please do it only if there is some problem with your documentation. If you decide to delete your namespace with this tool, make sure you first delete its plugin from ms.vscc or ms.vscc.2003 or MS.VSIPCC.v80 or MS.VSIPCC.v90 namespace.

Since help is updating every time you make some changes and it may take several minutes we recommend you to compile HTML Help 1.x (chm) documentation for test purposes and use Help 2 format when you are satisfied with your documentation.

When deploying your documentation you need to register it on the target machine. There are some methods mentioned in Visual Studio .NET Help Integration Kit (VSHIK). The method that fits our needs uses MS Installer and is quite complicated and in fact it is unusable for most developers.

Therefore we developed small command line tool HelixoftHelpReg.exe that does all the job. Registered users of VSdocman can distribute it with their documentation. VSdocman itself uses this tool for registering the help.

As already mentioned, Help 2 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_DOC folder:

• HelixoftHelpReg.exe - help registration utility. You can use HelixoftHelpRegQ.exe instead of it if you don't want any console window to appear during installation.
• HelpRegCfg.xml - configuration file for HelixoftHelpReg.exe
• register_PROJECT_NAME.bat - it simply calls HelixoftHelpReg.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 unregister the documentation. Again, HelixoftHelpReg.exe can do it for you. It simply calls HelixoftHelpReg.exe utility with proper arguments. You should call it from your uninstaller.
• PROJECT_NAME_dyn_help.xml - VS .NET dynamic help integration file which should be placed in VISUAL_STUDIO_NET\Common7\IDE\HTML\XMLLinks\LCID. LCID is language ID used on target computer. This path is usually: C:\Program Files\Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\1033. This will be performed by HelixoftHelpReg.exe utility.
• 8 *.Hx? files that compose Help 2 documentation.

All you need to do is to copy all those files in one folder on target machine and call register_PROJECT_NAME.bat during installation. All Hx? files must then stay in that folder. Don't delete any file, especially HelixoftHelpReg.exe because you will need them during uninstallation.

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

View and Deploy HTML Help 1.x Documentation | View and Deploy HTML Documentation | View and Deploy Help & Manual Documentation | View and Deploy Solution Documentation | View and Deploy Context Help