FusionCache

https://github.com/ziggycreatures/fusioncache
Admin
FusionCache is an easy to use, fast and robust hybrid cache with advanced resiliency features.
Tokens:198,212
Snippets:1,185
Trust Score:5.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup Redis and use background distributed cache operations

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Timeouts.md

This example shows how to instantiate Redis as a distributed cache, set up FusionCache with a serializer, and set a value with `AllowBackgroundDistributedCacheOperations` enabled. It warns that immediately reading from Redis may return null because the background operation may not have completed.

```csharp
// INSTANTIATE REDIS AS A DISTRIBUTED CACHE
var redis = new RedisCache(new RedisCacheOptions() {
    Configuration = "CONNECTION STRING"
});

// INSTANTIATE THE FUSION CACHE SERIALIZER
var serializer = new FusionCacheNewtonsoftJsonSerializer();

// INSTANTIATE FUSION CACHE
var cache = new FusionCache(new FusionCacheOptions());

// SETUP THE DISTRIBUTED 2ND LEVEL
cache.SetupDistributedCache(redis, serializer);

// SET A VALUE IN THE CACHE VIA FUSION CACHE, WITH BACKGROUND DISTRIBUTED OPERATIONS
cache.Set<string>(
    "foo",
    "Sloths, sloths everywhere",
    new FusionCacheEntryOptions { AllowBackgroundDistributedCacheOperations = true }
);

// HERE foo MAY BE NULL, BECAUSE THE DISTRIBUTED CACHE MAY STILL BE SAVING THE VALUE IN THE BACKGROUND
var foo = redis.GetString("foo");
```

--------------------------------

### Redis Backplane Setup

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Installation and registration of the Redis backplane for FusionCache.

```PowerShell
PM> Install-Package ZiggyCreatures.FusionCache.Backplane.StackExchangeRedis
```

```csharp
services.AddFusionCache()
    .WithOptions(options => {
        options.DistributedCacheCircuitBreakerDuration = TimeSpan.FromSeconds(2);
    })
    .WithDefaultEntryOptions(new FusionCacheEntryOptions {
        Duration = TimeSpan.FromMinutes(1),
        
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30),

        EagerRefreshThreshold = 0.9f,

        FactorySoftTimeout = TimeSpan.FromMilliseconds(100),
    })
    .WithSerializer(
        new FusionCacheSystemTextJsonSerializer()
    )
    .WithDistributedCache(
        new RedisCache(new RedisCacheOptions() { Configuration = "CONNECTION STRING" })
    )
    // ADD BACKPLANE BASED ON REDIS
    .WithBackplane(
        new RedisBackplane(new RedisBackplaneOptions() { Configuration = "CONNECTION STRING" })
    )
;
```

--------------------------------

### Manual setup of FusionCache with Redis distributed cache and backplane

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Backplane.md

Install the required NuGet packages for FusionCache with Redis as distributed cache and backplane, then manually instantiate and wire up the cache, distributed cache, serializer, and backplane. The manual setup uses the FusionCacheOptions, RedisCache, FusionCacheNewtonsoftJsonSerializer, and RedisBackplane classes. Replace the placeholder "CONNECTION STRING" with the actual Redis connection string.

```PowerShell
# CORE PACKAGE
PM> Install-Package ZiggyCreatures.FusionCache

# SERIALIZER
PM> Install-Package ZiggyCreatures.FusionCache.Serialization.NewtonsoftJson

# DISTRIBUTED CACHE
PM> Install-Package Microsoft.Extensions.Caching.StackExchangeRedis

# BACKPLANE
PM> Install-Package ZiggyCreatures.FusionCache.Backplane.StackExchangeRedis
```

```csharp
// INSTANTIATE FUSION CACHE
var cache = new FusionCache(new FusionCacheOptions());

// INSTANTIATE A REDIS DISTRIBUTED CACHE (IDistributedCache)
var redis = new RedisCache(new RedisCacheOptions() {
    Configuration = "CONNECTION STRING"
});

// INSTANTIATE THE FUSION CACHE SERIALIZER
var serializer = new FusionCacheNewtonsoftJsonSerializer();

// SETUP THE DISTRIBUTED 2ND LEVEL
cache.SetupDistributedCache(redis, serializer);

// CREATE THE BACKPLANE
var backplane = new RedisBackplane(new RedisBackplaneOptions() {
    Configuration = "CONNECTION STRING"
});

// SETUP THE BACKPLANE
cache.SetupBackplane(backplane);
```

--------------------------------

### Plugin Usage Examples

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Plugins.md

Code examples demonstrating how to use plugins via DI and without DI.

```csharp
services.AddTransient<IFusionCachePlugin, MyPlugin>();

services.AddFusionCache()
  .WithAllRegisteredPlugins()
;
```

```csharp
services.AddFusionCache()
  .WithPlugin(new MyPlugin(...))
;
```

```csharp
services.AddMyFusionCachePlugin(options => {
  options.Whatever = 42;
});

services.AddFusionCache()
  .WithAllRegisteredPlugins()
;
```

```csharp
services.AddTransient<IFusionCachePlugin, MyFirstPlugin>();
services.AddTransient<IFusionCachePlugin, MySecondPlugin>();

services.AddFusionCache()
  .WithAllRegisteredPlugins()
;
```

```csharp
var firstPlugin = new MyFirstPlugin();
var secondPlugin = new MySecondPlugin();

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

cache.AddPlugin(firstPlugin);
cache.AddPlugin(secondPlugin);
```

--------------------------------

