Compartir a través de

How to: Integrate F1 Help into a Domain-Specific Language

  • Artículo

This topic explains how to author help keywords in your domain-specific language and use a Domain Specific Language Setup project to deploy a Visual Studio help collection with a domain-specific language. Topics in the help collection that you deploy will appear with other topics in Visual Studio. By authoring keywords in your domain-specific language, you can link topics in the help collection to user interface elements through F1 help and the Dynamic Help window.

For more information about help authoring and integration in Visual Studio, see Help Authoring.

To author keywords in a domain-specific language

  1. In the Domain-Specific Language Designer, open the DslDefinition.dsl file for your domain-specific language, and click an instance of one of the following types of elements:

    • Dsl (root node in the DSL Explorer window)

    • Domain classes

    • Domain relationships

    • Shapes

    • Connectors

    • Domain properties

    • Domain roles

    • Toolbox items

  2. In the Properties window, find the Help Keyword property, and type a string as shown in the following illustration:

    DslDefinition Properties

  3. When you finish setting keywords, click Transform All Templates on the Solution Explorer toolbar.

  4. Build and run your designer.

    The keywords that you have set are used as F1 keywords in the Visual Studio help collection as described in the following table:

    Element type

    Action that pushes keyword

    Dsl

    Domain class

    A user clicks an instance of the domain class in Model Explorer.

    -or-

    A user clicks a shape that is on the design surface and that is mapped to an instance of the domain class.

    Domain relationship

    A user clicks a connector that is on the design surface and that is mapped to an instance of the domain relationship.

    Shape

    A user clicks an instance of the shape on the design surface.

    Connector

    A user clicks an instance of the connector on the design surface.

    Domain Property

    A user clicks the property in the Properties window.

    Domain Role

    A user clicks a property that is in the Properties window and that corresponds to a reference relationship on which the role exists.

    Toolbox item

    A user clicks the item in the Toolbox.

To verify keywords are functioning

  • To verify whether the keywords are being pushed as expected, do the following:

    • Enable debug output in the Dynamic Help window by opening the following key in the Windows registry:

      HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0Exp\Dynamic Help

      Nota

      This key might not exist until you have opened the Dynamic Help window at least once in the Visual Studio experimental build.

    • With the registry key open, change the value for Display Debug Output in Retail to YES.

    • Close and re-open the experimental build, and open the Dynamic Help window.

      Click various user interface elements in your designer to display the corresponding keywords in the debug output in the Dynamic Help window.

To author a help collection

  • Use Help Studio Lite, which is included in the Visual Studio SDK. For more information, see How to: Start HelpStudio Lite.

    Nota

    When authoring your help collection, make sure that the keywords that you associate with topics in your collection correspond to the values that you specified for the Help Keyword property in your domain-specific language.

To create a setup project for a help collection

  1. Open your domain-specific language solution.

    Nota

    Make sure that you have built the solution at least once.

  2. In Solution Explorer, right-click the Solution node,and click Add New Project.

  3. In the Add New Project dialog box, expand the Other Project Types node, and click Extensibility.

  4. Under Templates, click Domain Specific Language Setup, and click OK.

    A project that is named Setup1 is added to the solution, and a file that is named InstallerDefinition.dslsetup is opened. The InstallerDefinition.dslsetup file is an XML representation of an instance of a domain model for deploying domain-specific languages. The InstallerDefinition.dslsetup file is created with some initial values that are specific to your domain-specific language, such as its name. To deploy the help collection, you must modify this file. Specifically, you must add your help collection files and the standard Help merge modules to the domain-specific language deployment. For more information, see Walkthrough: Deploying a Domain-Specific Language and Appendix B: DslSetup Schema Description.

  5. Make sure that you have access to the following files from your help collection:

    • Compiled Help file(s) (.hxs)

    • Help collection index file(s) (.hxc)

    • Table of contents file(s) (.hxt)

    • Help keyword file(s) (.hxk)

    For example, you might have the following files:

    • TestDSLHelp.hxs

    • TestDSLHelp.hxc

    • TestDSLHelp.hxt

    • TestDSLHelp_A.hxk

    • TestDSLHelp_F.hxk

    • TestDSLHelp_K.hxk

    • TestDSLHelp_N.hxk

  6. In Setup1, create a folder, and name it Help.

  7. In Solution Explorer, right-click the new folder, click Add Existing Item, and add each help collection file.

  8. Right-click InstallerDefinition.dsl, and click Open With.

  9. In the Open With dialog box, click XML Editor, and then click OK.

  10. Add a <supportingFile> element for each help collection file. For each element, make sure that the name attribute is set to a unique value, the isEmbedded attribute is set to true, and the filePath attribute points to the file in the Help folder. To deploy the files that are listed in the earlier example, your XML would resemble the following:

    <supportingFiles>
