This project is read-only.

SHFB Exception with Plug-in: Wrong dll version linked

Dec 9, 2007 at 6:31 PM

When trying to use the plugin on the Releases page with SHFB version, I get an exception, because the plug-in is linked to version of SandcastleBuilder.Utils.dll. This is the versioning/packaging problem I mentioned in the thread about SHFB integration. Every time the SHFB build increments, plug-ins are broken.

I will mention this to Eric, but in my experience there are only two solutions to this type of problem:

1) Don't use interfaces, use reflection instead to dynamically invoke methods. This is an excellent solution and the one I recommend. OR

2) Don't change the dll containing the plug-in interface: Create a "standard" dll containing only a plug-in interface that will not change for at least one year. Build that dll only once, do not increment the version number ever, and always ship that dll with SHFB. All plug-ins can safely link to it because neither the interface nor the version will change over time.

Since Eric has decided to use an interface, I will recommend option 2 above. Just wondering how you feel about it -- it would make your life easier, as well as the lives of all plug-in developers, to not have to rebuild every time the SHFB is rebuilt.

Thanks again for your great work, you are doing exactly the things I need, as if you are reading my mind : )

Warmest Regards,
Dec 9, 2007 at 10:00 PM
The root cause is that the SHFB assemblies are signed and as such, the plug-ins must be used with a matching version of the assembly against which they were built. Separating out the interface isn't a real solution. The problem there is that the plug-ins are tied quite closely with the other classes present in the SandcastleBuilder.Utils assembly and cannot be separated easily. It's not just a matter of moving the interface into an assembly by itself as it also references the BuildStep enumeration and receives a reference to the BuildProcess class to name just two. BuildProcess uses pretty much everything else in the assembly either directly or indirectly so plug-ins would end up referencing it one way or another. Removing the signing might fix the problem but would introduce the problem of people trying to run versions of the plug-ins that won't work with newer versions of the dependent assemblies. Using reflection would suffer from the same problem. Saying that the interface won't change for a year is also unrealistic given some of the significant changes that occur in Sandcastle from one CTP to the next which result in some significant alterations to the build process. The interface might not change but the underlying build process can and does change. I'm also finding that as I develop new plug-ins, I need to move some stuff around, change the order of and add new build steps, etc. Given all of that, in the long run, signing the assemblies is simpler even if it isn't as convenient for the end users and other plug-in developers.

Another point to consider is that Sandcastle itself is signed now and all custom build components used by BuildAssembler must be rebuilt in order to use them when a new CTP is released. For SHFB and the Sandcastle Extensions, the argument becomes irrelevant as they both contain build components.

Dec 10, 2007 at 2:15 PM
Hi Eric,

It is just a wish that I do not have to build plug-ins from source code, that they truly be plug-ins and work upward compatibly, without having to debug the object code. I understood what the problem was once I attached a debugger, but without that it is not obvious what the problem is.

For plug in developers the interface, and classes used by it, must stabilize at some point? Can't it be refactored so only the things needed for the plug in are in a separate assembly? BuildProcess, BuildStep, etc all in that assembly. At some point sandcastle will stabilize we can assume. Signing assemblies is ok, as long as the version number does not increment.

Thanks for responding!

Best Regards,