### Install FusionCache.OpenTelemetry package

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/OpenTelemetry.md

Install the ZiggyCreatures.FusionCache.OpenTelemetry NuGet package to add OpenTelemetry support.

```PowerShell
PM> Install-Package ZiggyCreatures.FusionCache.OpenTelemetry
```

--------------------------------

### Install Redis and System.Text.Json serializer packages

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Install the Microsoft.Extensions.Caching.StackExchangeRedis and ZiggyCreatures.FusionCache.Serialization.SystemTextJson packages via NuGet Package Manager.

```PowerShell
PM> Install-Package Microsoft.Extensions.Caching.StackExchangeRedis
PM> Install-Package ZiggyCreatures.FusionCache.Serialization.SystemTextJson
```

--------------------------------

### FusionCache Example

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/AutoClone.md

Demonstrates FusionCache usage with auto-cloning and direct references, showing how changes affect clones vs cached instances.

```csharp
// SETUP

var cache = new FusionCache(new FusionCacheOptions());
cache.SetupSerializer(new FusionCacheSystemTextJsonSerializer());

// USAGE

cache.Set("foo", new Person { Name = "John" });

// RETURNS A CLONE OF THE CACHED INSTANCE
var person1 = cache.GetOrDefault<Person>("foo", options => options.SetAutoClone(true));
Console.WriteLine($"person1: {person1.Name}");
Console.WriteLine();

// RETURNS A CLONE OF THE CACHED INSTANCE: CHANGES APPLIED ONLY THE CLONE, CACHED INSTANCE REMAINS UNCHANGED
var person2 = cache.GetOrDefault<Person>("foo", options => options.SetAutoClone(true));
person2.Name = "Jane";
Console.WriteLine($"person1: {person1.Name}");
Console.WriteLine($"person2: {person2.Name}");
Console.WriteLine();

// RETURNS DIRECT REFERENCE TO THE CACHED INSTANCE: CHANGES APPLIED TO THE CACHED INSTANCE ITSELF
var person3 = cache.GetOrDefault<Person>("foo");
person3.Name = "Jim";
Console.WriteLine($"person1: {person1.Name}");
Console.WriteLine($"person2: {person2.Name}");
Console.WriteLine($"person3: {person3.Name}");
Console.WriteLine();

// RETURNS DIRECT REFERENCE TO THE CACHED INSTANCE: THE INSTANCE IS THE SAME AS BEFORE
// CHANGES APPLIED TO BOTH person3 AND person4 AS THEY POINT TO THE SAME CACHED INSTANCE
var person4 = cache.GetOrDefault<Person>("foo");
person4.Name = "Joe";

Console.WriteLine($"person1: {person1.Name}");
Console.WriteLine($"person2: {person2.Name}");
Console.WriteLine($"person3: {person3.Name}");
Console.WriteLine($"person4: {person4.Name}");
```

```text
person1: John

person1: John
person2: Jane

person1: John
person2: Jane
person3: Jim

person1: John
person2: Jane
person3: Joe
person4: Joe
```

--------------------------------

### Get default cache via IFusionCacheProvider.GetDefaultCache

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/NamedCaches.md

Alternative constructor injection example that obtains the default cache explicitly using IFusionCacheProvider.GetDefaultCache() and a named cache with GetCache("Products").

```csharp
public class MyController : Controller
{
    private readonly IFusionCache _defaultCache;
    private readonly IFusionCache _productsCache;

    public MyController(IFusionCacheProvider cacheProvider)
    {
        _defaultCache = cacheProvider.GetDefaultCache();
        _productsCache = cacheProvider.GetCache("Products");
    }
}
```

--------------------------------

### Configure OpenTelemetry with FusionCache Instrumentation

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Configure OpenTelemetry for FusionCache during setup, enabling traces and metrics with the AddFusionCacheInstrumentation() method. The example uses ConsoleExporter, but any other exporter can be substituted. This setup provides observability for production systems with tools like Jaeger or Prometheus.

```csharp
services.AddOpenTelemetry()
  // SETUP TRACES
  .WithTracing(tracing => tracing
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter() // OR ANY ANOTHER EXPORTER
  )
  // SETUP METRICS
  .WithMetrics(metrics => metrics
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter() // OR ANY ANOTHER EXPORTER
  );
```

--------------------------------

### Install ZiggyCreatures.FusionCache NuGet package

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

Install the ZiggyCreatures.FusionCache NuGet package using the Package Manager Console.

```PowerShell
PM> Install-Package ZiggyCreatures.FusionCache
```

--------------------------------

### Inject default cache via IFusionCache and named cache via IFusionCacheProvider

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/NamedCaches.md

Constructor injection example showing how to get the default cache as an IFusionCache parameter and a named cache using IFusionCacheProvider.GetCache("Products").

```csharp
public class MyController : Controller
{
    private readonly IFusionCache _defaultCache;
    private readonly IFusionCache _productsCache;

    public MyController(IFusionCache defaultCache, IFusionCacheProvider cacheProvider)
    {
        _defaultCache = defaultCache;
        _productsCache = cacheProvider.GetCache("Products");
    }
}
```

--------------------------------

### FusionCache Timeout Examples

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Timeouts.md

Two C# examples demonstrating FusionCache usage: one without timeouts and one with fail-safe and a soft timeout.

```csharp
product = cache.GetOrSet<Product>(
    "product:123",
    _ => GetProductFromDb(123),
    options => options
        .SetDuration(TimeSpan.FromMinutes(2))
);
```

