FGutierrez.Core.DistributedCache 1.1.6

⚡ FGutierrez.Core.DistributedCache

🚀 Overview

FGutierrez.Core.DistributedCache is a high-performance distributed caching library for .NET 8 designed to provide a unified abstraction over multiple cache providers.

The library simplifies cache integration by providing:

• In-memory caching
• Redis distributed caching
• Automatic resilience and fallback strategies
• HTTP response caching middleware
• OpenTelemetry metrics
• Health checks
• Provider-based extensibility
• Declarative method-level caching

Built following cloud-native architecture principles, applications can consume caching capabilities without being coupled to a specific infrastructure provider.

✨ Features

🏗️ Architecture

The library follows a provider-based architecture where the application consumes a single abstraction while the infrastructure layer decides the cache implementation.

graph TD

    App[Application] --> Cache[ICoreCacheService]

    Cache --> Decorator[Resilient Cache Decorator]

    Decorator --> Redis[RedisCacheStorage]
    Decorator --> Memory[MemoryCacheStorage]

    Redis --> RedisServer[(Redis Server)]
    Memory --> Runtime[(Application Memory)]

🏭 Cache Provider Factory

When an application requires explicit provider selection, the library exposes ICacheServiceFactory.

sequenceDiagram

    participant C as Client (Repository)
    participant F as ICacheServiceFactory
    participant DI as IServiceProvider
    participant D as ResilientCacheDecorator
    participant R as RedisCacheStorage
    participant M as MemoryCacheStorage

    C->>F: GetCacheService(ProviderType)

    F->>DI: Resolve(ICoreCacheService)

    Note over DI: Configuration injects the<br/>ResilientCacheDecorator by default

    DI-->>F: Returns ResilientCacheDecorator

    F-->>C: Returns ICoreCacheService

    C->>D: GetAsync(key)

    alt Redis is Healthy

        D->>R: Execute operation
        R-->>D: Return value

    else Redis is unavailable

        Note over D: Apply fallback strategy

        D->>M: Execute operation
        M-->>D: Return value

    end

    D-->>C: Return final result

🛡️ Resilience Strategy

The default implementation uses a resilient decorator that automatically falls back to memory cache when Redis becomes unavailable.

flowchart TD

    Request([Cache Request])

    Request --> RedisCheck{Redis Available?}

    RedisCheck -- Yes --> RedisAccess[Attempt Redis Access]

    RedisAccess --> Success{Operation Successful?}

    Success -- Yes --> Return([Return Cached Data])

    Success -- No --> Fallback[Log Error + Memory Fallback]

    RedisCheck -- No --> Fallback

    Fallback --> MemoryAccess[Query Memory Cache]

    MemoryAccess --> Return

⚡ Cache Aside Pattern

The library provides a built-in GetOrAddAsync workflow.

sequenceDiagram

    participant App as Application
    participant Cache as ICoreCacheService
    participant DB as Data Source

    App->>Cache: GetOrAddAsync(key, factory)

    Cache->>Cache: Check cache entry

    alt Cache Hit

        Cache-->>App: Return cached value

    else Cache Miss

        Cache->>DB: Execute factory()

        DB-->>Cache: Return data

        Cache->>Cache: Store value

        Cache-->>App: Return new value

    end

🌐 HTTP Cache Middleware

Provides transparent response caching capabilities for API endpoints.

sequenceDiagram

    participant Client as HTTP Client
    participant MW as Cache Middleware
    participant API as API Endpoint

    Client->>MW: GET /api/resource

    MW->>MW: Check cache

    alt Cache Hit

        MW-->>Client: Cached Response

    else Cache Miss

        MW->>API: Execute Request

        API-->>MW: Response

        MW->>MW: Store Response

        MW-->>Client: Original Response

    end

📦 Installation

Install the package using NuGet:

dotnet add package FGutierrez.Core.DistributedCache

⚙️ Configuration

appsettings.json

