.NET and Silverlight docs in single project/help file?

Topics: User Forum
Feb 10, 2011 at 7:52 PM

Hello. I have a SHFBproj file for my .NET 4.0 project, and having recently added Silverlight support for my library (a separate solution that targets the Silverlight platform), I was hoping I could simply add this Silverlight solution as a second source for the Sandcastle project. Unfortunately, this is giving me an error when building:


BUILDASSEMBLER : error : BuildAssembler: An error occured while initializing the build component 'SandcastleBuilder.Components.VersionInfoComponent' in the component assembly 'C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilder.Components.dll'. The error message and stack trace follows: System.ArgumentException: An item with the same key has already been added.
     at System.ThrowHelper.ThrowArgumentException(ExceptionResource resource)
     at System.Collections.Generic.Dictionary`2.Insert(TKey key, TValue value, Boolean add)
     at SandcastleBuilder.Components.VersionInfoComponent..ctor(BuildAssembler assembler, XPathNavigator configuration)
    Last step completed in 00:00:06.8334
-------------------------------

SHFB: Error BE0043: Unexpected error detected in last build step.  See output above for details.


So, is there any way to build both documentation output for my normal .NET library and the Silverlight version in one go/using the same SHFB project? If not, what is recommended practice here?

Many thanks.

Coordinator
Feb 11, 2011 at 1:45 AM

You've most likely named both assemblies the same which is causing the duplicate key issue.  Giving them different names should work around the issue.  You could use the Version Builder plug-in to build the help for each and combine them into one help file.  However, there are some known bugs with the version builder in the June 2010 release of Sandcastle.  There's a partial fix in a forum post at the Sandcastle Styles project site.

Eric

 

Feb 17, 2011 at 2:31 AM

Thanks for the reply. Indeed, giving the assemblies different names lets the build proceed successfully; however, the documentation for my normal .NET lib and the Silverlight version of the lib seem to merge into one under the same root node "API Documentation". I can't view them separately -- is this possible (i.e. having different sections under the root API Documentation node for different versions of the library) -- either with or (ideally) without the Version Builder plug-in? With the version builder plug-in, I presume I need two .shfbproj files?

Coordinator
Feb 17, 2011 at 7:26 PM

If they have the same namespaces/class/member name, the topics will be merged into the same location.  If classes and/or members overlap, one version will take precedence and will effectively hide the other unless you use the Version Builder plug-in to merge them.  In that case, part of the merging process is to add version info to each topic to define in which library or libraries, the member appears.  I don't think there's a way to do what you want with Help 1 or website output.  With MS Help Viewer you can build each as a separate help file and place them under their own node in the parent TOC.  I think you may be able to do something similar with Help 2 but I don't recall off-hand.

Eric

 

Feb 20, 2011 at 9:58 PM

Thanks for the response. I may just end up producing separate help files...So Version Builder won't work for me for Help 1 - what does it do then? I'll have a look into the MS Help Viewer method I think. I suppose there's no information out there on doing this; I'll have to experiment?

Coordinator
Feb 20, 2011 at 10:22 PM

The version builder is useful if you don't mind the members from each class/namespace being combined.  The version info in each topic provides details about which version the member appears.  For information on content placement, see the Content Placement Options topic in the SHFB help file.  It describes how the options work and how to use the content placement settings for MS Help Viewer to parent the content under a specific topic or one that you have created.

Eric