```csharp
product = cache.GetOrSet<Product>(
    "product:123",
    _ => GetProductFromDb(123),
    options => options
        .SetDuration(TimeSpan.FromMinutes(2))
        // ENABLE FAIL-SAFE
        .SetFailSafe(true)
        // SET A 100 MS SOFT TIMEOUT
        .SetFactoryTimeouts(TimeSpan.FromMilliseconds(100))
);
```

--------------------------------

### Install FusionCache, NewtonsoftJson serializer, and Redis packages

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheLevels.md

Install the required NuGet packages for using FusionCache with Redis and the NewtonsoftJson serializer.

```PowerShell
PM> Install-Package ZiggyCreatures.FusionCache
PM> Install-Package ZiggyCreatures.FusionCache.Serialization.NewtonsoftJson
PM> Install-Package Microsoft.Extensions.Caching.StackExchangeRedis
```

--------------------------------

### Configure RedisDistributedLocker with minimal setup

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheStampede.md

Shows the minimal setup for adding a distributed locker using RedisDistributedLocker with a connection string. This is the core configuration needed to enable distributed locking.

```csharp
services.AddFusionCache()
    // ...
	.WithDistributedLocker(
		new RedisDistributedLocker(new RedisDistributedLockerOptions
		{
			Configuration = "localhost:6379",
		})
	);
```

--------------------------------

### Using SqliteCache with FusionCache

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/DiskCache.md

Two C# examples showing how to configure FusionCache with SqliteCache as the distributed cache, either directly or via registration.

```csharp
services.AddFusionCache()
    .WithSerializer(
        new FusionCacheNewtonsoftJsonSerializer()
    )
    .WithDistributedCache(
        new SqliteCache(new SqliteCacheOptions { CachePath = "CACHE PATH" })
    )
;
```

```csharp
// REGISTER SQLITE AS THE IDistributedCache IMPL
services.AddSqliteCache(options => {
    options.CachePath = "CACHE PATH";
});

services.AddFusionCache()
    .WithSerializer(
        new FusionCacheNewtonsoftJsonSerializer()
    )
    // USE THE REGISTERED IDistributedCache IMPL
    .WithRegisteredDistributedCache()
;
```

--------------------------------

### FailSafeEMailPlugin example: options, plugin, and DI extension

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/PluginSample.md

These three C# files form the complete FailSafeEMailPlugin example: options class, plugin implementation, and DI extension. The plugin subscribes to the FailSafeActivate event and sends an email via SMTP when fail-safe activates. The extension method registers the plugin as a singleton and optionally configures options.

```csharp
using System;
using Microsoft.Extensions.Options;

namespace ZiggyCreatures.Caching.Fusion.Plugins.MyAwesomePlugins
{
  public class FailSafeEMailPluginOptions
    : IOptions<FailSafeEMailPluginOptions>
  {
    public string? FromAddress { get; set; }
    public string? ToAddress { get; set; }
    public string? SmtpHost { get; set; }
    public int SmtpPort { get; set; } = 25;
    public string? SmtpUsername { get; set; }
    public string? SmtpPassword { get; set; }

    FailSafeEMailPluginOptions IOptions<FailSafeEMailPluginOptions>.Value
    {
      get { return this; }
    }
  }
}
```

```csharp
using System;
using MailKit.Net.Smtp;
using MailKit.Security;
using Microsoft.Extensions.Options;
using MimeKit;
using MimeKit.Text;
using ZiggyCreatures.Caching.Fusion.Events;

namespace ZiggyCreatures.Caching.Fusion.Plugins.MyAwesomePlugins
{
  public class FailSafeEMailPlugin
    : IFusionCachePlugin
  {

    private FailSafeEMailPluginOptions _options;

    public FailSafeEMailPlugin(IOptions<FailSafeEMailPluginOptions> optionsAccessor)
    {
      // GET THE OPTIONS
      _options = optionsAccessor.Value;
    }

    public void Start(IFusionCache cache)
    {
      // ADD THE HANDLER
      cache.Events.FailSafeActivate += OnFailSafeActivate;
    }

    public void Stop(IFusionCache cache)
    {
      // REMOVE THE HANDLER
      cache.Events.FailSafeActivate -= OnFailSafeActivate;
    }

    private void OnFailSafeActivate(object sender, FusionCacheEntryEventArgs e)
    {
      // PREPARE THE MAIL MESSAGE
      var email = new MimeMessage();
      email.From.Add(MailboxAddress.Parse(_options.FromAddress));
      email.To.Add(MailboxAddress.Parse(_options.ToAddress));
      email.Subject = "Fail-safe has been activated";
      email.Body = new TextPart(TextFormat.Plain)
      {
        Text = $"A fail-safe activation has occurred at {DateTimeOffset.UtcNow:O} UTC for the cache key {e.Key}"
      };

      // SEND IT
      using (var smtp = new SmtpClient())
      {
        smtp.Connect(_options.SmtpHost, _options.SmtpPort, SecureSocketOptions.StartTls);
        smtp.Authenticate(_options.SmtpUsername, _options.SmtpPassword);
        smtp.Send(email);
        smtp.Disconnect(true);
      }
    }
  }
}
```

```csharp
using System;
using ZiggyCreatures.Caching.Fusion;
using ZiggyCreatures.Caching.Fusion.Plugins;
using ZiggyCreatures.Caching.Fusion.Plugins.MyAwesomePlugins;

namespace Microsoft.Extensions.DependencyInjection
{
  public static class FailSafeEMailPluginServiceCollectionExtensions
  {
    public static IServiceCollection AddFusionCacheFailSafeEMailPlugin(this IServiceCollection services, Action<FusionCacheOptions>? setupOptionsAction = null)
    {
      if (services is null)
        throw new ArgumentNullException(nameof(services));

      // ENSURE THE OPTIONS SYSTEM IS AVAILABLE
      services.AddOptions();

      // OPTIONAL CUSTOM CONFIGURATION OF OPTIONS
      if (setupOptionsAction is object)
        services.Configure(setupOptionsAction);

      //REGISTER THE SERVICE
      services.AddSingleton<IFusionCachePlugin, FailSafeEMailPlugin>();

      return services;
    }
  }
}
```

--------------------------------

### Serilog logging configuration in appsettings.json

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Same example as above but for Serilog, which uses a different configuration structure. It sets the 'MinimumLevel' with a 'Default' of 'Warning' and overrides for 'MyCompany' (Information) and 'ZiggyCreatures.Caching.Fusion' (Debug).

```json
{
    "Serilog": {
        "MinimumLevel": {
            "Default": "Warning",
            "Override": {
                "MyCompany": "Information",
                "ZiggyCreatures.Caching.Fusion": "Debug"
            }
        }
    }
}
```

--------------------------------

### GetProductFromDb method (sync)

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

A sample method that loads a product from the database. Used as the factory in the GetOrSet examples. The sync programming model is shown, but the async version would be equally valid.

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

--------------------------------

### Manually setup FusionCache with Redis and NewtonsoftJson serializer

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheLevels.md

Creates a Redis distributed cache, a FusionCacheNewtonsoftJsonSerializer, and a FusionCache instance, then sets up the distributed cache with the serializer.

```csharp
// INSTANTIATE A REDIS DISTRIBUTED CACHE
var redis = new RedisCache(new RedisCacheOptions() { Configuration = "CONNECTION STRING" });

// INSTANTIATE THE FUSION CACHE SERIALIZER
var serializer = new FusionCacheNewtonsoftJsonSerializer();

// INSTANTIATE FUSION CACHE
var cache = new FusionCache(new FusionCacheOptions());

// SETUP THE DISTRIBUTED 2ND LEVEL
cache.SetupDistributedCache(redis, serializer);
```

--------------------------------

### Complete FusionCache setup with distributed locker

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheStampede.md

Shows a complete FusionCache setup including serializer, distributed cache, backplane, and distributed locker, all using Redis. This is the full configuration when you need all components.

```csharp
services.AddFusionCache()
	// SERIALIZER
	.WithSerializer(
		new FusionCacheSystemTextJsonSerializer()
	)
	// DISTRIBUTED CACHE
	.WithDistributedCache(
		new RedisCache(new RedisCacheOptions
		{
			Configuration = "localhost:6379",
		})
	)
	// BACKPLANE
	.WithBackplane(
		new RedisBackplane(new RedisBackplaneOptions
		{
			Configuration = "localhost:6379",
		})
	)
	// DISTRIBUTED LOCKER <-- HERE IT IS!
	.WithDistributedLocker(
		new RedisDistributedLocker(new RedisDistributedLockerOptions
		{
			Configuration = "localhost:6379",
		})
	);
```

--------------------------------

### GetOrSet[Async] - Get or set with factory, duration, and fail-safe

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CoreMethods.md

Shows the main GetOrSet overloads: default value, factory, explicit duration, options with duration, fail-safe with stale data, fail-safe with default value, and using DefaultEntryOptions. Note that the factory examples are incomplete in the source (missing commas and closing parentheses) and are reproduced verbatim.

```csharp
// THIS WILL GET FOO FROM THE CACHE OR, IF NOT THERE, SET THE VALUE 123 AND RETURN IT
var foo = cache.GetOrSet<int>("foo", 123);

// THIS WILL GET FOO FROM THE CACHE OR CALL THE FACTORY, THEN SET THE VALUE OBTAINED AND RETURN IT
var foo = cache.GetOrSet<int>(
    "foo",
    _ => GetFooFromDb()
);

// AS ABOVE, BUT WITH AN EXPLICIT DURATION OF 1 MIN
var foo = cache.GetOrSet<int>(
    "foo",
    _ => GetFooFromDb()
    TimeSpan.FromMinutes(1)
);

// OR
var foo = cache.GetOrSet<int>(
    "foo",
    _ => GetFooFromDb()
    options => options.SetDuration(TimeSpan.FromMinutes(1))
);

// AS ABOVE, BUT IF BAD STUFF HAPPENS, WILL USE EXPIRED (STALE) DATA INSTEAD OF THROWING AN EXCEPTION
// ALSO:
// 1) STALE DATA WILL BE USED FOR 30 SEC AT A TIME, FOR A MAXIMUM OF 1 HOUR
// 2) IF THERE IS NO STALE DATA TO USE, AN EXCEPTION WILL BE THROWN NONETHELESS
var foo = cache.GetOrSet<int>(
    "foo",
    _ => GetFooFromDb()
    options => options
        .SetDuration(TimeSpan.FromMinutes(1))
        .SetFailSafe(true, TimeSpan.FromHours(1), TimeSpan.FromSeconds(30))
);

// AS ABOVE, BUT IF THERE IS NO STALE DATA, A DEFAULT VALUE WILL BE SET (FOR 30 SEC, ETC...) ADN RETURNED
var foo = cache.GetOrSet<int>(
    "foo",
    _ => GetFooFromDb()
    42
    options => options
        .SetDuration(TimeSpan.FromMinutes(1))
        .SetFailSafe(true, TimeSpan.FromHours(1), TimeSpan.FromSeconds(30))
);

// OR, IF YOUR DefaultEntryOptions ALREADY HAVE FAIL-SAFE ENABLED AND THE
// RIGHT OPTIONS, YOU CAN JUST DO THIS
var foo = cache.GetOrSet<int>("foo", _ => GetFooFromDb(), 42);
```

--------------------------------

### GetProductFromDb database fetch method

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Baseline method that fetches a product from the database. Replace the comment with the actual database call. The example uses the synchronous model; an async version with await would likely improve performance.

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

--------------------------------

### GetOrSet with duration

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

Get a product from the cache or, if not present, get it from the database and cache it for 30 seconds.

```csharp
var id = 42;

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

--------------------------------

### Install and register Redis distributed locker for FusionCache

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Install the Redis distributed locker package and register it during startup. The registration chain configures FusionCache with options, serialization, distributed cache, backplane, and the locker. Replace the CONNECTION STRING placeholders with your Redis connection string.

```PowerShell
PM> Install-Package ZiggyCreatures.FusionCache.Locking.Distributed.Redis
```

```csharp
services.AddFusionCache()
    .WithOptions(options => {
        options.DistributedCacheCircuitBreakerDuration = TimeSpan.FromSeconds(2);
    })
    .WithDefaultEntryOptions(new FusionCacheEntryOptions {
        Duration = TimeSpan.FromMinutes(1),
        
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(2),
        FailSafeThrottleDuration = TimeSpan.FromSeconds(30),

        EagerRefreshThreshold = 0.9f,

        FactorySoftTimeout = TimeSpan.FromMilliseconds(100),
        FactoryHardTimeout = TimeSpan.FromMilliseconds(1500),

        DistributedCacheSoftTimeout = TimeSpan.FromSeconds(1),
        DistributedCacheHardTimeout = TimeSpan.FromSeconds(2),
        AllowBackgroundDistributedCacheOperations = true,

        JitterMaxDuration = TimeSpan.FromSeconds(2)
    })
    .WithSerializer(
        new FusionCacheSystemTextJsonSerializer()
    )
    .WithDistributedCache(
        new RedisCache(new RedisCacheOptions() { Configuration = "CONNECTION STRING" })
    )
    .WithBackplane(
        new RedisBackplane(new RedisBackplaneOptions() { Configuration = "CONNECTION STRING" })
    )
    // ADD THE DISTRIBUTED LOCKER BASED ON REDIS
	.WithDistributedLocker(
		new RedisDistributedLocker(new RedisDistributedLockerOptions { Configuration = "CONNECTION STRING" })
	)
;
```

--------------------------------

### Plugin Startup and Event Handler Registration

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/PluginSample.md

Define the plugin class, implementing IFusionCachePlugin, and register an event handler for cache.Events.FailSafeActivate in the Start method, removing it in Stop.

```csharp
using System;
using ZiggyCreatures.Caching.Fusion.Events;

namespace ZiggyCreatures.Caching.Fusion.Plugins.MyAwesomePlugins
{
  public class FailSafeEMailPlugin
    : IFusionCachePlugin
  {

    public void Start(IFusionCache cache)
    {
      // ADD THE HANDLER
      cache.Events.FailSafeActivate += OnFailSafeActivate;
    }

    public void Stop(IFusionCache cache)
    {
      // REMOVE THE HANDLER
      cache.Events.FailSafeActivate -= OnFailSafeActivate;
    }

    private void OnFailSafeActivate(object sender, FusionCacheEntryEventArgs e)
    {
      // DO SOMETHING HERE...
    }
  }
}
```

--------------------------------

### FusionCache Options Configuration

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Options.md

Examples of configuring FusionCache options: setting default entry options, using them implicitly, and using a lambda to duplicate and modify defaults.

```csharp
var options = new FusionCacheOptions() {
    DefaultEntryOptions = new FusionCacheEntryOptions {
        Duration = TimeSpan.FromMinutes(1),
        IsFailSafeEnabled = true,
    }
};
```

```csharp
// THIS USES THE DEFAULT OPTIONS
cache.Set<int>("foo", 42);
```

```csharp
cache.Set<int>(
    "foo",
    42,
    // THIS DUPLICATES THE DEFAULT OPTIONS, SET A DIFFERENT DURATION AND ENABLES FAIL-SAFE
    options => options.SetDuration(TimeSpan.FromMinutes(2)).SetFailSafe(true)
);
```

--------------------------------

### Use IFusionCacheProvider to get named cache 'Products'

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/NamedCaches.md

Shows how to replace IFusionCache with IFusionCacheProvider and use GetCache("Products") to retrieve a named cache.

```csharp
public class MyController : Controller
{
    private readonly IFusionCache _cache;

    public MyController(IFusionCacheProvider cacheProvider)
    {
        _cache = cacheProvider.GetCache("Products");
    }