{
  "DistributedCache": {
    "Provider": "Redis",
    "InstanceName": "MySystem",
    "Redis": {
      "Enabled": true,
      "Host": "localhost:6379",
      "Password": "your-password"
    }
  }
}

Redis Setup

var builder = WebApplication.CreateBuilder(args);

var distributedCache = config.GetSection("DistributedCache");

if (distributedCache.Exists())
{
    builder.Services.AddCoreDistributedCache(options =>
    {
        distributedCache.Bind(options);

        if (options.Redis.Enabled)
        {
            var redisSection =
                config.GetSection("DistributedCache:Redis");

            var host =
                redisSection["Host"] ?? "localhost:6379";

            var password =
                redisSection["Password"];

            options.Redis.Configuration = redisConfig =>
            {
                redisConfig.EndPoints.Add(host);

                if (!string.IsNullOrEmpty(password))
                {
                    redisConfig.Password = password;
                }

                redisConfig.AbortOnConnectFail = false;
            };
        }
    });
}

var app = builder.Build();
app.UseCoreDistributedCache();
app.Run();

🧑‍💻 Basic Usage

Inject ICoreCacheService into your services.

public class ProductService
{
    private readonly ICoreCacheService _cache;

    public ProductService(ICoreCacheService cache)
    {
        _cache = cache;
    }

    public async Task<Product> GetAsync(Guid id)
    {
        return await _cache.GetOrAddAsync(
            $"product:{id}",
            async () =>
            {
                return await LoadFromDatabase(id);
            });
    }
}

🎯 Advanced Usage: Provider Selection

public class MyBusinessService(ICacheServiceFactory cacheFactory)
{
    public async Task SaveAsync(bool forceRedis)
    {
        var provider =
            forceRedis
            ? CacheProviderType.Redis
            : CacheProviderType.Memory;

        var cache =
            cacheFactory.GetCache(provider);

        await cache.SetAsync(
            "my_key",
            myData,
            TimeSpan.FromMinutes(5));
    }


    public async Task DefaultAsync()
    {
        var cache =
            cacheFactory.GetDefaultCache();

        await cache.GetOrAddAsync(
            "default_key",
            async () => GetData());
    }
}

🏷️ Declarative Caching

Caching logic can be applied declaratively using the [Cacheable] attribute.

This removes repetitive cache handling code from business services.

Example:

[HttpGet("data/{id}")]
[Cacheable(
    tag: "Order",
    expirationSeconds: 300)]
public async Task<IActionResult> GetData(string id)
{
    var result =
        await myService.GetDataAsync(id);

    return Ok(result);
}

📊 Observability

The library integrates with OpenTelemetry Metrics.

Compatible with:

• Grafana
• Prometheus
• Jaeger
• Azure Monitor
• Elastic Observability
• Any OTLP-compatible backend

🩺 Health Checks

The package integrates with:

builder.Services.AddHealthChecks();

Provides monitoring for:

• Redis availability
• Memory cache status
• Provider connectivity

🛠️ Requirements

• .NET 8 SDK
• Microsoft.Extensions.Caching.Memory
• StackExchange.Redis
• OpenTelemetry
• Microsoft.Extensions.Diagnostics.HealthChecks

🏗️ Design Principles

FGutierrez.Core.DistributedCache follows:

• Clean Architecture principles
• Provider-based extensibility
• High cohesion / low coupling
• Cloud-native patterns
• Resilient infrastructure design
• Observability-first development

🗺️ Roadmap

Completed

• Memory Cache provider
• Redis provider
• Cache Aside pattern
• Resilience fallback
• OpenTelemetry metrics
• Health checks
• Declarative caching

Future

• SQL Server cache provider
• PostgreSQL cache provider
• Multi-level distributed cache
• Cache invalidation events
• Cache warming strategies

🤝 Contributing

Contributions are welcome.

Steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

📄 License

MIT License

© Federin Pastor Gutierrez Ortiz

See the LICENSE file for details.

⭐ Support

If this ecosystem helps you build modern .NET distributed systems, consider giving the repository a star on GitHub.

Building reusable cloud-native components, one package at a time.