Why is sandcastle so slow?

Jul 25, 2008 at 9:40 AM

just out of curiosity: Why does it take so long to build docs using Sandcastle? If I simply add one single MAML file, it takes about 30 to 60 seconds on a Core 2 Duo with 2.4 GHz and 4 GBytes RAM. Is this normal?


Jul 25, 2008 at 11:57 AM
Are you building with the basic script or using third party tools?

Best regards,
Jul 25, 2008 at 12:24 PM

I am using SHFB 1.7.


Jul 25, 2008 at 2:27 PM
Edited Jul 25, 2008 at 2:28 PM

Hello Golo,

Sandcastle is designed to offer maximum flexibility by using a system similar to assembly line in a modern manufacturing line - you start at one end and many sub-steps modify and shape it until it reaches the other end.
So unlike tools like the NDoc, you pay the price in terms of speed.

For simply work involving one or two files, like the assembly line, the system will take time to initialize or warm up so you will notice this overhead.
Note: The third party tools may add to the overhead.

For the normal multi-file project, unlike the assembly line, the Sandcastle build processes idle for a single step to be completed before starting the next. Currently, much effort is into the output with little into speeding up the build process - beyond code optimization. With the output getting stabilized, you will see improvements
in the build process soon.

Best regards,

Jul 25, 2008 at 3:58 PM
You can take a look at the build times in the log file to see which step(s) are taking the longest.  Most complete in a few seconds.  The longest step, and the most likely offender regarding slowness, is the BuildAssembler step.  The reference link component can take 20 to 30 seconds to initialize as it has to index all of the framework elements.  If you have SdkLinkType set to MSDN, that can slow down the build a little too as it has to contact the MSDN web service to resolve links to the online framework content.  Some of this time can be offset by using the cached build components that come with SHFB.  Use the ComponentConfigurations option to add them to the project.  See the help file for information on what is cached.

Jul 25, 2008 at 6:12 PM
Hi Golo,

It may be worth pointing out that the initial startup time is basically a constant factor in Sandcastle.  So try adding another MAML topic and you should see that the time doesn't change much at all.  As Eric mentioned already, the Framework link type that you choose is another variable in the speed of the build, so if you choose to not resolve MSDN links then you should see a fairly constant time with each additional MAML file only adding a very small delay, relative to the entire process.  With MSDN links enabled that small delay is a bit more variable and unpredictable, since Sandcastle is making a web service call for each .NET API reference (barring caching), but the time it takes to produce each topic is still much smaller than the initial constant startup cost.
Jul 26, 2008 at 12:57 AM
Hey ...

Thanks for your answers :-). I will check out the log files and see what I can find out ...