    // ...
}
```

--------------------------------

### Warning-level log output example

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Example of FusionCache log output when the minimum log level is set to Warning. It shows two warning messages: one about a synthetic timeout and one about fail-safe activation, with a stack trace for the timeout exception.

```text
[12:15:41 WRN] FUSION (O=33859d31231f48a197950c3edd0cccbd K=foo): a synthetic timeout occurred while calling the factory
ZiggyCreatures.Caching.Fusion.SyntheticTimeoutException: The operation has timed out.
   at ZiggyCreatures.Caching.Fusion.Internals.FusionCacheExecutionUtils.RunAsyncFuncWithTimeoutAsync[TResult](Func`2 asyncFunc, TimeSpan timeout, Boolean cancelIfTimeout, Action`1 timedOutTaskProcessor, CancellationToken token) in C:\Users\Jody\source\repos\ZiggyCreatures.FusionCache\src\ZiggyCreatures.FusionCache\Internals\FusionCacheExecutionUtils.cs:line 79
   at ZiggyCreatures.Caching.Fusion.FusionCache.GetOrSetEntryInternalAsync[TValue](String operationId, String key, Func`3 factory, MaybeValue`1 failSafeDefaultValue, FusionCacheEntryOptions options, CancellationToken token) in C:\Users\Jody\source\repos\ZiggyCreatures.FusionCache\src\ZiggyCreatures.FusionCache\FusionCache_Async.cs:line 191
[12:15:41 WRN] FUSION (O=33859d31231f48a197950c3edd0cccbd K=foo): FAIL-SAFE activated (from memory)
```

--------------------------------

### Standard .NET logging configuration in appsettings.json

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Example of a logging configuration in the standard appsettings.json file for native .NET loggers, with a couple of minimum level overrides. The 'Default' level is 'Warning', with overrides for 'MyCompany' (Information) and 'ZiggyCreatures.Caching.Fusion' (Debug).

```json
{
    "Logging": {
        "LogLevel": {
            "Default": "Warning",
            "MyCompany": "Information",
            "ZiggyCreatures.Caching.Fusion": "Debug"
        }
    }
}
```

--------------------------------

### Complete FusionCache Logging Configuration

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Complete example showing how to set a global minimum log level of Warning and then override the log levels for factory synthetic timeouts (Debug) and other factory errors (Error) via FusionCache options. This configuration reduces log noise from frequent synthetic timeouts while still capturing real errors.

```csharp
services.AddLogging(b => b
    // GLOBAL MIN LEVEL: Warning
    .SetMinimumLevel(LogLevel.Warning)
);

services.AddFusionCache()
    .WithOptions(options =>
    {
        // FACTORY SYNTHETIC TIMEOUTS: Debug (SO THEY WILL BE IGNORED)
        options.FactorySyntheticTimeoutsLogLevel = LogLevel.Debug;
        // ANY OTHER FACTORY ERRORS: Error (SO THEY WILL -NOT- BE IGNORED)
        options.FactoryErrorsLogLevel = LogLevel.Error;
    })
;
```

--------------------------------

### GetOrSet with adaptive caching (dynamic duration via context)

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/AdaptiveCaching.md

Example of calling GetOrSet with a factory that receives a FusionCacheFactoryExecutionContext and a cancellation token, allowing the cache duration to be set dynamically based on the product's last updated time. The default duration is 1 minute.

```csharp
var id = 42;

// WITH ADAPTIVE CACHING: THE DURATION DEPENDS ON THE OBJECT BEING CACHED
var product = cache.GetOrSet<Product>(
    $"product:{id}",
    (ctx, ct) => {
        var product = GetProductFromDb(id, ct);

        if (product is null) {
            // CACHE null FOR 5 minutes
            ctx.Options.Duration = TimeSpan.FromMinutes(5);
        } else if (product.LastUpdatedAt > DateTime.UtcNow.AddDays(-1)) {
            // CACHE PRODUCTS UPDATED IN THE LAST DAY FOR 1 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(1);
        } else if (product.LastUpdatedAt > DateTime.UtcNow.AddDays(-10)) {
            // CACHE PRODUCTS UPDATED IN THE LAST 10 DAYS FOR 10 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(10);
        } else {
            // CACHE ANY OLDER PRODUCT FOR 30 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(30);
        }

        return product;
    },
    options => options.SetDuration(TimeSpan.FromMinutes(1)) // DEFAULT: 1 MIN
);
```

--------------------------------

### Setup FusionCache with Redis and NewtonsoftJson serializer using DI

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheLevels.md

Configures FusionCache via dependency injection, adding the NewtonsoftJson serializer and Redis distributed cache.

```csharp
services.AddFusionCache()
    .WithSerializer(
        new FusionCacheNewtonsoftJsonSerializer()
    )
    .WithDistributedCache(
        new RedisCache(new RedisCacheOptions { Configuration = "CONNECTION STRING" })
    )
;
```

--------------------------------

### Set up traces and metrics without DI

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/OpenTelemetry.md

Configure OpenTelemetry traces and metrics using the Sdk builders and FusionCache instrumentation. Add an exporter like ConsoleExporter.

```csharp
// SETUP TRACES
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();

// SETUP METRICS
using var meterProvider = Sdk.CreateMeterProviderBuilder()
  .AddFusionCacheInstrumentation()
  .AddConsoleExporter()
  .Build();
```

--------------------------------

### Set up traces and metrics with dependency injection

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/OpenTelemetry.md

Configure OpenTelemetry using the standard 'services.AddOpenTelemetry()' DI approach, adding FusionCache instrumentation for both tracing and metrics.

```csharp
services.AddOpenTelemetry()
  // SETUP TRACES
  .WithTracing(tracing => tracing
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  )
  // SETUP METRICS
  .WithMetrics(metrics => metrics
    .AddFusionCacheInstrumentation()
    .AddConsoleExporter()
  );
```

--------------------------------

### Create FusionCache with default entry options

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

Create a FusionCache instance with default entry options: a duration of 2 minutes and Low priority.

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

--------------------------------

### WithBackplane direct instance

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/DependencyInjection.md

Use this when you want to specify a backplane directly as an instance. Replace the placeholder connection string with your actual Redis configuration.

```csharp
services.AddFusionCache()
    .WithBackplane(new RedisBackplane(new RedisBackplaneOptions
    {
        Configuration = "CONNECTION_STRING_HERE"
    }))
