On a recent project, I wanted to do file-based caching in a console application. I figured the memory-mapped file implementation in the Caching Application Block for .NET would be a good place to start.
I haven't really use these blocks very often, but I did look through the Data Access and Smart Client Offline blocks. I found both of these to be generally very high quality, especially in the surrounding documentation. After all, that's the point - these are supposed to be best practices out of the Patterns & Practices group.
Unfortunately, it really seems like the Caching block was slapped together.
The documentation is poor at best. It seems that the authors of the block have largely deferred to the Caching Architecture Guide - which is actually pretty decent, but it isn't based on the application block implementation. In a fairly sophisticated system, the diagram below is the only design artifact (with about 5 lines of text below it explaining it):
The documentation on how to use the block isn't much better - it's quite short and is mostly dedicated on how to add a reference to their assembly (This section is actually in all of the application blocks, but man - we have much bigger problems if architects don't know how to add a damned reference).
I thought the included quickstarts might be useful - that is, until I looked at them.
The package installs three QuickStart sample apps: AggregationServiceAgents, AsyncServiceAgents, and QuickStartSampleApp. There is code that uses the Asynchronous Invocation block and code that uses the Aggregation block, but nothing that uses the Caching block.
Seriously.
In fact, nowhere in these sample apps is the Caching assembly even referenced. Even if those other two blocks internally used the Caching (which they don't), I fail to see how that's particularly useful - the sample shows you how to use the other blocks, but not how to use the Caching block itself.
Further investigation reveals that these three blocks - Caching, Aggregation and Async Invocation - were all done by the same team. All three have the same samples and the same generally poor quality in documentation - especially when compared to some of the other blocks like Data Access and Smart Client Offline.
I just don't get it.
In the course of working on various framework-level products over the past few years, I've been involved in a number of reference applications. The primary value from these implementations is not so much the code itself but the design and architecture. Thus, good documentation that explains what architectural decisions were made, and why, is of the utmost importance. Most of the time, we actually worked backwards from some documentation (of course, with some tweaking along the way as we reconciled the two).
What's the point? Without the design documentation, it isn't all that useful as a reference. I'm also reluctant to use it purely as a 3rd party component as it is. I haven't been able to get the memory-mapped file bit to actually work - and while I'm sure I'm doing something wrong, the documentation sure hasn't been much help.
Needless to say, this Caching application block has been rather disappointing.
(By the way, Tomas Reseptro has a simple library called FileMap, that wraps the Win32 Memory Mapped File stuff. I think I'm going to take a look through that this weekend and see if will be useful.)