ZiggyCreatures.FusionCache 1.0.0

FusionCache

FusionCache is an easy to use, fast and robust cache with advanced resiliency features and an optional distributed 2nd level.

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 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, customizable extensive logging and more (see below).

🏆 Award

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

📕 Getting Started

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.

In search of all the docs? There's a page for that, too.

More into videos? The fine folks at On .NET have been kind enough to invite me on the show and listen to me mumbling random caching stuff.

✔ Features

These are the key features of FusionCache:

• 🛡️ Cache Stampede: automatic protection from the Cache Stampede problem
• 🔀 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
• 📢 Backplane: in a multi-node scenario, it can notify the other nodes about changes in the cache, so all will be in-sync
• ↩️ Auto-Recovery: automatic handling of transient issues with retries and sync logic
• 🧙‍♂️ 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
• 🔃 Dependency Injection + Builder: 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
• 🔭 OpenTelemetry: native observability support via OpenTelemetry
• 📜 Logging: comprehensive, structured and customizable, via the standard ILogger interface
• 💫 Fully 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...

⭐ Quick Start

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 and a Low priority:

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

Or, using DI, like this:

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

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 simply do this:

var id = 42;

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

That's it 🎉

🖥️ Simulator

Distributed systems are, in general, quite complex to understand.

When using FusionCache with the distributed cache, the backplane and auto-recovery the Simulator can help us seeing the whole picture.

🧰 Supported Platforms

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.

💼 Is it Production Ready ™️ ?

Yes!

FusionCache is being used in production on real world projects for years, happily handling millions of requests per day.

Considering that the FusionCache packages have been downloaded more than 3 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!