FusionCache is an easy to use, fast and robust hybrid cache with advanced resiliency features.
Being a hybrid cache means that it can work both as a normal memory cache (L1) or, optionally, as a multi-level cache (L1+L2) where the 2nd level can be any implementation of the standard IDistributedCache interface. This will get us better better scalability, better performance and more resiliency in a multi-node scenario or even just to ease cold starts (initial empty cache, maybe after a restart).
Optionally, it can also use a backplane: in a multi-node scenario this will send notifications to the other nodes to keep each node's memory cache perfectly synchronized, without any additional work.
FusionCache also includes some advanced resiliency features like a fail-safe mechanism, cache stampede prevention, fine grained soft/hard timeouts with background factory completion, eager refresh, full observability via logging and OpenTelemetry and more (see below).
FusionCache tries to feel like a native part of .NET by adhering to the naming conventions of the standard memory and distributed cache components:
| MemoryCache | DistributedCache | FusionCache | |
|---|---|---|---|
| Interface | IMemoryCache |
IDistributedCache |
IFusionCache |
| Implementation | MemoryCache |
[Various]Cache |
FusionCache |
| Options | MemoryCacheOptions |
[Various]CacheOptions |
FusionCacheOptions |
| Entry Options | MemoryCacheEntryOptions |
DistributedCacheEntryOptions |
FusionCacheEntryOptions |
If we have ever used one of those, we'll feel at home with FusionCache.
🚀 Factory (more)
A factory is just a function that we specify when using the main GetOrSet[Async] method: basically it's the way we specify how to get a value when it's needed.
Here's an example:
var id = 42;
var product = cache.GetOrSet<Product>(
$"product:{id}",
_ => GetProductFromDb(id), // THIS IS THE FACTORY
options => options.SetDuration(TimeSpan.FromMinutes(1))
);FusionCache will search for the value in the cache (memory and distributed, if available) and, if nothing is there, will call the factory to obtain the value: it then saves it into the cache with the specified options, and returns it to the caller, all transparently.
Special care has been put into ensuring that only 1 factory per-key will be executed concurrently, to avoid what is known as Cache Stampede.
Read more here, or enjoy the complete step by step guide.
🔀 Cache Levels (more)
There are 2 caching levels, transparently handled by FusionCache for us.
These are:
- 1️⃣ Primary: it's a memory cache, is always there and is used to have a very fast access to data in memory, with high data locality. We can give FusionCache any implementation of
IMemoryCacheor let FusionCache create one for us - 2️⃣ Secondary: is an optional distributed cache (any implementation of
IDistributedCachewill work) and, since it's not strictly necessary and it serves the purpose of easing a cold start or coordinating with other nodes, it is treated differently than the primary one. This means that any potential error happening on this level (remember the fallacies of distributed computing ?) can be automatically handled by FusionCache to not impact the overall application, all while (optionally) logging any detail of it for further investigation
Everything is handled transparently for us.
Read more here, or enjoy the complete step by step guide.
📢 Backplane (more)
If we are in a scenario with multiple nodes, each with their own local memory cache, we typically also use a distributed cache as a secondary level (see above).
Even using that, we may find that each memory cache may not be necessarily in-sync with the others, because when a value is cached locally it will stay the same until the Duration passes and expiration occurs.
To avoid this and have everything always synchronized we can use a backplane, a shared message bus where change notifications will be automatically sent to all other connected nodes each time a value changes in the cache, without us having to do anything.
Read more here, or enjoy the complete step by step guide.
💣 Fail-Safe (more)
Sometimes things can go wrong, and calling a factory for an expired cache entry can lead to exceptions because the database or the network is temporarily down: normally in this case the exception will cause an error page in our website, a failure status code in our api or something like that.
By enabling the fail-safe mechanism we can simply tell FusionCache to ignore those errors and temporarily use the expired cache entry: our website or service will remain online, and our users would not notice anything.
Read more here, or enjoy the complete step by step guide.
⏱️ Timeouts (more)
Sometimes our data source (database, webservice, etc) is overloaded, the network is congested or something else is happening, and the end result is a long wait for a fresh piece of data.
Wouldn't it be nice if there could be a way to simply let FusionCache temporarily reuse an expired cache entry if the factory is taking too long?
Enter soft/hard timeouts.
Read more here, or enjoy the complete step by step guide.
↩️ Auto-Recovery(more)
As we know from the Fallacies Of Distributed Computing, something may go wrong while we are using distributed components like the distributed cache or the backplane, even if only in a transient way.
Without some extra care what can happen is that data would not be saved in the distributed cache or other nodes may not be notified of changes: this would result in out-of-sync issues.
wouldn't it be nice if FusionCache would help us is some way when transient error happens?
Enter Auto-Recovery.: everything is done automatically, and it just works.
Read more here.
🎚️ Options (more)
There are 2 kinds of options:
FusionCacheOptions: cache-wide options, related to the entire FusionCache instanceFusionCacheEntryOptions: per-entry options, related to each method call/entry
It's also possible to define DefaultEntryOptions: they can act as default options (like a "starting point") for every entry/method call, which can then be furtherly customized in-place.
Read more here, or enjoy the complete step by step guide.
🕹️ Core Methods (more)
At a high level there are 6 core methods:
Set[Async]GetOrSet[Async]GetOrDefault[Async]TryGet[Async]Expire[Async]Remove[Async]
All of them work on both the memory cache and the distributed cache (if any) in a transparent way: we don't have to do anything extra for it to coordinate the 2 levels.
All of them are available in both a sync and an async version.
Finally, most of them have a set of overloads for a better ease of use.
Read more here.
Everything is natively available for both the sync and async programming models.
Any operation works seamlessly with any other, even if one is sync and the other is async: an example is multiple concurrent factory calls for the same cache key, some of them sync while others async, all coordinated together at the same time with no problems and a guarantee that only one will be executed at the same time.
🔃 Dependency Injection + Builder (more)
FusionCache fully supports Dependency Injection (DI), a design pattern to achieve a form of Inversion of Control (IoC) in our code.
It also supports the modern and easy to use Builder approach.
Read more here, or enjoy the complete step by step guide.
📛 Named Caches (more)
Just like with the standard named http clients in .NET, with FusionCache it's possible to have multiple named caches.
Thanks to the native builder support, it's very easy to configure different caches identified by different names.
Read more here.
📞 Events (more)
There's a comprehensive set of events to subscribe to regarding core events inside of a FusionCache instance, both at a high level and at lower levels (memory/distributed levels).
Read more here.
🧩 Plugins (more)
FusionCache supports extensibility via plugins: it is possible for example to listen to events and react in any way we want.
In time, the most useful plugins will be listed directly in the homepage.
Read more here.
🔭 OpenTelemetry (more)
Full observability support, thanks to OpenTelemetry integration, means that we can have a clear and detailed view of what happens in our production systems.
Detailed traces are available, with timings, durations, details, events and tags.
We can also observe one of the various metrics available like cache hit/miss, method calls and so on.
📜 Logging (more)
FusionCache can log extensively to help us pinpoint any possible problem in our production environment.
It uses the standard ILogger<T> interface and a structured logging approach so it fits well in the .NET ecosystem, allowing us to use any implementation we want that is compatible with it (Serilog, NLog, etc): it also has a series of settings we may find useful to better tune its behavior.
Read more here.