How to make different versions of help3 coexist.

Nov 21, 2011 at 11:42 AM


I have the following issue. Once I build and deploy help3 it shows up in Help Viewer with the same name taken from the MS Help Viewer Root Container. Let's say that I name that file "Product ver 1". Then I make a new build and I name that file "Product ver 2", but when I install it, it does not show up in Help Viewer. 

I assume that this has something to do with the CatalogProductId and CatalogVersion, but I have tried different scenarios and none of them worked. 

My goal is to be able to deploy different versions of my help without removing the previous one. Is this possible?

Nov 21, 2011 at 4:14 PM

Do you have the RootNamespaceContainer property set to true?  If so, it's a known issue.  Sandcastle uses a hard-coded "R:Project" ID for the namespace container page in all projects which is not valid in MS Help Viewer since all pages need a unique ID.  There's an open work item to see about fixing it or workaround it but I haven't been able to look into it yet (  You'll need to set the property to false and not use a root namespace container page.  The alternative is to use a MAML topic as a parent page for the API content.



Nov 22, 2011 at 1:59 PM
Edited Nov 22, 2011 at 2:02 PM

The RootNamespaceContainer is set to false, but I do have a node in my toc marked as MS Help Viewer Root Container. I have performed many tests and I was not able to make both versions coexist. nor update the whole content with the new one. This is probably the bug that you are talking about. 

If you uninstall the previous version, you will be able to install the new content, but I did not manage to find a way to traverse and delete all previous versions concerning my product, without manually specifying the exact version that i want to remove in the installer bat file. What approach do you recommend to make two versions coexist or to successfully update the help content? MAML topic as parent page is not acceptable in my case. 

Nov 22, 2011 at 3:16 PM

The node marked in the TOC as the root container is a MAML topic and has a different ID in each version, right?  Likewise for any other MAML topics in each version.  They'd need unique IDs or you'd only see the one set from one file or the other.  After thinking about it, a bigger issue is that most of the API members probably have identical IDs too between each version.  Since the ID is based on the member signature, the only possible workaround would be to use a different NamingMethod project property value so that it physically changes the ID by changing the way it's created.  That might work around the issue but would only work for two or three concurrent versions since there are only three naming methods.  I don't know of a way to have MS Help Viewer topics with identical IDs across multiple help content files.  I'm not sure that's even possible.  If changing the naming method gets it to work, that is the problem and you'd have to ask in the MSDN Dev Docs forum to see if there is a way to allow duplicate IDs such as in this case.



Nov 23, 2011 at 11:23 AM

The node marked in the TOC as the root container is a MAML topic and has a different ID in each version, right?

- I have tried to mark an empty containter node as root container, but I was not able to do that, since it required association with aml file. So in order to make it work I have created an empty aml file and I have associated it with the root container node. So to answer your question - this file will always be with the same ID.

So if I understand correctly, the Id of each file should differ for consecutive versions, and if it does not, the new content will not be deployed.

The NamingMethod approach is unprofessional to use, since the people using the help content will be disappointed after three versions, when I should remove all previously installed versions.

As i see things, the only possible option will be to remove all previously installed versions prior installation of new one. Are you aware of a way, to remove all previously installed versions for certain catalog. In my project I have set the CatalogProductId and CatalogVersion properties, so my content can be in my own catalog. But I do not want to track each version every time, so, do you know how to remove the whole content of a catalog.

Thanks for your cooperation.

Nov 25, 2011 at 7:31 PM

Empty container nodes are not supported in MS Help Viewer.  All TOC entries need a physical topic since all the meta data is stored in the topic as attributes.  As far as I know, all topics need a unique ID and they cannot be duplicated.  I haven't seen anything to the contrary.  It does seem incredibly shortsighted to have such a requirement so maybe there is a way to make it happen.  Since this exceeds my knowledge of the MS Help Viewer format, you would be better off asking these questions in the MSDN Dev Docs forum where people more knowledgeable in the inner workings of the format may be able to answer them.  If it turns out there is a way to make it happen, I can always modify SHFB to support it.