Integration Application Blocks Help into Visual Studio .NET 2003

The Microsoft Application Blocks (MAB) have documentation included in their respective docs folder at the installation directory. I’ve always thought it was a pitty that you did not have integrated help from the Visual Studio .NET environment. Well, it is not so hard to create it. I’ll provide a cookbook recipe that you can use to integrate your MABs into the Microsoft Visual Studio Combined Collection (VSCC) Help.

What you need is:
– Microsoft Application Blocks of your choice
Microsoft Visual Studio Help Integration Kit 2003 (VSHIK)
Microsoft Help Integration Wizard (Beta)
Make sure you have these installed.

Next, create a folder where all documentation files will be put. If you can’t think of anything, go for “C:Microsoft Application Blocks” or C:MAB. Copy all .chm documentation files from the docs folders of all MABs you want the integrated help for. Create two batch files named convert.bat and compile.bat and add the following content to them:

@echo off
“C:Program FilesMicrosoft Help 2.0 SDKhxconv” -o “C:Microsoft Application BlocksAggregation” “Aggregation.chm”
“C:Program FilesMicrosoft Help 2.0 SDKhxconv” -o “C:Microsoft Application BlocksAsynchronous Invocation” “Async.chm”

@echo off
“C:Program FilesMicrosoft Help 2.0 SDKhxcomp” -r “C:Microsoft Application BlocksAggregation” -p “C:Microsoft Application BlocksAggregationAggregation.HxC”
“C:Program FilesMicrosoft Help 2.0 SDKhxcomp” -r “C:Microsoft Application BlocksAsynchronous Invocation” -p “C:Microsoft Application BlocksAsynchronous InvocationAsync.HxC”

Obviously, the list of calls to hxconv and hxcomp might be longer if you have more than the Aggregation and Asynchronous Invocation MABs installed. You can make the list as long or short as you like. Just remember that you should name the HxC files without spaces. I use the same simple names that the .chm files have, whereas the folders get more descriptive names.

Run the convert and compile batch files. This should convert the .chm files to a lot of html pages, images and Microsoft Help 2.0 files. The compiler will create content files for each of the MABs with the .HxS extension.

The final step in the integration is the most tricky one. We need to create a .HxC collection file, some index files (HxK), and even others (.HxF, .HxT) and integrate and register these files in a correct  way to make it appear within the VSCC. Not the simplest of all tasks. Luckily, the Help Integration Wizard does all of this for us. All we need to do is go through the four steps in the Wizard. Then it will create a .msi setup file for us, containing all of the necessary files and installer entries to do the integration.

You start the Wizard from File, New Project, Extensibility Projects. Specify the C:MAB folder (or whatever) as your location and name the project something like “Documentation Setup”. The Wizard will show right after you click OK.

Step 1: Specify a Standalone Setup Project.
Step 2: Add all .HxS files from the C:MAB subfolders where you had the MABs converted and compiled. Take a look at the picture to find out what it should look like.

Step 3: Rename the root of the Help Collection TOC to “Microsoft Application Blocks”. Next, create new child nodes by clicking the blue book icon in the mini toolbar. Set its name to the full name of the MAB. Add these in alphabetical order. After you create and name a node, select the corresponding node from the right-hand side of the Wizard. Navigate the first item of the set that was added to the left, so the set becomes a child of the node you have created. Use the arrow buttons to do so. You might get error messages here (hey, it’s a beta), but these can be dismissed without crashing the Wizard. Repeat for all MABs. Take a look at the picture for reference.

Step 4: There’s a lot of properties you can set in this step, but the most important ones are in the Collection category. Set the namespace to “ms.applicationblocks.1033” and the description to “Microsoft Application Blocks Help”. Click Finish.

You should get a Installer project in VS.NET once you finish the Wizard. After changing the usual properties of the project to suit your desires (whatever they may be), build it and run the .msi file. Close VS.NET and start it again. If all went well, your VSCC should have a new node called Microsoft Application Blocks.

If things didn’t turn out as you expected, make sure that none of the .Hx* files have spaces in their names, especially inside the compile.bat file. You can also download the MsiVal2.exe tool (part of the Platform SDK found here, and it should be available after download in “C:Program FilesMicrosoft SDKBin” as msival2.msi) to check if the .msi file is correct. MsiVal2 validates a .msi file based on a .ice (Internal Consistency Checker) file. The one you need to check help integration .msi files in located in the “C:Program FilesMicrosoft Help 2.0 SDKUnsupported Tools” folder and is called Copy this file plus the msival2.exe to project folder (C:MABDocumentation Setup) and execute the following line from a command prompt in this folder:

msival2 “releaseMicrosoft Application Blocks Help Setup.msi” helpice.cub

(assuming the .msi file built is named as above). You should only get three errors (for Hxs_460, Hxs_36583, Hxs_17) and not more. Otherwise retrace your steps or contact me through the comments if all fails. Maybe I can help you out.

Compile.bat.txt (1.85 KB)
Convert.bat.txt (1.28 KB)

This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s