An implementation of HTTP Caching in .NET Core and 4.52+ for HttpClient, ASP.NET Web API, ASP.NET MVC Core and Carter.
This document covers topics below:
There are quite a few changes in the server-side implementation of CacheCow due to shortcomings of previous approach while the client-side mostly remained the same. Hence if you have used CacheCow.Server in the past and you would like to migrate, read the guide on migration further down. CacheCow.Client has some changes which may or may not break your code (depending whether you had used .NET 4.5 packages) which includes:
It is useful to start with concepts but feel free to use it as a reference. If you get bored reading this 😀, jump straight to Getting Started sections or simply browse and run a couple of samples.
HttpClient
./api/car/1
is a resource and it might have two representations as JSON or XML. Also the same resource could have two representations in Chinese or Spanish. Headers by which representations will vary is defined by the Vary
header from the server.Cache-Control
, Vary
, ETag
and in HTTP 1.0 would include Expires
, Last-Modified
and Pragma
(for the purpose of this article, we include ETag
and Last-Modified
as part of directives although purely speaking they are not). CacheCow has ICacheDirectiveProvider
interface responsible for controlling these headers.Expires
header: Defines expiry of a resource in absolute time. Cache-Control
header provides richer semantic and supersedes it. CacheCow sets both to support both HTTP 1.0 and 1.1. Last-Modified
header: Since its precision is at seconds, its use is not recommended for valiation and instead, it is recommended to use ETag
.ETag
header: ETag or EntityTag is an opaque string that identifies a version of resource (not representation). If you have a high-precision Last-Modified date, it is better to turn it to ETag by binarising the date (example).TimedEntityTagHeaderValue
. It is recommended to construct it with an ETag (due to low precision of DateTime in HTTP Spec's Last-Modified
header).ITimedETagExtractor
: A CacheCow interface responsible for extracting TimedETag from view models sent back by the API. By default, it checks to see if the ViewModel has implemented ICacheResource, if so it enquires the TimedETag directly. If not, it will resort to serialising the ViewModel to JSON and use its hash as ETag. This can be expensive hence it is suggested to either your ViewModels implementing ICacheResource
interface or implement ITimedETagExtractor
- plenty of examples in the samples.Last-Modified
date supplied. This is known as conditional PUT/PATCH/DELETE. CacheCow supports these scenarios OOB.SELECT COUNT(1), MAX(LastModifiedDate) FROM MyTable
). Such queries will be fast and cheap. CacheCow provides ITimedETagQueryProvider
interface to preemptively query the backend stores for conditional HTTP calls without load the resources.ITimedETagQueryProvider
: This interface allows server implementations to query their back-end and carry out validation against it. This is the best way to have APIs support consistency and the most efficient level of caching. Client scenario is perhaps the most common use case of CacheCow. Most of the concepts discussed above relate to the server-side. Client-side CacheCow has been implemented as a DelegatingHandler and has very few concept counts - most of the complexity of HTTP Caching has been hidden away from you. For the purpose of this guide, we choose an In-Memory storage which is the default.
> install-package CacheCow.Client
HttpClient
(piped to a CachingHandler
fronted by HttpClientHandler
):var client = ClientExtensions.CreateClient();
This is simply a helper and you saves you writing a couple of lines of code.
JQuery CDN is a handy little cacheable resource. We make a call twice and check CacheCow header:
const string CacheableResource = "https://code.jquery.com/jquery-3.3.1.slim.min.js";
var response = client.GetAsync(CacheableResource).
ConfigureAwait(false).GetAwaiter().GetResult();
var responseFromCache = client.GetAsync(CacheableResource).
ConfigureAwait(false).GetAwaiter().GetResult();
Console.WriteLine(response.Headers.GetCacheCowHeader().ToString()); // outputs "2.0.0.0;did-not-exist=true"
Console.WriteLine(responseFromCache.Headers.GetCacheCowHeader().ToString()); // outputs "2.0.0.0;did-not-exist=false;retrieved-from-cache=true"
As you can see, second time round the resource came from the cache and the request did not even hit the network.
NOTE: In-Memory storage is OK for test scenarios or cases where the load is limited. In many cases you would choose to use Redis storage or you can implement your own if you need to. If you would need an alternative storage not yet supported, feel free to discuss by opening an issue before sending a PR.
From CacheCow 2.0, ASP.NET MVC Core scenarios are supported. Server-side CacheCow has been implemented as a Resource Filter.
> install-package CacheCow.Server.Core.Mvc
public virtual void ConfigureServices(IServiceCollection services)
{
... // usual startup code
services.AddHttpCachingMvc(); // add HTTP Caching for Core MVC
}
HttpCacheFactory
attributeProvide the expiry as the first parameter (number of seconds):
public class MyController : Controller
{
[HttpGet]
[HttpCacheFactory(300)]
public IActionResult Get(int id)
{
... // implementation
}
}
Here we have set the expiry to 5 minutes. This covers the basic scenario, browse the samples for the advanced and efficient use cases.
Web API has always been supported by CacheCow but the server-side has been radically changed. There is no more a DelegatingHandler and all you need is to decorate your actions with the HttpCache
filter.
> install-package CacheCow.Server.WebApi
HttpCache
attributeProvide the expiry as a parameter (number of seconds):
public class MyController : ApiController
{
[HttpGet]
[HttpCache(DefaultExpirySeconds = 300)]
public IHttpActionResult Get(int id)
{
...
}
}
Here we have set the expiry to 5 minutes. This covers the basic scenario, browse the samples for the advanced and efficient use cases.
CacheCow.Client and CacheCow.Server variants include diagnostic headers (x-cachecow-client
and x-cachecow-server
) to inform you of the actions taken and their results. They are useful in debugging and in case you would like to log them to understand cache hit ratios.
The header name is x-cachecow-client
and can optionally contain extensions below (values separated by semicolon) depending on the scenario:
was-stale
: whether the stored representation was staledid-not-exist
: the requested representation did not exist in the cachenot-cacheable
: the request or response were not cacheable (due to status, various headers and directives)cache-validation-applied
: CacheCow attempted the HTTP call (GET, PUT, PATCH or DELETE) with cache validationretrieved-from-cache
: whether the representation ultimately came from the cache or the one sent by the serverThe header name is x-cachecow-server
and contains extensions below (values separated by semicolon):
validation-applied
: whether validation was attemptedvalidation-matched
: validation attempted and the conditions met (resulting in 304 for GET and 2xx for PUT/PATCH/DELETE)short-circuited
: the request was short-circuited and did not hit deeper API layers (with status 304 or 412)query-made
: ITimedETagQueryProvider
made a query to the back-end stores CacheCow project contains 3 sample projects that demonstrate how to use both client and server libraries. The samples are exactly similar in functionality, shared by CacheCow.Samples.Common
project. Server is an API hosting functionality for adding, modifying and querying cars. it a command-line interface with 6 options to choose from:
After choosing options A, L or X application prints the value of the CacheCow header from both client and the server. These values will denote the caching actions taken and their result.
You can test and try different scenarios. For example:
You can run this sample on Windows, Mac and Linux and requires .NET Core +2.0. Essentially in your shell of your choice cd
to the CacheCow.Samples.MvcCore
folder and type:
dotnet run
This is a simple Web API example that displays out-of-the-box features for Web API. This sample is in .NET 4.52 and you can build and run as a console app on Windows.
This is an advanced Web API example that displays advanced features of server-side CacheCow, especially IoC. This sample is in .NET 4.52 and you can build and run as a console app on Windows.
This sample is for a typical Carter implementation. You can run this sample on Windows, Mac and Linux and requires .NET Core +2.0. Essentially in your shell of your choice cd
to the CacheCow.Samples.Carter
folder and type:
dotnet run
Scenarios in the Getting-Started sections above choose simple out-of-the-box options to get you started. Depending on the load on your server, these are not necessarily the optimal. To get the best out of your API's caching, you would have to do a little more work and help CacheCow optimise HTTP Caching. By default, CacheCow server relies on Serialising your payloads/viewmodels to generate ETag. While for low-mid traffic scenarios this could be sufficient, it would be detrimental for high-load APIs or cases where your payload is big. That is why, instead of leaving CacheCow to generate ETag (rather TimedETag) by serialisation, you could supply it yourself.
There are two times when a TimedETag is needed:
TimedETag needs to be included in the response headers (in the form of ETag
or Last-Modified
headers). If your view models implement ICacheResource
, CacheCow will attempt to get TimedETag by calling interface's only method. Otherwise it will use serialisation unless you provide an alternative ITimedETagExtractor
implementation that extracts the TimedETag. And example would be an implementation that uses LastModifiedDate field and turns it into an ETag by binarisation (example here).
This is the preemotive validation of the resource in response to conditional GET (or PUT/PATCH/DELETE). In case of a conditional GET, client requests for a later version of the resource unless it has changed since it has had its version, providing its last modified date or ETag(s). In this case, by default, CacheCow allows the call to controller to load the view model and then generates its TimedETag (by querying ICacheResource
or serialisation). If the version the client has is still the most recent, it will send back status 304 or NotModified. While this reduces network traffic and reduces server (and client) resource usage, it does not relieve pressure from your back-end services. That is where ITimedETagQueryProvider
interface comes into play: by implementing this interface you could go back to your back-end store and check whether the condition is met without loading the whole view model from the back-end services. For example, you could go back to the record requested and check if the LastModifiedDate matches.
This table highlights different options in CacheCow.Server and value associated with each.
ASP.NET Core can already integrate with Dependency Injection frameworks and supports resolving its own dependencies through such abstractions. One of the challenges with server-side CacheCow is that there interfaces such as ITimedETagExtractor
or ITimedETagQueryProvider
would have implementations that would be different for different resources (rather view models). For example, if an API serves 3 entities as Customer
, Product
and Order
you would need 6 different implementations, one for each entity and one for each collection (e.g. IEnumerable<Customer>
). It would be certainly cleaner to have one implementation per each and somehow know the view model type of each action. Looking at the return type is an option but quite commonly actions return IActionResult
.
So the solution is to let the filter on the action define the type of the view model. Hence, for example, on a CarController
's Get
action, you would define ViewModelType
in the attribute as below:
public class CarController : Controller
{
[HttpGet]
[HttpCacheFactory(300, ViewModelType = typeof(Car))]
public IActionResult Get(int id)
{
... // implementation
}
}
This will help CacheCow to know that it should look for ITimedETagExtractor<Car>
and you would create an implementation for ITimedETagExtractor<Car>
and register it on your DI container.
The same applies to ITimedETagQueryProvider<T>
, essentially: 1) define ViewModelType
on filter 2) implement generic interfaces 3) register them in your container
CacheCow uses Options Pattern to allow consumers to configure a few options at the time of using AddHttpCachingMvc
. Currently you can control whether to emit CacheCow diagnostic header (for now default is true
) and also whether respect configuration:
services.AddHttpCachingMvc(options =>
{
options.EnableConfiguration = true; // default is false
options.DoNotEmitCacheCowHeader = false; // default is true
});
If you enable configuration (using EnableConfiguration = true
), CacheCow will try to read expiry values from .NET Core's IConfiguration
. For example using the appsettings.json below, you can override the settings defined in the attribute:
{
"CacheCow":
{
"Test":
{
"Get":
{
"Expiry": "00:00:10"
}
}
}
}
Example below assumes a controller of "Test" and action of "Get" and it sets the cache expiry to 10 seconds. The value of controller and action are picked up from the route data and the keys need to be defined under "CacheCow" entry.
As per .NET Core configuration, you can override file configuration values with environment variables or command line arguments.
At this point, there is also "Enabled" property that can be set to false to disable CacheCow for a particular controller/action - something that might be handy during development. For example, setting environment variable "CacheCowTestGet__Enabled" to "false" will turn off CacheCow functionality on action Get of controller Test.
You should first register default types in your Web API Dependency Resolver:
// registering in a Windsor Castle container
CachingRuntime.RegisterDefaultTypes((
(t1, t2, isTransient) =>
{
if (isTransient)
container.Register(Component.For(t1).ImplementedBy(t2).LifestyleTransient());
else
container.Register(Component.For(t1).ImplementedBy(t2).LifestyleSingleton());
}));
The rest to use ITimedETagExtractor<T>
and ITimedETagQueryProvider<T>
is similar to ASP.NET Core: simply define ViewModelType and register your dependencies.
Almost all projects using CacheCow.Client would carry on working in version 2.0. But servider-side implementation has been radically changed and in many ways simplified. In order to migrate: