Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Creating Custom Help Files

This section serves as an introduction to creating help. To do this, you must install the Visual Studio .NET Help Integration Kit (VSIK) 2003, which you should be able to download from MSDN around the time Visual Studio .NET 2003 launches.

In this example, we'll create a simple Help file and integrate it into Visual Studio .NET 2003. In a way, creating help is much like using a new programming language, so we'll leave out some of the creation details in favor of the integration details.

After you install the Visual Studio .NET Help Integration Kit 2003, you'll find a new project category in the Visual Studio .NET New Project dialog box. The Help Projects category provides templates for new Help projects, Help conversion, and Help decompilation. You can see the new project templates in Figure 14-9.

One of the best features of the Help Integration Kit is that it lets you work on your Help project files from within Visual Studio .NET and therefore take advantage of the editors and the Help system in the IDE as you work.

The version of Help we'll use in this section is Microsoft Help 2. A number of files are used to organize an average Help 2 project. These files generally have an .Hx? extension, where ? represents a letter specific to the work that the file does. For example, the Help collection definition file extension is .HxC and the Help include file extension is .HxF. In Visual Studio .NET, Help 2 projects have an .HWProj extension. You can add a help project to any solution you create. Table 14-4 lists the extensions you should be familiar with.

When you create a new project, you start with an .HxC (collection) file and an .HxF (include) file. If you were building these files by hand, you'd normally edit them yourself, but in Visual Studio .NET you can do this using the project's Property Pages dialog box, as shown in Figure 14-10.

Templates for the file types you can add to a project are available in the Add New Item dialog box, as shown in Figure 14-11. You normally want to add a least one .HxT (TOC) file and one .HxK (Index) file.

Once you've added an .HxT file and an .HxK file to your project, you use the project's Property Pages dialog box to set a couple of important options. On the Navigation tab of the dialog box, select the TOC and Index files you want to use in your project from their respective drop-down lists, as shown in Figure 14-12. Then you can add some content to the project.

Next, we'll use the Add New Item dialog box to add an file named Intro. We'll use this file as the default page for the project. You can see in Figure 14-13 how our project stands. We have the page open in the editor, and the files we've created are all listed in the Project Explorer window. At this point, we can add nearly any content that we want to the project and make it available through the TOC.

After you create and save a number of content files, you can add them to the TOC by dragging and dropping them. Figure 14-14 shows the open TOC file. You can drag your content files to the tree and set their order by using the arrows on the toolbar or by using the context menu for the individual items. In this case, we've added a second TOC to the Global TOC.

Notice that in addition to the compiled content, you can add links in the TOC to external Web sites and to file system items. In this case, we added a link to the book's home page and set the Icon property to 22 to display a Web icon. You can customize the icon for any topic in the TOC in the Properties window for each topic. There are 45 icons available for use in the TOC, so you can get pretty specific with your content. To see the complete list, search on Default TOC Icons in VSHIK Help.

We now need to add some code to the file to get it to do some specific things. First, we want a default page to show up when we open our new Help file. If we don't set one, we'll just get our default Microsoft Internet Explorer Web page, which isn't what we want. We also want to add the appropriate help topics to the Index. To do both of these things, we need to add some code to the .HxK (Index) file.

First, let's talk about what we need to do to get a default page up and running. To get a default page to show up in help, you must create a Keyword index entry with a particular keyword and point that entry at the file you want to make the default. The Keyword for the default page in a Help file is "HomePage". The code to set this keyword in the .HxK (Index) file is shown here:

<Keyword Term = "HomePage">
<Jump Url = "HomePage"/>
</Keyword>

To add topics to the index, you can use the Keyword syntax we just described or add XML data to your topics, which adds them to the index automatically. Our example is short, so we just added a few entries to the Index file. The complete listing for the Index1.HxK is shown in Listing 14-2.

Listing 14-2 Help index file

Index1.HxK
<?xml version="1.0"?>
<!DOCTYPE HelpIndex SYSTEM "ms-help://hx/resources/HelpIndex.DTD">
<HelpIndex DTDVersion="1.0" Name="K">
<!-- Insert keywords here -->
<Keyword Term = "Macros">
<Jump Url = "Macros"/>
</Keyword>
<Keyword Term = "Web Site">
<Jump Url = "http://www.microsoft.com/mspress/books/6425.asp"/>
</Keyword>
<Keyword Term = "About">
<Jump Url = "About"/>
</Keyword>
<Keyword Term = "Add-Ins">
<Jump Url = "AddIns"/>
</Keyword>
<Keyword Term = "HomePage">
<Jump Url = "HomePage"/>
</Keyword>
</HelpIndex>

With all that in place, running the project should result in a complete Help collection like the one shown in Figure 14-15. You can compile and launch a Help collection by issuing the Debug.Start command from the Command Window or by pressing F5. This runs the compiler that creates the .HxS file and then starts a copy of Document Explorer (Dexplorer.exe) using the arguments supplied on the Launch page of the Project Properties dialog box.

Registering Your Help Collection

Before the help topic can be addressed by Dexplorer, it must be registered. There are a couple ways to register your Help collection so it can be viewed. The recommended way is to set up a Windows Installer package. This involves a fairly complicated set of steps that requires you to edit a merge module with the Orca tool from the Windows SDK. This method is described in a document that ships with the Help 2 SDK entitled Visual Studio .NET Help Integration. Here we'll describe an alternative method of registering a Help collection using the HxReg.exe utility for testing purposes.

To register the Help collection we just created, we need to run the HxReg.exe utility, specifying the namespace of the collection (-n), the name of the collection file (-c), and a description of the namespace (-d). To accomplish this, you probably need to add the Help 2 SDK to your path (C:\Program Files\Microsoft Help 2.0 SDK). To run the registration commands, navigate to the folder containing the .HxS file and run the following commands from the Command Window. The first one registers a namespace for your Help collection:

HxReg.exe n MS.InsideVSNET.1033 c InsideVSNET.HxC 
d "Inside Visual Studio .NET Help Sample"

Next, you register the compiled Help file:

HxReg.exe n MS.InsideVSNET.1033 i InsideVSNET 
s InsideVSNET.HxS l 1033

Notice that we wrapped the namespace with MS. And .1033. The convention for namespaces in this regard is (Company).Namespace.(Language).

Finally, to create a link to the newly registered Help file, create a shortcut that contains the following path in the Target text box:

"C:\Program Files\Common Files\Microsoft Shared\Help\dexplore.exe" 
/helpcol ms-help://MS.InsideVSNET.1033

You can also use the topics in your Help file from within Dynamic Help. To do this, just add the URL to the topic you want to display in the LItem tag that we discussed earlier. For the Macro topic in the help sample, the XML for the link would look something like this:

<LItem URL="ms-help://MS.InsideVSNET.1033/InsideVSNET/Macros" 
LinkGroup="InsideVSNET">Macro Information</LItem>

This won't integrate your Help collection into Visual Studio .NET. You must create an installer and edit the appropriate merge module to do that. But this gives you enough information so you can test your help topics from the Web toolbar and from Dynamic Help.