Sunday 1 December 2013

CacheCow 0.5.0-alpha released for community review: new features and breaking changes

[Level T3]

CacheCow 0.5 was long time coming but with everything that was happening, I am already 1 month behind. So I have now released it as alpha so I can get some feedback from teh community.

As some of you know, a few API improvements had been postponed due to breaking changes. On the other hand, there were a few areas I really needed to nail down - the most important one being resource organisation. While resource organisation can be anything, most common approach is to stick with the standards Web API routing, i.e. "/api/{controller}/{id}" where api/{controller} is a collection resource and api/{controller}/{id} is an instance resource.

I will go through some of the new features and changes and really appreciate if you spend a bit of time reviewing and sending me feedbacks.

No more dependency on WebHost package

OK, this has been asked by Darrel and Tugberk and only made sense. So in version 0.4 I added dependency to HttpConfiguration but in order not to break the compatibility, it would use GlobalConfiguration.Configuration in WebHost by default. This has been removed now so an instance of HttpConfiguration needs to be passed in. This is a breaking change but fixing it should be a minimal change in your code from:
var handler = new CachingHandler(entityTagStore);
You would write:
var handler = new CachingHandler(config, entityTagStore);

CacheKeyGenerator is gone

CacheKeyGenerator was providing a flexibility for generating CacheKey from resource and Vary headers. Reality is, there is no need to provide extensibility points. This is part of the framework which needs to be internal. At the end of the day, Vary headers and URL of the resource are important for generating the CacheKey and that is implemented inside CacheKey. Exposing CacheKeyGenerator had lead to some misuses and confusions surrounding its use cases and had to go.

RoutePatternProvider is reborn

A lot of work has been focused on optimising RoutePatternProvider and possible use cases. First of all, signature has been changed to receive the whole request rather than bits and pieces (URL and value of Vary headers as a SelectMany result).

So the work basically looked at the meaning of Cache Key. Basically we have two connected concepts: representation and resource. A resource can have many representations (XML, image, JSON, different encoding or languages). In terms of caching, representations are identified by a strong ETag while resource will have a weak ETag since it cannot be guaranteed that all its representations are byte-by-byte equal - and in fact they are not.

A resource and its representations

It is important to note that each representation needs to be cached separately, however, once the resource is changed, the cache for all representations are invalidated. This was the fundamental area missing in CacheCow implementation and has been added now. Basically, IEntityTagStore has a new method: RemoveResource. This method is pivotal and gets called when a resource is changed.

The change in RoutePatternProvider is not just a delegate, it is now an interface: IRoutePatternProvider. Reason for the change to delegate is that we have a new method in there too: GetLinkedRoutePatterns. So what is a RoutePattern?

RoutePattern is basically similar to a route and its definition conventions in ASP.NET, however, it is meant for resources and their relationships. I will write a separate post on this but basically RoutePattern is in relation to collection resources and instance resources. Let's imagine a car API hosted at http://server/api. In this case, http://server/api/car refers to all cars while http://server/api/car/123 refers to a car with Id of 123. In order to represent this, we use * sign for collection resources and + sign for instance:

http://server/api/car         collection         http://server/api/car/*
http://server/api/car/123     instance           http://server/api/car/+  

Now normally:

  • POST to collection invalidates collection
  • POST to instance invalidates both instance and collection
  • PUT or PATCH to instance invalidates both instance and collection
  • DELETE to instance invalidates both instance and collection

So in brief, change to collection invalidates collection and change to instance invalidates both.

In a hierarchical resource structure this can get even more complex. If /api/parent/123 gets deleted, /api/parent/123/* (collection) and /api/parent/123/+ will most likely get invalidated since they do not exist any more. However, implementing this without making some major assumptions is not possible hence its implementation is left to the CacheCow users to tailor for their own API.

However, since a flat resource organisation (defining all resources using "/api/{controller}/{id}") is quite common, I have implemented IRoutePatternProvider for flat structures in ConventionalRoutePatternProvider which is the default.

Prefixing SQL Server Script names with Server_ and Client_

The fact was that SQL Server EntityTagStore (on the server package) and CacheStore (on the client package) had some stored procedure name clashes preventing use of the same database for both client and server component. This was requested by Ben Foster and has been done now.

Please provide feedback

I hope this makes sense and waiting for your feedbacks. Please ping me on twitter or ask your questions in Github by raising issue.

Happy coding ...


  1. CacheCow.Server 0.5.0-alpha has dependency on "CacheCow.Common (≥ 0.5.0)", but it is not available and installation of CacheCow.Server 0.5.0-alpha is failing.

    1. Thank you! I have just uploaded the missing package. Please let me know if it does not work.

    2. Thanks.

      This issue is fixed but now getting following error:

      Could not load file or assembly 'System.Net.Http.Formatting, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)

    3. And now there is no default constructor available for CachingHandler class.

      Any particular reason to remove the default constructor ?
      Or, now we don't need to add the CacheHandler object to HttpConfiguration's MessageHandlers ?

    4. I have explained about the constructor change in the article "This has been removed now so an instance of HttpConfiguration needs to be passed in".

      For assembly issues, you need to use assembly redirect. Something similar to this:

  2. Hi aliostad,

    CacheCow is really a nice piece of software and I like it very much. In my current WebAPI project unfortunately not all resources are changed by http post/put/delete, so that I would need a mechanism in order to generate the ETag according to the (everytime generated) result object. Could you please give me a hint whether I can use CacheCow in this way?

    Thanks in advance

    Best regards


    1. Hi Florian. I am pleased to hear that. I am hoping to make it a better with your feedbacks.

      This is an area I am working on as it is a common use case. If you browse the code, you will find this the class ContentHashETagGenerator. Version 0.5 will have this functionality.

  3. Hi aliostad,

    I already had a look at the code and I had the impression that the ContentHashETagGenerator was triggered by the ContentHashETagAttribute. If you tell me where the missing parts are, I could even help you to get it done.

    Best regards


  4. Hi aliostad,

    thanks for creating CacheCow, at first glance it looks really nice and easy to set up. However, I'm having difficulties in finding documentation on how to use CacheCow after the initial setup. In your blog posts and on GitHub there's much talk about things like CacheControlPolicy and RoutePatterns, but I can't find any documentation on how to use them.
    Specifically, in my project I need more control in my resources (server side) to invalidate the cache. E.g. a PUT on resource 'orderline' should invalidate the cache for resource 'order'. Can I do that with CacheCow? Where to find documentation?


    1. Hi Sophie. I think I need to add a FAQ and common scenario list on GitHub which I will try to do. Now, in terms of the scenario you have in mind, it is possible but you have to implement that yourself. CacheCow only supports one level invalidation (collection and instance resource such as cars/1 and cars/) and more levels need to be implemented by the application. Please ask the question in GitHub (open an issue) and I can provide more insight.


Note: only a member of this blog may post a comment.