CoreSystem.Cache 3.0.0

⚡ CoreSystem.Cache

Production-ready distributed caching framework for .NET 8

CoreSystem.Cache provides a unified cache abstraction with an execution pipeline, Memory caching, optional external cache storage with fallback, HTTP response caching, OpenTelemetry metrics, and tag-based invalidation.

✨ Features

• ✅ Memory cache provider
• ✅ Cache-Aside (GetOrAddAsync)
• ✅ Tag-based invalidation
• ✅ Optional external cache with Memory fallback
• ✅ HTTP response caching
• ✅ OpenTelemetry metrics for cache hits and misses
• ✅ Configurable execution pipeline
• ✅ Optional resilience integration through Core.Resilience
• ✅ Configurable serialization through Core.Serialization

Redis support is provided by the CoreSystem.Cache.Redis package, which registers Redis as the external primary storage and uses Memory as the fallback storage.

📦 Installation

dotnet add package CoreSystem.Cache

For Redis support, add the Redis provider package separately:

dotnet add package CoreSystem.Cache.Redis

🚀 Quick Start

Register the framework:

builder.Services.AddCoreCache(options =>
{
    options.InstanceName = "my-app";
});

Inject the cache service:

public sealed class ProductService(ICoreCache cache)
{
}

Store data:

await cache.SetAsync(
    "products:1",
    product,
    TimeSpan.FromMinutes(10));

Retrieve data:

var product = await cache.GetAsync<Product>("products:1");

Recommended Cache-Aside pattern:

var product = await cache.GetOrAddAsync(
    $"products:{id}",
    async ct => await repository.GetByIdAsync(id, ct),
    expiration: TimeSpan.FromMinutes(10),
    tags: ["products"]);

🌐 HTTP Response Caching

Enable the middleware:

app.UseCoreCache();

Decorate your endpoint:

[Cacheable(expirationSeconds: 300)]
public async Task<IActionResult> Get(Guid id)
{
    return Ok(await service.GetAsync(id));
}

HTTP response caching is applied only to endpoints decorated with CacheableAttribute. The default request policy allows GET and HEAD requests and excludes requests containing an Authorization header.

CacheOptions.DefaultExpiration sets the lifetime of a cached response when the attribute omits expirationSeconds. It is not a fallback for SetAsync or GetOrAddAsync: those operations store the entry with no expiration when the expiration argument is null, so pass one explicitly when a lifetime is needed.

📊 Why CoreSystem.Cache?

Redis and resilience capabilities are provided through their corresponding companion packages and are integrated with the cache pipeline when registered and configured.

🏗 Architecture

Application
      │
      ▼
 ICoreCache
      │
      ▼
 CachePipeline
      │
      ├── Logging
      ├── Metrics
      ├── Fallback (when available)
      └── Resilience (when registered)
      │
      ▼
 Cache Storage Resolver
      │
      ├── External Storage (Primary)
      │
      └── Memory Storage (Fallback)

When no external cache storage is registered, Memory is used as the primary storage. When one external storage is registered, it becomes the primary storage and Memory becomes the fallback. The core resolver allows only one external cache storage to be registered.

📚 Documentation

The full documentation includes:

• Getting Started
• Architecture
• Configuration
• Basic Usage
• HTTP Response Caching
• Observability
• Health Checks
• Extensibility
• Roadmap

Visit the GitHub repository for the complete documentation.

🤝 Contributing

Issues, discussions and pull requests are welcome.

📄 License

Released under the MIT License.