…
<supportingFile name="TestDSLHelpHxC" filePath="Help\TestDSLHelp.HxC" isEmbedded="true"/>
<supportingFile name="TestDSLHelphxt" filePath="Help\TestDSLHelp.hxt" isEmbedded="true"/>
<supportingFile name="TestDSLHelp_Ahxk" filePath="Help\TestDSLHelp_A.hxk" isEmbedded="true"/>
<supportingFile name="TestDSLHelp_Fhxk" filePath="Help\TestDSLHelp_F.hxk" isEmbedded="true"/>
<supportingFile name="TestDSLHelp_Khxk" filePath="Help\TestDSLHelp_K.hxk" isEmbedded="true"/>
<supportingFile name="TestDSLHelp_Nhxk" filePath="Help\TestDSLHelp_N.hxk" isEmbedded="true"/>
<supportingFile name="TestDSLHelphxs" filePath="Help\TestDSLHelp.hxs" isEmbedded="true"/>
</supportingFiles>

    The next step is to add the following Help merge modules to your deployment:

    • HTML_Help_Registration__RTL_---_---.msm

    • MSHelp2_RegTables__RTL_---_---.msm

    • VSIPCC_Collection_Files_RTL_---_---.msm

    These modules contain custom actions that handle registration and unregistration of the help collection when your domain-specific language is installed and uninstalled. You can find the first two modules in the following location:

    <Drive>:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\Redist

    You can find the third module in the following location:

    <Drive>:\Program Files\Microsoft Visual Studio 2008 SDK\HelpIntegration

  11. In the Setup1 project, right-click the Help folder, click Add Existing Item, and add each .msm file.

  12. In the InstallerDefinition.dslsetup file, add a <mergeModules> section immediately before the closing </installerDefinition> tag, which appears at the end of the file. This section should contain one <mergeModule> element for each .msm file as in the following example:

    <installerDefinition…>
…
<mergeModules>
<mergeModule name="helpModule1" localeId="1033" modulePath="Help\HTML_Help_Registration__RTL_---_---.msm"/>
<mergeModule name="helpModule2" localeId="1033" modulePath="Help\MSHelp2_RegTables__RTL_---_---.msm"/>
<mergeModule name="helpModule3" localeId="1033" modulePath="Help\VSIPCC_Collection_Files_RTL_---_---.msm"/>
</mergeModules>
</installerDefinition>

    The next step requires a tool that can modify the data tables in Windows Installer merge modules. Orca.exe is an example of such a tool, and you can find it as part of the Windows Platform SDK.

  13. Use Orca.exe or a similar tool to open the second merge module in your setup project, “Help\MSHelp2_RegTables__RTL_---_---.msm”.

  14. Modify the values in the following tables for your help collection:

    • HelpFile

    • HelpFileToNamespace

    • HelpNamespace

    • HelpPlugin

    For information about which values to specify, see Walkthrough: Registering and Integrating Your Help Collection Using Windows Installer.

    Advertencia

    Notice the underscore (“”) that comes before the values in the File_HxS, File_Collection, and File_HxT columns. The values in these columns must correspond to values in the File table in the main Windows Installer (MSI) package for deploying your domain-specific language. The Domain Specific Language Setup Project generates File table values of the form: “<name>”. In this form, <name> is the value of the name attribute of the <supportingFile> element in your InstallerDefinition.dslsetup file.

  15. Save your changes, and close Orca.exe or similar tool.

  16. Click Transform All Templates on the Solution Explorer toolbar.

  17. On the Build menu, click Build Solution.

To install and test a help collection

  1. From the Setup1\bin\Debug directory, copy the MSI package for deploying your domain-specific language, DSLToolsRedist.msi, setup.exe, and setup.ini to a target computer.

    Nota

    You can install the domain-specific language on the computer on which you developed it. However, you should then uninstall the language before you continue to develop it.

  2. On the target computer, run setup.exe, and then open your designer and the Dynamic Help window.

  3. Click different elements in your domain-specific language.

    Links that correspond to topics appear in the Dynamic Help window.

  4. Click one of those topics, or press F1.

    The corresponding topic appears in the Visual Studio help collection.

See Also

Concepts

Deploying Domain-Specific Language Solutions

Domain-Specific Language Tools Glossary