AspNetCoreCacheKit 3.0.0

AspNetCoreCacheKit

A lightweight caching library for ASP.NET Core featuring group-based keys, per-entry and per-group duration, configurable via appsettings.json, and a DI-ready design that wraps IMemoryCache in a clean, testable abstraction.

Why AspNetCoreCacheKit? IMemoryCache is powerful but low-level. AspNetCoreCacheKit adds group-based key management, per-group and per-entry expiration, appsettings.json configuration, and a consistent type-safe API that makes caching easy to use and easy to mock in tests.

✨ Features

• 🔑 Group-based keys — organise cache entries with prefixes like "users:123"
• ⚡ GetOrCreate and GetOrCreateAsync — read-through pattern out of the box
• ⏱️ Per-group and per-entry duration — fine-grained expiration control
• 🗑️ Delete — remove a single entry by key or group + key
• ✅ Configuration validation with DataAnnotations
• 📐 Nullable reference types and generic type-safe Set<T> support
• 🎛️ appsettings.json configuration with sensible defaults
• 🧪 DI-ready — register with one line, mock ICacheService in tests

📋 Requirements

🚀 Installation

dotnet add package AspNetCoreCacheKit

🎯 Quick Start

1. Configure appsettings.json

{
  "CacheOptions": {
    "IsEnabled": true,
    "DurationMinutes": 60,
    "GroupDurations": {
      "users": 30,
      "tokens": 5,
      "countries": 1440
    }
  }
}

All duration values are expressed in minutes. GroupDurations is optional — groups without an entry use the global DurationMinutes.

2. Register services

// With appsettings.json
builder.Services.AddAspNetCoreCacheKit(builder.Configuration);

// Without appsettings (uses defaults)
builder.Services.AddAspNetCoreCacheKit();

3. Inject and use

[ApiController]
public class UsersController : ControllerBase
{
    private readonly ICacheService _cache;

    public UsersController(ICacheService cache)
    {
        _cache = cache;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetUser(int id, CancellationToken ct)
    {
        // Uses GroupDurations["users"] = 30 min from appsettings
        var user = await _cache.GetOrCreateAsync(
            "users",
            id.ToString(),
            _ => GetUserFromDb(id),
            ct: ct);

        return user is null ? NotFound() : Ok(user);
    }
}

📚 API Reference

Duration priority

Every method that writes to the cache resolves the expiration following this priority chain — first wins:

1. duration parameter passed explicitly to the method
2. GroupDurations[groupKey] configured in appsettings.json
3. Global DurationMinutes from appsettings.json

// 1. Explicit duration wins — cached for 2 minutes regardless of everything else
await _cache.GetOrCreateAsync("tokens", userId, _ => GenerateTokenAsync(), TimeSpan.FromMinutes(2));

// 2. No explicit duration — uses GroupDurations["users"] = 30 min from appsettings
await _cache.GetOrCreateAsync("users", "42", _ => GetUserFromDb(42));

// 3. No explicit duration, no group config — uses global DurationMinutes = 60 min
await _cache.GetOrCreateAsync("misc", "key", _ => LoadSomethingAsync());

GetOrCreateAsync — async read-through

// With group — uses GroupDurations["users"] or global fallback
var user = await _cache.GetOrCreateAsync("users", "42", _ => GetUserFromDb(42), ct: ct);

// With group + explicit duration override
var token = await _cache.GetOrCreateAsync(
    "tokens", userId,
    _ => GenerateTokenAsync(userId),
    duration: TimeSpan.FromMinutes(5),
    ct);

// Without group key
var config = await _cache.GetOrCreateAsync("app:config", _ => LoadConfigAsync(), ct: ct);

GetOrCreate — sync read-through

// Uses GroupDurations["countries"] = 1440 min from appsettings
var countries = _cache.GetOrCreate("countries", () => LoadCountries());

// Explicit override
var result = _cache.GetOrCreate("countries", "IT", () => LoadItaly(), TimeSpan.FromHours(2));

Set — explicit write

_cache.Set("users", "42", user);                                   // group duration or global
_cache.Set("users", "42", user, TimeSpan.FromMinutes(10));         // explicit override

Delete — remove an entry

_cache.Delete("users", "42");
_cache.Delete("app:config");

⚙️ Configuration options

Setting IsEnabled: false is useful in development or testing environments where you want to bypass the cache without changing code.

🧪 Testing

ICacheService is a plain interface — mock it directly in unit tests:

var cacheMock = new Mock<ICacheService>();

cacheMock
    .Setup(c => c.GetOrCreateAsync(
        "users", "1",
        It.IsAny<Func<ICacheEntry, Task<User>>>(),
        It.IsAny<TimeSpan?>(),
        It.IsAny<CancellationToken>()))
    .ReturnsAsync(new User { Id = 1, Name = "Simone" });

❤️ Support

If you find AspNetCoreCacheKit useful, consider sponsoring its development.

📄 License

MIT — see LICENSE for details.