How-To Add Help Using the SnapInHelpTopicAttribute and SnapInLinkedHelpTopicAttribute

Article
10/10/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MMC help system uses HTML help to display help for snap-ins. It supports chm extension files and specific links into these files. There is a provision to merge the table of contents from a custom help file with the MMC help system by adding a link to a chm file. An additional requirement for a snap-in help file is that it must support a TOC (Table of Contents). You can also associate a specific help topic with a node. The help topic is automatically used when the standard help menu option is selected on the node.

While building your help file, make sure that the table of contents is binary, so that it can be added to the MMC table of contents. Failing to do so will not cause an obvious error, since the help file will still load and the help topics accessed from nodes will still work. However, the table of contents will not be correctly incorporated.

The SnapInHelpTopicAttribute and the SnapInLinkedHelpTopicAttribute attributes are used for associating a Help file with the snap-in. At run time, MMC uses the information in the attributes to find and load the referenced .chm files. For an example of a snap-in that uses help, please see the sample <MMC 3.0 Samples>\HelpSample.

Differences in Designing Help for Managed and Unmanaged snap-ins

Here are some major differences in the way in which help content is provided in managed and native snap-ins in MMC.

Managed Snap-ins

A help topic is provided by use of the SnapInHelpTopicAttribute attribute. During snap-in registration the help file is retrieved and stored in the registry. Once the snap-in is registered, the help file cannot be changed.

For different selections, a snap-in can provide different links into the main file. Both ScopeNode and SelectionData support the HelpTopicId property to update the topic for a given tree or result selection.

Native Snap-ins

In MMC 2.0 help interfaces are provided to retrieve the help file from snap-ins. Snap-ins need to implement the ISnapinHelp2 interface. The GetHelpTopic method is called to get the help file for the snap-in.

MMC 3.0 Help File Redirection

On the basis of the user and the system language setting, MMC 3.0 automatically redirects the help file lookup to the MUI subfolders. The redirection logic is dependent on the operating system. As an example, suppose that the path provided for the help file is <path>\helpfile.chm. MMC 3.0 would use the alternatives below in the following order for redirection. If a <path> is not provided, %windir%\help is used as the path.

MMC 3.0 on Windows Vista Redirection Logic

Attempt <path>\helpfile.chm
Attempt to redirect to <path>\mui\<userlangid>\helpfile.chm.
Attempt to redirect to <path>\mui\<systemlangid>\helpfile.chm.
Attempt to redirect to <path>\mui\ENDLANGID\helpfile.chm.

MMC 3.0 on Windows Server 2003 and XP Redirection Logic

Attempt <path>\helpfile.chm
If the system language is ENGLANGID, do not redirect.
If the user language is same as system language, do not redirect.
Attempt to redirect to <path>\mui\<userlangid>\helpfile.chm.
Attempt to redirect to <path>\mui\<systemlangid>\helpfile.chm.