Version plugin of SHFB and VersionBuilder of Sandcastle

Topics: Developer Forum, Project Management Forum
Oct 9, 2013 at 9:16 PM
Edited Oct 9, 2013 at 10:05 PM

I have the following situation:
  • Project A, which is portable, and which defines type T
  • Project B, which is not portable, and which defines extension method for T
Now, because A and B target different frameworks, I have to create separate .shfbproj files for them. And then use one of them as 'main' project with Version Builder plugin in order to produce a single help file.

I chose B to be 'main' project which has Version Builder plugin active and configured. There was a problem however - the extension methods defined for T in Project B, were not visible in resulting help file!

I traced the problem to the fact that VersionBuilder.exe in Sandcastle merges the reflection files without checking for additional extension models. One could argue that the data schema for reflection XML file was already faulty since it included duplicated information about extension methods (<element api="M:..." source="extension">...</element> within the type with the extension method), but fixing that is a huge task.

Instead, I fiddled around with the source code of VersionBuilder.exe so that it now produces merged .xml files which has correct extension method information even when the type and method are defined in different projects.

Additionally, the Version Builder -plugin in SHFB doesn't restore original values of some properties of the configured projects (Project A, in my case), which is quite annoying when the .shfbproj file is under version control. It happens because .Build() method of the build process will save the project file, and the Version Builder plugin never restores the old values.

I have made modifications to the Version Builder plugin code so that after successful or unsuccessful build, it will restore old values of the project file and save it.

Apparently I can't attach files here, so I've uploaded a zip file containing two modified .cs files files (with correct folder structure) to here: . I hope the fix will be incorporated to codeplex soon. :)

Edit: It seems that the fix to the Version Builder plugin caused the "Project file was modified outside..." dialog. I don't know how to disable it. Even still, that is better than constant changes in the file (assuming file is under version control system).
Oct 10, 2013 at 7:18 PM
I'll take a look at the changes. Be aware that you can create a work item on the Issues tab and attach your files there.

Oct 11, 2013 at 5:43 AM
Ah, of course. Silly me. Would you like me to create an issue (or two?) out of this?
Oct 11, 2013 at 3:02 PM
Edited Oct 12, 2013 at 11:18 PM
No need for a work item. I had time so I've merged your changes into the VersionBuilder tool. Regarding the plug-in, I've corrected it so that it properly clones the project and avoids modifying a copy that Visual Studio may have loaded too. That will prevent the source control check out issue too.

Oct 13, 2013 at 4:44 PM
I just came back home from weekend and was thinking of creating an issue, but I am glad you had time to fix them without the work item. Thank you for that, and I'll be sure to create work item if I encounter similar issues in the future. :)
Oct 13, 2013 at 8:47 PM
Edited Oct 13, 2013 at 8:48 PM
Argh, I just noticed one bug. If you can just change line 131 of Program.cs in VersionBuilder of Sandcastle, from
XPathExpression skipFirstParam = XPathExpression.Compile("/parameter[position()>1]");
XPathExpression skipFirstParam = XPathExpression.Compile( "./parameter[position()>1]" );
then the parameters within the extension method <element api="..." source="extension">...</element> XML element will show up correctly.

I'm really sorry for the inconvenience.
Oct 13, 2013 at 10:02 PM
No problem, it's fixed. I'm not planning on publishing the new release until some time this week.