;
```

--------------------------------

### Uncached GetProduct controller action

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Controller action that retrieves a product without caching. Returns NotFound when the product is null. This is the starting point before adding caching.

```csharp
[HttpGet("product/{id}")]
public ActionResult<Product> GetProduct(int id)
{
    var product = GetProductFromDb(id);

    if (product is null)
        return NotFound();

    return product;
}
```

--------------------------------

### Inject IFusionCache into an MVC controller

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/DependencyInjection.md

Shows how to inject IFusionCache into a controller constructor and use it to get or set a cached product. The DI framework automatically populates the cache parameter.

```csharp
public class MyController : Controller
{
    private readonly IFusionCache _cache;

    // THE cache PARAM WILL BE AUTOMATICALLY POPULATED BY THE DI FRAMEWORK
    public MyController(IFusionCache cache)
    {
        _cache = cache;
    }

    [Route("product/{id:int}")]
    public IActionResult Product(int id)
    {
        var product = _cache.GetOrSet<Product>(
            $"product:{id}",
            _ => GetProductFromDb(id),
            TimeSpan.FromSeconds(30)
        );

        return View(product);
    }
}
```

--------------------------------

### Create FusionCache with advanced default entry options

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

Create a FusionCache instance with default entry options that set duration to 2 minutes, priority to High, enable fail-safe for 2 hours, and set factory timeouts: soft timeout of 100 ms and hard timeout of 2 seconds.

```csharp
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))
});
```

--------------------------------

### Options Configuration

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/DependencyInjection.md

Configures cache-wide options using the fluent builder.

```csharp
services.AddFusionCache()
    .WithOptions(opt =>
    {
        opt.AutoRecoveryMaxItems = 123;
    })
;
```

--------------------------------

### Remove a cache entry with cache.Remove

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CoreMethods.md

Removes a value from the cache for the specified key. If the key does not exist, the operation does nothing. The example sets a value, removes it, then attempts to remove it again to show the no-op behavior.

```csharp
cache.Set("foo", 42);

// THIS WILL REMOVE THE CACHE ENTRY FOR "foo"
cache.Remove("foo");

// THIS WILL DO NOTHING
cache.Remove("foo");
```

--------------------------------

### Use HybridCache via DI with GetOrCreateAsync

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/MicrosoftHybridCache.md

Shows a service that depends on HybridCache and uses GetOrCreateAsync to retrieve or create a cache entry. The example is taken from official Microsoft docs and demonstrates the main overload.

```csharp
public class SomeService(HybridCache cache)
{
    private HybridCache _cache = cache;

    public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
    {
        return await _cache.GetOrCreateAsync(
            $"{name}-{id}", // Unique key to the cache entry
            async cancel => await GetDataFromTheSourceAsync(name, id, cancel),
            cancellationToken: token
        );
    }

    public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
    {
        string someInfo = $"someinfo-{name}-{id}";
        return someInfo;
    }
}
```

--------------------------------

### Use registered components with WithRegisteredXyz() for multiple caches

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/NamedCaches.md

Registers a common serializer, Redis distributed cache, and backplane in DI, then configures the default, 'Products', and 'Customers' caches to use them via WithRegisteredSerializer(), WithRegisteredDistributedCache(), and WithRegisteredBackplane(). Also adds a cache key prefix per cache name.

```csharp
// COMPONENTS
services.AddFusionCacheSystemTextJsonSerializer();
services.AddStackExchangeRedisCache(opt => opt.Configuration = "REDIS_CONNECTION");
services.AddFusionCacheStackExchangeRedisBackplane(opt => opt.Configuration = "REDIS_CONNECTION");

// DEFAULT CACHE
services.AddFusionCache()
    .WithDefaultEntryOptions(opt =>
    {
        opt.Duration = TimeSpan.FromSeconds(10);
    })
;

// PRODUCTS CACHE
services.AddFusionCache("Products")
    .WithDefaultEntryOptions(opt =>
    {
        opt.Duration = TimeSpan.FromSeconds(20);
    })
    .WithCacheKeyPrefixByCacheName()
    .WithRegisteredSerializer()
    .WithRegisteredDistributedCache()
    .WithRegisteredBackplane()
;

// CUSTOMERS CACHE
services.AddFusionCache("Customers")
    .WithDefaultEntryOptions(opt =>
    {
        opt.Duration = TimeSpan.FromSeconds(30);
    })
    .WithCacheKeyPrefixByCacheName()
    .WithRegisteredSerializer()
    .WithRegisteredDistributedCache()
    .WithRegisteredBackplane()
;
```

--------------------------------

### Set duration and fail-safe

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/EagerRefresh.md

Basic FusionCache GetOrSet call with a 10-minute duration and fail-safe enabled. Any request within 10 minutes gets the cached value; the first request after expiry triggers a blocking refresh.

```csharp
product = cache.GetOrSet<Product>(
    "product:123",
    _ => GetProductFromDb(123),
    options => options
        // DURATION
        .SetDuration(TimeSpan.FromMinutes(10))
        // FAIL-SAFE
        .SetFailSafe(true)
);
```

--------------------------------

### Reuse ConnectionMultiplexer for distributed locker setup

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/CacheStampede.md

Shows how to reuse a single ConnectionMultiplexer across all Redis components (cache, backplane, locker) for better performance and resource usage. This is the recommended approach when you have multiple Redis components.

```csharp
var muxer = ConnectionMultiplexer.Connect("localhost:6379");

