Katalyst.Library.Cache 1.0.0

Katalyst.Library.Cache

Overview

Library.Cache is a small abstraction over ASP.NET Core caching that lets you switch between an in-process memory cache and a Redis-backed distributed cache using configuration only.

Capabilities

• Unified API — Work against ICacheService instead of IMemoryCache vs IDistributedCache directly.
• Configuration-driven provider — Choose Memory or Redis via the Cache:Provider setting.
• Per-entry options — Absolute TTL, sliding expiration, and (for memory) entry size when a size limit is configured.
• JSON serialization (Redis) — Values are stored using System.Text.Json; types must serialize/deserialize cleanly.

Configuration shape

{
  "Cache": {
    "Provider": "Memory",
    "Memory": {
      "SizeLimit": 65536,
      "DefaultAbsoluteExpirationMinutes": 5
    },
    "Redis": {
      "ConnectionUri": "localhost:6379",
      "InstanceName": "MyApp_",
      "DefaultAbsoluteExpirationMinutes": 5
    }
  }
}

Everything sits under the Cache section (see CacheSettings.SectionName). Provider selects the implementation: Memory (default when omitted or when the value is anything other than Redis) or Redis. Only the subsection for the active provider needs valid values—for example, with Memory, Redis can remain present for documentation or future switches but is unused at runtime.

• Memory — SizeLimit caps total entry weight for IMemoryCache when set; entries contribute CacheEntryOptions.Size (default 1). DefaultAbsoluteExpirationMinutes applies when a cache operation does not specify its own absolute or sliding expiration.
• Redis — ConnectionUri is the Redis URI or StackExchange.Redis configuration string (required when Provider is Redis); it is assigned to RedisCacheOptions.Configuration at registration. InstanceName is an optional logical prefix for keys. DefaultAbsoluteExpirationMinutes plays the same default-TTL role as on Memory.

Calling AddAppCache registers CacheSettings via services.Configure<CacheSettings>(configuration.GetSection("Cache")).

ICacheService methods

CacheEntryOptions

If you omit expiration on SetAsync / GetOrCreateAsync, the provider applies DefaultAbsoluteExpirationMinutes from its section when that value is set in configuration.

Memory provider

When it runs

Selected when Cache:Provider is missing or not Redis (comparison is case-insensitive). Registers IMemoryCache and MemoryCacheService as ICacheService.

How it works

• Stores objects in memory in the current process (no serialization).
• SizeLimit — Read from Cache:Memory:SizeLimit at startup and passed to AddMemoryCache. When set, entries participate in size-based eviction; each entry’s weight comes from CacheEntryOptions.Size (default 1). When the limit is exceeded due to capacity, evicted entries are logged at Error level.
• DefaultAbsoluteExpirationMinutes — Bound on CacheSettings.Memory. Used when a Set/GetOrCreate call does not specify AbsoluteExpirationRelativeToNow or SlidingExpiration (sliding-only entries still work when explicitly set).
• GetAllAsync — Because IMemoryCache does not expose enumeration, the provider keeps a lightweight key index for entries written via SetAsync / GetOrCreateAsync, reconciles against the cache on read, and removes keys on RemoveAsync and eviction. Keys written only through raw IMemoryCache elsewhere are not listed.

Configuration example

{
  "Cache": {
    "Provider": "Memory",
    "Memory": {
      "SizeLimit": 65536,
      "DefaultAbsoluteExpirationMinutes": 5
    }
  }
}

Using InstanceName / connection-style fields on Memory

The bound MemoryCacheSettings model may include properties also used for documentation symmetry with Redis; the memory provider implementation wires SizeLimit from configuration and DefaultAbsoluteExpirationMinutes through options as described above.

Redis provider

When it runs

Selected when Cache:Provider is Redis. Registers StackExchange.Redis distributed cache and RedisCacheService as ICacheService.

How it works

• Values are System.Text.Json serialized to UTF-8 bytes in Redis.
• ConnectionUri — Redis URI or StackExchange.Redis configuration string (required). If Redis is selected but Cache:Redis:ConnectionUri is empty, registration throws InvalidOperationException.
• InstanceName — Optional; passed to AddStackExchangeRedisCache and also used when building keys inside RedisCacheService (prefix before your logical key). Strongly recommended when you use GetAllAsync: the Redis provider builds a SCAN pattern from InstanceName so enumeration stays scoped to your app’s keys. If InstanceName is empty, GetAllAsync matches all keys in the configured database (*), which can be large or include non-cache data on a shared server.
• DefaultAbsoluteExpirationMinutes — Same role as for memory: default absolute TTL when per-call options do not set expiration.
• GetAllAsync — Uses StackExchange.Redis SCAN (via IServer.Keys with a page size) per connected non-replica endpoint, so it avoids blocking KEYS. Logical keys are returned by stripping InstanceName from each Redis key. A separate ConnectionMultiplexer is created lazily on the first GetAllAsync call only (the ASP.NET Core RedisCache owns its own connection and may dispose it independently), then disposed when the host disposes RedisCacheService. Values are not prefetched; call GetAsync<T> per key when you need payloads.

Configuration example

{
  "Cache": {
    "Provider": "Redis",
    "Redis": {
      "ConnectionUri": "localhost:6379",
      "InstanceName": "MyApp_",
      "DefaultAbsoluteExpirationMinutes": 5
    }
  }
}

Requirements

• A reachable Redis server matching ConnectionUri (e.g. redis://… or host:port forms accepted by StackExchange.Redis).
• Types used with GetAsync/SetAsync must be JSON-serializable with System.Text.Json (including compatible constructors/properties for your models).

Examples

ASP.NET Core (minimal hosting)

using Library.Cache;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAppCache(builder.Configuration);

var app = builder.Build();

app.MapGet("/demo", async (ICacheService cache, CancellationToken ct) =>
{
    var key = "greeting";
    var value = await cache.GetOrCreateAsync(
        key,
        _ => Task.FromResult($"Hello at {DateTimeOffset.UtcNow:O}"),
        new Library.Cache.Models.CacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(1)
        },
        ct);

    return Results.Ok(value);
});

app.Run();

appsettings.json

{
  "Cache": {
    "Provider": "Memory",
    "Memory": {
      "DefaultAbsoluteExpirationMinutes": 10
    }
  }
}

Switch to Redis by setting "Provider": "Redis" and filling in Cache:Redis as in the Redis section above.

Class library or tests (manual Configuration + ServiceCollection)

Use this when you do not have WebApplicationBuilder but still want the same registration:

using Library.Cache;
using Library.Cache.Models;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false)
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["Cache:Provider"] = "Memory",
        ["Cache:Memory:DefaultAbsoluteExpirationMinutes"] = "5"
    })
    .Build();

var services = new ServiceCollection();
services.AddLogging();
services.AddAppCache(configuration);

await using var provider = services.BuildServiceProvider();

var cache = provider.GetRequiredService<ICacheService>();

await cache.SetAsync(
    "user:42",
    "Ada",
    new CacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(2) });

var displayName = await cache.GetAsync<string>("user:42");

For Redis in tests, set Cache:Redis:ConnectionUri to your test Redis instance (or Testcontainers) before calling AddAppCache.

Referenced packages

The project references Microsoft.Extensions.Caching.Memory, Microsoft.Extensions.Caching.StackExchangeRedis, Microsoft.Extensions.Options.ConfigurationExtensions, Microsoft.Extensions.Logging.Abstractions, and StackExchange.Redis. Hosting apps typically already reference Microsoft.Extensions.Hosting / Microsoft.AspNetCore.App, which supply IServiceCollection extensions and IConfiguration.