CasCap.Common.Caching 4.9.0

CasCap.Common.Caching

Multi-tier distributed caching library implementing the cache-aside pattern with support for Memory, Disk, and Redis cache layers.

Purpose

Provides a complete caching infrastructure with local (in-process) and remote (Redis) cache tiers, synchronised expiration via Redis Pub/Sub, and configurable serialization (JSON or MessagePack). Includes background services for cache expiry management, an async duplicate-lock mechanism to prevent thundering-herd scenarios, and optional Redis-based distributed locking via RedLock.net.

Target frameworks: netstandard2.0, net8.0, net9.0, net10.0

Services

Extensions

Configuration

Enums

Service Architecture

Multi-tier caching infrastructure with cache-aside pattern:

flowchart TD
    CLIENT["Application Code"]

    subgraph CachingServices["Caching Services"]
        DIST["DistributedCacheService<br/>(Multi-tier orchestrator)"]

        subgraph LocalCaches["Local Cache Implementations"]
            MEM["MemoryCacheService<br/>(IMemoryCache)"]
            DISK["DiskCacheService<br/>(File system)"]
        end

        subgraph RemoteCaches["Remote Cache"]
            REDIS["RedisCacheService<br/>(StackExchange.Redis)"]
        end

        subgraph BackgroundServices["Background Services"]
            EXPIRY_BG["CacheExpiryBgService"]
            LOCAL_EXP["LocalCacheExpiryService"]
            REMOTE_EXP["RemoteCacheExpiryService"]
        end
    end

    REDIS_SERVER[("Redis Server<br/>(Pub/Sub)")]
    LOCK["AsyncDuplicateLock<br/>(Prevent thundering herd)"]
    REDLOCK["IDistributedLockFactory<br/>(RedLock.net — optional)"]

    CLIENT --> DIST
    DIST --> MEM
    DIST --> DISK
    DIST --> REDIS
    DIST -.uses.-> LOCK
    DIST -."opt-in distributed lock".-> REDLOCK

    REDIS <--> REDIS_SERVER
    REDLOCK -."Redlock algorithm".-> REDIS_SERVER

    EXPIRY_BG --> LOCAL_EXP
    EXPIRY_BG --> REMOTE_EXP

    REDIS_SERVER -."Pub/Sub expiry sync".-> LOCAL_EXP
    REDIS_SERVER -."Pub/Sub expiry sync".-> REMOTE_EXP

    LOCAL_EXP -.expires.-> MEM
    LOCAL_EXP -.expires.-> DISK
    REMOTE_EXP -.expires.-> REDIS

Configuration Examples

All configuration lives under the CasCap:CachingConfig section in appsettings.json. Properties omitted from the JSON use their record defaults.

Minimal — local memory cache only

{
  "CasCap": {
    "CachingConfig": {
      "RemoteCacheConnectionString": "localhost:6379,abortConnect=false"
    }
  }
}

Redis remote cache with JSON serialization

{
  "CasCap": {
    "CachingConfig": {
      "RemoteCacheConnectionString": "localhost:6379,abortConnect=false",
      "RemoteCache": {
        "SerializationType": "Json"
      }
    }
  }
}

Distributed locking enabled (cache-miss protection)

{
  "CasCap": {
    "CachingConfig": {
      "RemoteCacheConnectionString": "localhost:6379,abortConnect=false",
      "DistributedLockingEnabled": true,
      "RemoteCache": {
        "SerializationType": "Json"
      }
    }
  }
}

Distributed locking with custom Redlock profiles

{
  "CasCap": {
    "CachingConfig": {
      "RemoteCacheConnectionString": "localhost:6379,abortConnect=false",
      "DistributedLockingEnabled": true,
      "RemoteCache": {
        "SerializationType": "Json"
      },
      "Redlock": {
        "ExpiryMs": 5000,
        "WaitMs": 5000,
        "RetryMs": 250,
        "Profiles": {
          "LeaderElection": {
            "ExpiryMs": 30000,
            "WaitMs": 60000,
            "RetryMs": 5000
          }
        }
      }
    }
  }
}

Fully configured — production-style deployment

{
  "CasCap": {
    "CachingConfig": {
      "RemoteCacheConnectionString": "redis-sentinel:26379,serviceName=mymaster,abortConnect=false,connectTimeout=1000",
      "DistributedLockingEnabled": true,
      "CacheKeyFormat": "Production:{0}",
      "MemoryCacheSizeLimit": 500,
      "UseBuiltInLuaScripts": true,
      "DiskCacheFolder": "/var/cache/cascap",
      "ExpirationSyncMode": "ExpireViaPubSub",
      "MemoryCache": {
        "IsEnabled": true,
        "ClearOnStartup": false,
        "SerializationType": "None"
      },
      "DiskCache": {
        "IsEnabled": false,
        "SerializationType": "Json"
      },
      "RemoteCache": {
        "IsEnabled": true,
        "DatabaseId": 1,
        "ClearOnStartup": false,
        "SerializationType": "MessagePack"
        },
        "Redlock": {
          "RedisKeyFormat": "Production:RedLock:{0}",
          "ExpiryMs": 5000,
        "WaitMs": 5000,
        "RetryMs": 250,
        "Profiles": {
          "LeaderElection": {
            "ExpiryMs": 30000,
            "WaitMs": 60000,
            "RetryMs": 5000
          },
          "LongRunningJob": {
            "ExpiryMs": 120000,
            "WaitMs": 30000,
            "RetryMs": 10000
          }
        }
      }
    }
  }
}

Dependencies

NuGet Packages

Project References