Sandcastle document multiple assemblies with dependencies located at 2 different places

Jan 25, 2008 at 3:38 PM

I have around 400 assemblies and equal amount of corresponding .xml files. Now, I want to use the MRefBuilder, BuildAssembler and XSLTransformer individually in a batch file and compile the .chm help file.

I am using the MrefBuilder as following since I have multiple .dlls

MRefBuilder *.dll /

My question is how and where can I feed these 400+ .xml files which are the documentation generated by "csc \doc" ? Also, can anyone give me an example on how to do so?

I appreciate your help in advance.


Jan 25, 2008 at 4:00 PM
Edited Jan 25, 2008 at 4:03 PM
If you're doing a command line build, the easiest way would be to have your script copy everything to a common location so that you only have to specify one folder for the tools and in the configuration file. The comments files are specified in sandcastle.config in the CopyFromIndexComponent preceeded by the "Copy in comments" comment. By default, it only uses comments.xml so you can search for that too to find out where to specify your files.

If you haven't tried them yet, check out the community tools such as The Sandcastle Help File Builder ( and DocProject ( which can help you manage the project and automate the build process.

Jan 25, 2008 at 4:36 PM
Hi KP,

Check out Sandcastle Help for some links to more information. Also dig through the Sandcastle Blog for more information about the build process and Sandcastle's tools.

Although, if you follow Eric's suggestion and check out the community tools, then you won't need to learn much about Sandcastle in order to use it.

- Dave
Jan 25, 2008 at 4:50 PM
Eric & dave

Thanks for your quick replies. I do have enough knowledge about how this works.
Eric, I have all my libraries in one folder. However, some of my libraries are referring to GAC libraries. Is there anyway I can make the MRefBuilder look in GAC.

Also, I checked out SHFB, It is pretty much doing everything I want. I just want to know how to replicate that using a batch file instead of GUI.

Jan 25, 2008 at 5:32 PM
Edited Jan 25, 2008 at 5:33 PM
Hi KP,

Is there anyway I can make the MRefBuilder look in GAC?

Assuming that you're referring to dependencies and not source assemblies that you want documented, try setting use-gac="true" in the resolver element of the MRefBuilder.config file, found in the ProductionTools folder (the value is false by default). Example:

<resolver type="Microsoft.Ddue.Tools.Reflection.AssemblyResolver" 
  use-gac="true" />
- Dave
Jan 25, 2008 at 5:42 PM
Dave, I did it with no luck.

Eric do you remember this thread

Now I am trying to use the SandcastleBuilderConsole instead of the GUI and I get the following error

"Error: BuildAssembler: The type 'SandcastleBuilder.Components.ShowMissingComponent' was not found in the component assembly 'C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilder.Components.dll'."

Can you or Dave help me with this. I am using
Jan 25, 2008 at 5:57 PM
Eric I downloaded the latest version you uploaded on January 22 and it worked.

I have one more question. I missed some of the namespace summaries and when the .chm is generated under description for the namespace it read
"Missing namespace summary documentation for N:ProjectLoader"

How can I disable that?

Thanks for the help guys
Jan 25, 2008 at 6:47 PM
Eric I was able to disable the Missing Name space summary too.
One last question is the output .chm is generated with a default name how can i change the name?

Jan 25, 2008 at 8:24 PM
Edited Jan 25, 2008 at 8:28 PM
You can use the HtmlHelpName project property to set the name of the help file. Don't include a path or extention. They are added automatically during the build.

Jan 25, 2008 at 10:39 PM
Thanks Eric. It was right there I just overlooked. You saved my day!

This process is paifully slow. Last time I used sandcastle help file builder to build the .chm file it took nearly 30 hours for my 400+ assemblies. But NDoc is really fast when compared nearly 3 hours.

Why do you think it is taking so long?

Thanks a million,
Jan 25, 2008 at 11:12 PM
Hi KP,

Sandcastle generates topics by running XML input files through a series of XSL transformations and build components, making the process extremely flexible at the cost of performance (although performance has improved during its development). For example, you can completely modify the existing presentation styles (or even create your own) to produce any conceivable style of XML-based documentation. I don't think NDoc supports such a high level of flexibility.

- Dave
Jan 26, 2008 at 3:19 AM
Edited Jan 26, 2008 at 3:20 AM
You can examine the build log to see how long each step took. That may help identify possible bottlenecks. I did add some cached build components which may improve performance a little but with such a large project they may not make much difference in this case. You can add them via the ComponentConfigurations project property. It takes one build to create the caches and after that you'd see any improvement they provide. If you'd care to post the timing results over in the SHFB forum or e-mail me the build log, I may be able to offer some ideas specific to SHFB or see if there's possibly somewhere I may be able to improve performance in the SHFB-related steps.

Feb 4, 2008 at 9:26 AM
Edited Feb 4, 2008 at 9:27 AM
Hi KP,
Can you send me the build log? My email is "v-wenjp AT". I would like to investigate the perf issue you mentioned. It does not take 30 hours for us to build help doc for .Net framework.
I will be on vacation soon, so my response will be delayed. Thanks.
Feb 5, 2008 at 4:39 PM
Hi Eric & Steve,

I've been away for quite some time. I am sorry I couldn't reply to your messages. I donot have the build log as of now as I kept overwriting them with new builds. I didn't want to do the whole build as I said earlier it was time consuming. So I am just making sure that the process is initiated without any hickups.

But I will do a complete build this weekend and will see if I can send the log to you. The only reason I am skeptical about sending the log is that it contains the information about my organizarion's product's assemblies. However, as far as sharing information about how long each step is taking I can do that I suppose.

Finally, a question. Is there a flag or something that indicated if the build is successful or not at the end of the process? cause I am trying to send an email message depending on the success of the help file generation.

Thanks a million

StevenPei wrote:
Hi KP,
Can you send me the build log? My email is "v-wenjp AT". I would like to investigate the perf issue you mentioned. It does not take 30 hours for us to build help doc for .Net framework.
I will be on vacation soon, so my response will be delayed. Thanks.

Feb 5, 2008 at 10:14 PM
SHFB has a Completion Notification plug-in. Select the PlugInConfigurations project property and click the "..." button to the right of it to open the configuration dialog. In it, select the Completion Notification plug-in and add it to the project then configure it to specify where to send the notification on failure and/or success.