The XML Help Provider and Dynamic Help
When the Dynamic Help window is opened for the first time, it looks for an XML file in the folder
<VS install path>\Common7\IDE\HTML\XMLLinks\<LCID>. This folder is located in the Visual Studio .NET installation directory. The value of
<LCID> depends upon your language, such as English or French. For example, the English LCID is 1033. If an XML file is found in that folder that contains the correct tag syntax, its contents display in the Dynamic Help window along with the other Visual Studio .NET content. This service is known as the XML Help Provider.
Types of Tags
The DynamicHelp tag links to an XML schema (.XSD) file called vsdh.xsd that defines the custom XML tags and provides statement completion when authoring Help XML files. The Context tags encompass all of the content you want to provide to the Dynamic Help window. The Keywords tags surround the KItem tags, which in turn provide the Visual Studio .NET keyword you want to use to identify your topic(s). You can have multiple KItem tags nested inside of the Keywords tags. The Links tags surround the LItem tags, which in turn provide the URL to navigate to when your link is selected.
Role of Attributes and Keywords
"Context" is a term that refers to the combination of programming language, UI elements, and the item currently selected. The Attributes/AItem tags define the scope of the context in which your links will appear, that is, the combination of selected items and languages in which your topic will display. By default, the widest scope is assumed and your link appears in all possible contexts. While this might be useful in some situations, you can refine and narrow the circumstances in which your link will appear by adding one or more attributes.
For example, add the following to your XML Help file:
<Attributes> <AItem Name="Solution" Value="single"/> <AItem Name="item" Value="none"/> <AItem Name="project" Value="none"/> <AItem Name="Product" Value="VS"/> <AItem Name="Solution" Value="Any"/> <AItem Name="ShellMode" Value="Design"/> </Attributes>
In this case, you have defined a very narrow context scope where your link appears only if:
- The solution is open and contains only one project.
- No project item is active.
- No project is selected.
- The product is Visual Studio.
- One or more projects is opened at once.
- The IDE is in Design view.
That is a fairly narrow restriction! In some cases, though, defining such a restrictive scope can be useful. The benefits of creating a narrow scope are:
- Your topic displays only when you want it to and when the right conditions exist.
- Your topic gets a higher rank score, and as a result, moves closer to the top of the Dynamic Help topics list.
Each time the topic scope of your link matches a keyword and attribute in Visual Studio .NET, it receives a higher ranking in the Dynamic Help window. The higher the ranking, the nearer to the top of the list it displays. So, if you want your topic to display at or near the top of the topics list, try to match the keywords and attributes for your link to that of the IDE. The way to ensure this is by examining the Dynamic Help debugging information.