Sandcastle project status

Jan 14, 2012 at 9:44 PM
Edited Jan 16, 2012 at 6:23 PM

Hi,

Could anyone tell me if this project is still alive? It's been 18 months since the last release, and there doesn't seem to be any activity on the repository...

Is someone still working on it? Can I expect outstanding bugs to be fixed someday (e.g. this very annoying one), or do I have to live with it or switch to another documentation tool?

Jan 15, 2012 at 2:20 PM

Hello,

I have no information on the state of the project and cannot comment on that part.

I will, however, advice you post bugs to the forum for discussions, since most do not subscribe to the
issue tracker. 

For the issue referenced, I still do not know why you need to provide extensions methods for Object class.
Here is how to fix it. The extension methods are handled by a class, ExtensionMethodAddIn, defined in
the MrefBuilder application and used in the MrefBuilder.config file.

1. Take a copy of that class from the Sandcastle source codes.
2. Add the following to the start of the AddExtensionMethod method:

 

if (type != null)
{
    // Avoid adding extension method support to enumerations...
    if (type.NodeType == NodeType.EnumNode)
    {
        return;
    }
    // Avoid adding the extension methods to static classes...
    if (type.NodeType == NodeType.Class && (type.IsAbstract && type.IsSealed))
    {
        return;
    }
}

3. As you can see from the naming of this class, it is an add-in. So replace the standard with
this one in your build system and it will solve all the problems listed in the issue. 

The operation in that method is what determines which type gets and displays the extension methods.
The above codes will filter out the cases giving the problems. 

Best regards,
Paul. 

Jan 15, 2012 at 10:37 PM
Edited Jan 15, 2012 at 11:48 PM

Hi Paul,

Thanks for your answer! This solution looks promising, I will give it a try.

Regards,
Thomas


EDIT: btw, the reason I have an extension method for the object type is that I want it to apply to any type. Here's the method:

        public static T ConvertTo<T>(this object value)
        {
            return (T)Convert.ChangeType(value, typeof(T));
        }
I could add a second type parameter for the source type, but then I would have to specify both types when calling the method...

Jan 18, 2012 at 2:06 AM

Hi Paul,

I didn't manage to make it work... The MRefBuilder.exe I generate from the source has the same version as the one installed with Sandcastle, but it's much smaller, and doesn't work. Apparently Sandcastle expects to find the AssemblyResolver class in the MRefBuilder assembly, but in the solution it's in the Reflection assembly, which doesn't exist in the installed version of Sandcastle... So it seems that the source doesn't match the installed version. Is there something else I should do to make it work?


Regards,
Thomas

Jan 18, 2012 at 2:24 AM

Hello Thomas,

You are not supposed to generate or replace MrefBuilder.exe, it is the main application that will
run your add-in. The default/standard add-in for the extension is what you need to replace.

So create your own assembly (DLL) with that single file with the modifications, and reference
that MrefBuilder.exe, but set the Copy Local property to false, so that you do not copy this
exe to your local directory.

Modify the MRefBuilder.config file for your build system to replace the default/standard
add-in similar to this:

<!-- This is configuration file for the MRefBuilder tool. -->
<configuration>
  <dduetools>
    <!-- 1. Specify the platform for the reflection. -->
    <platform version="2.0" path="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\" />
    <!-- 2. Specify the assembly resolver for the reflection. -->
    <resolver type="Sandcastle.Reflections.RedirectAssemblyResolver" assembly="A:\Output\Sandcastle.Components.dll" use-gac="false" />
    <!-- 3. Specify the API namer for the reflection. -->
    <!-- 4. Specify any addin - must be an implementation of MRefBuilderAddIn. -->
    <addins>
      <addin type="Sandcastle.Reflections.ExtensionMethodAddIn" assembly="A:\Output\Sandcastle.Components.dll" />
      <addin type="Microsoft.Ddue.Tools.XamlAttachedMembersAddIn" assembly="A:\Program Files\Sandcastle\ProductionTools\MRefBuilder.exe" />
    </addins>
    
    <!-- Omitted other stuff ...  -->
  </dduetools>
</configuration>

 As you can see, mine is defined in the class Sandcastle.Reflections.ExtensionMethodAddIn and in the assembly Sandcastle.Components.dll.

Best regards,
Paul 

Editor
Jan 18, 2012 at 2:32 AM

You shouldn't need to rebuild MRefBuilder.  Create a library project in Visual Studio,  add a strong name key file to sign the assembly, add the ExtensionMethodAddIn.cs class to it, add references to MRefBuilder.exe if necessary with any other supporting assemblies from the Sandcastle installation folder to it and build the library.  You can then take the library, put it in a well-known location such as the Sandcastle installation folder and change the MRefBuilder.config file to point at it by changing the <addin> element for it to point at the new assembly.

If using SHFB, you'll need to modify it's MRefBuilder.config template found in the .\Templates folder in the SHFB installation folder.  That's off the top of my head but I don't think I missed anything.  I plan on adding a version containing the fix to the next release of SHFB so it'll be built-in by default.

Eric

 

Jan 18, 2012 at 8:52 AM

Oh, right... I misunderstood Paul's proposed solution. Thanks for the clarification, I'll try this tonight.


Thomas

Jan 18, 2012 at 4:23 PM

Paul, Eric,

Thanks a lot, this solution works perfectly !

Regards,
Thomas