Experimental Release Feedback

Topics: User Forum
Nov 27, 2007 at 3:34 AM
Edited Jan 22, 2008 at 11:56 PM
This thread is only for leaving feedback about the new cached build components in the release

The three new build components are as follows:

  • Cached Framework Comments Index Data - Caches index file information about the location of the framework member comments.
  • Cached Reflection Index Data - Caches index file information about the location of the framework members in the reflection data files.
  • Cached MSDN URL References - Caches resolved MSDN URLs for the Resolve Reference Links build component when SdkLinkType is set to MSDN. This saves it having to hit the web service in every build to get the same information.

To use these components, select the ComponentConfigurations property in the project and add the three components noted above to your project. The configurations for each are editable as raw XML but you shouldn't need to change anything unless you want to alter the default location for storing the cache files. I'll add proper configuration dialogs for them if they prove to be useful.

If using the build components in your own build scripts or with other build tools, see the Example.config file included with the standalone build component download for an example of how to add the configuration to the file.

NOTE: You must perform at least one build with any project to create the comments and reflection data cache files. The MSDN URL cache is cumulative so you must perform at least one build with each project that you add it to so as to ensure that all URLs for the given project are in the cache.

What I am looking for:
I'd like to get an idea for which types of projects these build components are useful. If you can provide information about build time improvements, be sure to include information about the PC on which the build was done (CPU speed, single/dual core, amount of RAM, and the type and speed of connection to the internet). You can download the Timing Tests file from the Releases page to get an idea of what I did although you do not have to go to the
trouble of getting as detailed. It's an Excel spreadsheet containing the results that I got from using them on several of my projects. The cells with the red marker in the corner contain comments. Hover the mouse over them to get a description of the information. The timings are for the BuildAssembler step alone and do not include time for all the other steps prior to or after it. After a build, you can look at the log file, scroll down to the end of the BuildAssembler step and find information about the length of time it took to run and about cache information reported by the new build components.

These are my initial observations using the new components in my own projects:

  • The first two provide the least benefit and are fairly consistent in the amount of time saved. They benefit small projects with shorter build times the most and, to a certain extent, can be used to offset the rather lengthy initialization time of the Resolve Reference Links component (I could not do anything about that part of it unfortunately, see below).
  • The cached MSDN URL component can provide a huge performance increase. This will be most evident in control libraries in which the classes are derived from Windows Forms and web controls which have a large number of inherited members thus causing a spike in the number of MSDN lookups that occur. Non-UI projects with base classes that are simpler result in fewer lookups and benefit less.
  • Using the cached MSDN URL component is, after the initial build, almost equivalent to setting the SdkLinkType property to None in regards to build time but adds the benefit of keeping the links in place.
  • That said, the larger the project the less benefit you may see. For example, if your project contains 10,000+ topics, it's already going to run pretty long and the few minutes saved by the cached URLs may end up making little difference in the end. I don't have any large projects like that which is why I'd like to get some more feedback to see at what point the caching becomes irrelevant to the build.

I did try to cache the index information generated when the Resolve Reference Links component initializes but in that case, the information is much more complex and there is so much of it that there was a negative impact on performance. As such, it must still load the index information in the normal fashion when it starts. As noted, you can use the first two cached build components to offset that a little.

If anything need further explanation, please post here. Thanks!

Feb 19, 2008 at 5:40 PM
Hi Eric,
I am trying out the Cache components since my build is taking much longer using than Reading the documentation above, it is not clear to me if I should set SDKType property to None when I am using the Cached MSDN URL.

Here's the background. I did my first build with SDKType as None and without setting Cached MSDN. That build took almost 6 hrs (previously with and SDKType set to MSDN took only alittle more than 1 hour). I am now running my second build with with SDKType at None and Cached MSDN is on. It is still running after four hours. Am I just cancelling out the MSDN cache with a setting of None?

I am running on a Pentium 4 single CPU, 2.60 GHz, 3.56 GB RAM
Feb 19, 2008 at 6:26 PM
Edited Feb 19, 2008 at 6:27 PM
To have any benefit, SdkLinkType needs to be set to MSDN so that it actually goes out and contacts the web service to cache the MSDN URLs. After the first build, it will then use the cache. Setting the link type to None disables that so they won't be used. Using the cache, it doesn't have to contact the web service so speed-wise, its equivalent to using the None setting but you still get links to the online content.

Did you perhaps change presentation styles? The Hana and VS2005 styles do take longer than Prototype. Other than that, I can't think why things would be so much slower as there wasn't that much that changed.

Feb 19, 2008 at 8:16 PM
I changed some elements of the VS2005 presentation style, mostly the color of headings and table backgrounds. Maybe that is enough to slow things down. My project has ~13,000 topics.

I am quite happy using, except I would like to take advantage of the MSDN cache feature, so I will keep testing with it.

Mar 7, 2008 at 6:41 AM
Hi Eric,

