It was born after years of dealing with all sorts of different types of caches: memory caching, distributed caching, http caching, CDNs, browser cache, offline cache, you name it. So I've tried to put together these experiences and came up with FusionCache.

It uses a memory cache (any impl of the standard IMemoryCache interface) as the primary backing store and optionally a distributed, 2nd level cache (any impl of the standard IDistributedCache interface) as a secondary backing store for better resilience and higher performance, for example in a multi-node scenario or to avoid the typical effects of a cold start (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 all the memory caches involved perfectly synchronized, without any additional work.

FusionCache also includes some advanced resiliency features like cache stampede prevention, a fail-safe mechanism, fine grained soft/hard timeouts with background factory completion, customizable extensive logging and more (see below).

On August 2021, FusionCache received the Google Open Source Peer Bonus Award: here is the official blogpost.

With 🦄 A Gentle Introduction you'll get yourself comfortable with the overall concepts.

Want to start using it immediately? There's a ⭐ Quick Start for you.

Curious about what you can achieve from start to finish? There's a 👩‍🏫 Step By Step guide.

More into videos? The great Anna Hoffman has been so nice to listen to me mumble random stuff on Data Exposed.

These are the key features of FusionCache:

• 🚀 Cache Stampede prevention: automatic protection from the Cache Stampede problem
• 🔀 Optional 2nd level: an optional 2nd level handled transparently, with any implementation of IDistributedCache
• 💣 Fail-Safe: a mechanism to avoids transient failures, by reusing an expired entry as a temporary fallback
• ⏱ Soft/Hard timeouts: a slow factory (or distributed cache) will not slow down your application, and no data will be wasted
• 🧙‍♂️ Adaptive Caching: for when you don't know upfront the cache duration, as it depends on the value being cached itself
• 🔂 Conditional Refresh: like HTTP Conditional Requests, but for caching
• 🦅 Eager Refresh: start a non-blocking background refresh before the expiration occurs
• 📢 Backplane: in a multi-node scenario, it can notify the other nodes about changes in the cache, so all will be in-sync
• 🔃 Dependency Injection: native support for Dependency Injection, with a nice fluent interface including a Builder support
• 📛 Named Caches: easily work with multiple named caches, even if differently configured
• 💫 Natively sync/async: native support for both the synchronous and asynchronous programming model
• 📞 Events: a comprehensive set of events, both at a high level and at lower levels (memory/distributed)
• 🧩 Plugins: extend FusionCache with additional behavior like adding support for metrics, statistics, etc...
• 📜 Logging: comprehensive, structured and customizable, via the standard ILogger interface

Main packages:

Package Name	Version	Downloads
ZiggyCreatures.FusionCache The core package
ZiggyCreatures.FusionCache.Chaos A package with additional chaos-related utilities and implementations

Serializers:

Package Name	Version	Downloads
ZiggyCreatures.FusionCache.Serialization.NewtonsoftJson A serializer, based on Newtonsoft Json.NET
ZiggyCreatures.FusionCache.Serialization.SystemTextJson A serializer, based on the new System.Text.Json
ZiggyCreatures.FusionCache.Serialization.NeueccMessagePack A MessagePack serializer, based on the most used MessagePack serializer on .NET
ZiggyCreatures.FusionCache.Serialization.ProtoBufNet A Protobuf serializer, based on one of the most used protobuf-net serializer on .NET
ZiggyCreatures.FusionCache.Serialization.CysharpMemoryPack A serializer based on the uber fast new serializer by Neuecc, MemoryPack
ZiggyCreatures.FusionCache.Serialization.ServiceStackJson A serializer based on the ServiceStack JSON serializer

Backplanes:

Package Name	Version	Downloads
ZiggyCreatures.FusionCache.Backplane.Memory An in-memory backplane (mainly for testing)
ZiggyCreatures.FusionCache.Backplane.StackExchangeRedis A Redis backplane, based on StackExchange.Redis

Third-party packages:

Package Name	Version	Downloads
JoeShook.ZiggyCreatures.FusionCache.Metrics.Core
JoeShook.ZiggyCreatures.FusionCache.Metrics.EventCounters
JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics

FusionCache can be installed via the nuget UI (search for the ZiggyCreatures.FusionCache package) or via the nuget package manager console:

PM> Install-Package ZiggyCreatures.FusionCache

As an example, imagine having a method that retrieves a product from your database:

Product GetProductFromDb(int id) {
	// YOUR DATABASE CALL HERE
}

💡 This is using the sync programming model, but it would be equally valid with the newer async one for even better performance.

To start using FusionCache the first thing is create a cache instance:

var cache = new FusionCache(new FusionCacheOptions());

If instead you are using DI (Dependency Injection) use this:

services.AddFusionCache();

We can also specify some global options, like a default FusionCacheEntryOptions object to serve as a default for each call we'll make, with a duration of 2 minutes:

var cache = new FusionCache(new FusionCacheOptions() {
	DefaultEntryOptions = new FusionCacheEntryOptions {
		Duration = TimeSpan.FromMinutes(2)
	}
});

Or, using DI, like this:

services.AddFusionCache()
	.WithDefaultEntryOptions(new FusionCacheEntryOptions {
		Duration = TimeSpan.FromMinutes(2)
	})
;

Now, to get the product from the cache and, if not there, get it from the database in an optimized way and cache it for 30 sec (overriding the default 2 min we set above) simply do this:

var id = 42;

cache.GetOrSet<Product>(
	$"product:{id}",
	_ => GetProductFromDb(id),
	TimeSpan.FromSeconds(30)
);

That's it 🎉

cache.GetOrSet<Product>(
	$"product:{id}",
	_ => GetProductFromDb(id),
	// THIS IS WHERE THE MAGIC HAPPENS
	options => options
		.SetDuration(TimeSpan.FromSeconds(30))
		.SetPriority(CacheItemPriority.High)
		.SetFailSafe(true, TimeSpan.FromHours(2))
		.SetFactoryTimeouts(TimeSpan.FromMilliseconds(100), TimeSpan.FromSeconds(2))
);

var cache = new FusionCache(new FusionCacheOptions() {
	DefaultEntryOptions = new FusionCacheEntryOptions()
		.SetDuration(TimeSpan.FromMinutes(2))
		.SetPriority(CacheItemPriority.High)
		.SetFailSafe(true, TimeSpan.FromHours(2))
		.SetFactoryTimeouts(TimeSpan.FromMilliseconds(100), TimeSpan.FromSeconds(2))
});

var id = 42;

cache.GetOrSet<Product>(
	$"product:{id}",
	_ => GetProductFromDb(id),
	options => options.SetDuration(TimeSpan.FromSeconds(30))
);

The documentation is available in the 📂 docs folder, with:

• 🦄 A Gentle Introduction: what you need to know first
• 🔀 Cache Levels: a bried description of the 2 available caching levels and how to setup them
• 📢 Backplane: how to get an always synchronized cache, even in a multi-node scenario
• 🚀 Cache Stampede prevention: no more overloads during a cold start or after an expiration
• 💣 Fail-Safe: an explanation of how the fail-safe mechanism works
• ⏱ Timeouts: the various types of timeouts at your disposal (calling a factory, using the distributed cache, etc)
• 📛 Named Caches: how to work with multiple named FusionCache instances
• 🧙‍♂️ Adaptive Caching: how to adapt cache duration (and more) based on the object being cached itself
• 🔂 Conditional Refresh: how to save resources when the remote data is not changed
• 🦅 Eager Refresh: how to start a background refresh eagerly, before the expiration occurs
• 🔃 Dependency Injection: how to work with FusionCache + DI in .NET
• 🎚 Options: everything about the available options, both cache-wide and per-call
• 🕹 Core Methods: what you need to know about the core methods available
• 📞 Events: the events hub and how to use it
• 🧩 Plugins: how to create and use plugins
• 📜 Logging: logging configuration and usage

If you are in for a ride you can read a complete step by step example of why a cache is useful, why FusionCache could be even more so, how to apply most of the options available and what results you can expect to obtain.

There are various alternatives out there with different features, different performance characteristics (cpu/memory) and in general a different set of pros/cons.

A feature comparison between existing .NET caching solutions may help you choose which one to use.

FusionCache targets .NET Standard 2.0 so any compatible .NET implementation is fine: this means .NET Framework (the old one), .NET Core 2+ and .NET 5/6+ (the new ones), Mono 5.4+ and more (see here for a complete rundown).

NOTE: if you are running on .NET Framework 4.6.1 and want to use .NET Standard packages Microsoft suggests to upgrade to .NET Framework 4.7.2 or higher (see the .NET Standard Documentation) to avoid some known dependency issues.

The logo is an original creation and is a sloth because, you know, speed.

Nothing to do here.

After years of using a lot of open source stuff for free, this is just me trying to give something back to the community.

If you find FusionCache useful please just ✉ drop me a line, I would be interested in knowing about your usage.

And if you really want to talk about money, please consider making ❤ a donation to a good cause of your choosing, and maybe let me know about that.

Yes!

Even though the current version is 0.X for an excess of caution, FusionCache is already used in production on multiple real world projects happily handling millions of requests per day, or at least these are the projects I'm aware of.

Considering that the FusionCache packages have been downloaded more than a million times (thanks everybody!) it may very well be used even more.

And again, if you are using it please ✉ drop me a line, I'd like to know!