sandcastle bug: doesn't appear to be able to handle assembly rebindings

Oct 9, 2008 at 2:42 PM
This tool looked rather promising until I tried to use it on a project that made use of assembly rebindings.  Then it crapped out.  Here's the error:

[c:\temp\sandcastle\Help\Working\GenerateRefInfo.bat]
MrefBuilder (v2.4.10520.1)
Copyright c Microsoft 2006
Info: Loaded 1 assemblies for reflection and 29 dependency assemblies.
Error: Unresolved assembly reference: TopCoder.Util.ExceptionManager.SDE (TopCoder.Util.ExceptionManager.SDE, Version=2.1.1.0, Culture=neutral, PublicKeyToken=b7567367622062c6) required by TopCoder.Services.KeyAssociationSet
    Last step completed in 00:00:04.5310
-------------------------------

BUILD FAILED: Unexpected error in last build step.  See output above for details.

In case you are not familiar with assembly rebindings, they allow you to "rebind" all references to a specific assembly.  Here's an excerpt:


    <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.Util.ConfigurationManager" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-2.0.1.0" newVersion="2.0.1.0"/>
            </dependentAssembly>
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.Util.ObjectFactory" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-1.2.1.0" newVersion="1.2.1.0"/>
            </dependentAssembly>
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.LoggingWrapper" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-3.0.0.0" newVersion="3.0.0.0"/>
            </dependentAssembly>
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.Util.ExceptionManager.SDE" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-2.1.2.0" newVersion="2.1.2.0"/>
            </dependentAssembly>
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.Util.ExceptionManager" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-2.0.0.0" newVersion="2.0.0.0"/>
            </dependentAssembly>
            <dependentAssembly>
                <assemblyIdentity name="TopCoder.Configuration.File" publicKeyToken="B7567367622062C6" culture="neutral"/>
                <bindingRedirect oldVersion="0.0.0.0-2.0.0.0" newVersion="2.0.0.0"/>
            </dependentAssembly>
        </assemblyBinding>
    </runtime>

But sandcastle doesn't seem to read the config file that contains these rebindings, so when it tries to generate the doc it whines about not being able to find the correct assembly.  Anyway, seems like a bug to me.  I guess most folks don't use assembly rebindings, but it's a showstopper in my case so I will resort to the previous method I was using to generate sandcastle docs.

If I'm missing something or there's something I need to do differently please feel free to let me know. Thanks.



Coordinator
Oct 9, 2008 at 3:00 PM
It's a known issue with MRefBuilder.  There's an open work item in the Sandcastle project and I recently attached a workaround that uses a custom assembly resolver (http://www.codeplex.com/Sandcastle/WorkItem/View.aspx?WorkItemId=1014).  The related discussion topic and info on how to use it is also in the Sandcastle project here: http://www.codeplex.com/Sandcastle/Thread/View.aspx?ThreadId=36323.

Eric
Oct 9, 2008 at 3:20 PM
Thanks for the reply.  However, this solution really won't work for me, because if I understand it correctly you are basically specifying a global-scope assembly rebinding (by modifying the MRefBuilder.config).  But in a lot of the scenarios I deal with, I might be rebinding the same assembly to a different version depending on the project.  For example, in project A I might rebind assembly x to version 1.1.2.0, but in project B I might need to rebind that same assembly to version 1.1.1.0.  I work with a lot of signed assemblies and often times they are bound against different versions of supporting assemblies, so such rebindings are often required.

But the solution you provide will assume you're ALWAYS binding to the same version of an assembly across all projects.  Ideally you should be able to specify this in the sandcastle help file builder project file so the bindings could be project specific.  I guess ultimately, it'd be nice if the sandcastle help file builder could just read the app.config/web.config and get the assembly rebindings from there.

Anyway, thanks again for the reply, hope you can fix this issue in a future release because the tool does look like it has promise.

Coordinator
Oct 9, 2008 at 7:33 PM
In its current form, it is global as you have to modify the MRefBuilder.config template file to specify the bindings.  However, I plan on writing a plug-in to support this sort of thing on a per-project basis.  What you suggest about importing the settings from the app.config or web.config file is a good idea so I'll add support for that option too.

Eric