services.AddFusionCache()
	// SERIALIZER
	.WithSerializer(
		new FusionCacheSystemTextJsonSerializer()
	)
	// DISTRIBUTED CACHE
	.WithDistributedCache(
		new RedisCache(new RedisCacheOptions
		{
			ConnectionMultiplexerFactory = async () => muxer,
		})
	)
	// BACKPLANE
	.WithBackplane(
		new RedisBackplane(new RedisBackplaneOptions
		{
			ConnectionMultiplexerFactory = async () => muxer,
		})
	)
	// DISTRIBUTED LOCKER <-- HERE IT IS!
	.WithDistributedLocker(
		new RedisDistributedLocker(new RedisDistributedLockerOptions
		{
			ConnectionMultiplexerFactory = async () => muxer,
		})
	);
```

--------------------------------

### Register FusionCache with DI and default entry options

Source: https://github.com/ziggycreatures/fusioncache/blob/main/README.md

Register FusionCache with DI and set default entry options: duration of 2 minutes and Low priority.

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

--------------------------------

### GetOrSet without adaptive caching (fixed duration)

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/AdaptiveCaching.md

Example of calling GetOrSet with a factory that takes only a cancellation token, resulting in a fixed cache duration of 1 minute. The options lambda sets the duration to 1 minute.

```csharp
var id = 42;

// WITHOUT ADAPTIVE CACHING: THE DURATION IS FIXED TO 1 MIN
var product = cache.GetOrSet<Product>(
    $"product:{id}",
    ct => GetProductFromDb(id, ct),
    options => options.SetDuration(TimeSpan.FromMinutes(1)) // FIXED: 1 MIN
);
```

--------------------------------

### Register FusionCache in ConfigureServices

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/StepByStep.md

Register FusionCache in Startup.cs after the existing MemoryCache registration.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddMemoryCache();
    services.AddFusionCache();
}
```

--------------------------------

### Set tags on cache entries with Set and GetOrSet

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Tagging.md

Associate tags when saving entries using Set or GetOrSet. Later, RemoveByTag("tag-1") removes all entries with that tag; in this example, only the "bar" entry remains.

```csharp
cache.Set<int>("foo", 1, tags: ["tag-1", "tag-2"]);
cache.Set<int>("bar", 2, tags: ["tag-2", "tag-3"]);
cache.GetOrSet<int>("baz", _ => 3, tags: ["tag-1", "tag-3"]);

cache.RemoveByTag("tag-1");
```

--------------------------------

### Create a FusionCache logger and pass it to the constructor

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Creates an ILogger<FusionCache> from the factory and passes it to the FusionCache constructor. This enables logging for the cache instance.

```csharp
// CREATE THE SPECIFIC LOGGER
var logger = factory.CreateLogger<FusionCache>();

// SPECIFY THE LOGGER WHEN CREATING THE CACHE
var cache = new FusionCache(new FusionCacheOptions(), logger: logger);
```

--------------------------------

### Configure logging and FusionCache with DI

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/Logging.md

Adds logging services with the same console configuration and registers FusionCache. The logger is automatically provided to components.

```csharp
services.AddLogging(b => b
    // MIN LOG LEVEL (GLOBAL)
    .SetMinimumLevel(LogLevel.Warning)
    // SIMPLE CONSOLE SINK + SCOPES
    .AddSimpleConsole(options => options.IncludeScopes = true)
);

// THE LOGGER WILL BE AUTOMATICALLY PROVIDED
services.AddFusionCache();
```

--------------------------------

### Skip cache writes for flash-sale products using adaptive caching

Source: https://github.com/ziggycreatures/fusioncache/blob/main/docs/AdaptiveCaching.md

Shows how to use adaptive caching to avoid caching certain values, such as flash-sale products that change frequently. The factory sets SkipMemoryCacheWrite and SkipDistributedCacheWrite to true for flash-sale items, and adjusts Duration for other cases (null, recently updated, older). The default duration is 1 minute.

```csharp
var id = 42;

// USE ADAPTIVE CACHING TO SKIP CACHE WRITE FOR SOME VALUES RETURNED BY THE FACTORY
var product = cache.GetOrSet<Product>(
    $"product:{id}",
    (ctx, ct) => {
        var product = GetProductFromDb(id, ct);

        if (product.IsFlashSale) {
            // FLASH‑SALE PRODUCTS CHANGE PRICE AND STOCK CONSTANTLY
			// SO WE AVOID CACHING THEM TO PREVENT SERVING STALE DATA
            ctx.Options.SkipMemoryCacheWrite = true;
			ctx.Options.SkipDistributedCacheWrite = true;
        } else if (product is null) {
            // CACHE null FOR 5 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(5);
        } else if (product.LastUpdatedAt > DateTime.UtcNow.AddDays(-1)) {
            // CACHE PRODUCTS UPDATED IN THE LAST DAY FOR 1 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(1);
        } else if (product.LastUpdatedAt > DateTime.UtcNow.AddDays(-10)) {
            // CACHE PRODUCTS UPDATED IN THE LAST 10 DAYS FOR 10 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(10);
        } else {
            // CACHE ANY OLDER PRODUCT FOR 30 MIN
            ctx.Options.Duration = TimeSpan.FromMinutes(30);
        }

        return product;
    },
    options => options.SetDuration(TimeSpan.FromMinutes(1)) // DEFAULT: 1 MIN
);
```
Tokens:
Raw