I would like to cache both reflection information and comments of the .NET framework. I turned on both Cached Framework Comments Index Data and Cached Reflection Index Data (nothing else, no plugins yet). BuildAssembler failed in the second CachedCopyFromIndexComponent, however.

I tried both SHFB and beta. The exception is thrown either if the cache does or does not not exist. I use Sandcastle from January with your presentation patch.

Merging custom build component configurations
Replaced configuration for 'Microsoft.Ddue.Tools.CopyFromIndexComponent' (instance 1) with configuration for 'Cached Reflection Index Data'
Replaced configuration for 'Microsoft.Ddue.Tools.CopyFromIndexComponent' (instance 3) with configuration for 'Cached Framework Comments Index Data'
Info: CachedCopyFromIndexComponent: Instantiating component.
Info: CachedCopyFromIndexComponent: Searching for files that match 'reflection.xml'.
Info: CachedCopyFromIndexComponent: Indexed 7 elements in 1 files.
Info: CachedCopyFromIndexComponent:
Sandcastle Help File Builder Components, version
Cached Copy From Index Component. Copyright c 2006-2008, Eric Woodruff, All Rights Reserved
Warn: CachedCopyFromIndexComponent: E:\Sources\SHFB1605\SandcastleBuilder\SandcastleBuilderGui\bin\Debug\BuildComponents\Cache\SandcastleReflection.cache does not exist and is being created
Info: CopyFromIndexComponent: Instantiating component.
Info: CopyFromIndexComponent: Searching for files that match '*.xml'.
Info: CopyFromIndexComponent: Indexed 170091 elements in 106 files.
Info: CachedCopyFromIndexComponent: Loaded 170091 items from the cache
Info: CachedCopyFromIndexComponent: Instantiating component.
Info: CachedCopyFromIndexComponent: Searching for files that match 'r:\temp\DocuTest\Library1\doc\Library1.xml'.
Info: CachedCopyFromIndexComponent: Indexed 4 elements in 1 files.
Error: BuildAssembler: An error occured while initializing the build component 'SandcastleBuilder.Components.CachedCopyFromIndexComponent' in the component assembly 'E:\Sources\SHFB1605\SandcastleBuilder\SandcastleBuilderGui\bin\Debug\SandcastleBuilder.Components.dll'. The error message and stack trace follows: System.ArgumentException: An item with the same key has already been added.
at System.ThrowHelper.ThrowArgumentException(ExceptionResource resource)
at System.Collections.Generic.Dictionary`2.Insert(TKey key, TValue value, Boolean add)
at System.Collections.Generic.Dictionary`2.Add(TKey key, TValue value)
at Microsoft.Ddue.Tools.CopyFromIndexComponent..ctor(BuildAssembler assembler, XPathNavigator configuration)
at SandcastleBuilder.Components.CachedCopyFromIndexComponent..ctor(BuildAssembler assembler, XPathNavigator configuration)
Last step completed in 00:00:35.5000

Do you have any clue why it should fail? I can send you the complete project (a very small testing assembly).

Mar 7, 2008 at 3:02 PM
It happened with one other person but they couldn't send me their project so I had to guess as to the fix which apparently didn't work. I would appreciate it if you could send me your test project so that I can debug it. My e-mail address is in the About box and in the footer of the pages in the help file. Thanks.

Mar 8, 2008 at 11:21 AM
I mailed you one working and one testing project. I found out that the component Cached MSDN URL References even turned off caused the failure. I added it at the beginning and removed again later and the error was still there. Creating a fresh project without it the two components coexisted well. Maybe the order of the components makes the difference. I hope that you will be able to reproduce it.

Mar 9, 2008 at 6:35 PM
I found and fixed the bug that was causing this. The fix will be in the next release.

Mar 22, 2008 at 4:52 PM
Well, I finally got my versions straightened out, and here are my initial results for the Cached Build Components:

Feedback for Cached Build Components

3.0 GHz Intel DualCore CPU
1.0 GB RAM
8.0 Mbps Cable HighSpeed

Project: (Subclassed WinForms Control)
1 Namespace
29 Types
135 Members

Help File:
255 Topics
2303 Local Links
4081 MSDN Links


Time: 4:45:9375

Time: 5:26:2344


Time: 1:30:0781

Time: 2:05:5000

Cached MSDN URL's : 892
Cached Index Data : 5 reflection entries, 5 comments entries

Well done, Eric. Upwards of 60% reduction in processing time. Of course, this project exactly matches your profile of the most likely to benefit, and at this point, it has none of the substantial additonal content that it will have. But, most of the link traffic from the additional content will be back into the API documentation, not out to MSDN, so I'm tickled to death with the massive improvement. Good Job!

Mar 22, 2008 at 8:01 PM
Thanks for the feedback. Additional content usually gets processed really fast so it shouldn't add too much time to the build.