Redis Implementation

Foundatio provides Redis implementations for caching, queues, messaging, locks, and file storage. Redis enables distributed scenarios across multiple processes and servers.

Overview

Implementation	Interface	Package
RedisCacheClient	ICacheClient	Foundatio.Redis
RedisHybridCacheClient	ICacheClient	Foundatio.Redis
RedisQueue<T>	IQueue<T>	Foundatio.Redis
RedisMessageBus	IMessageBus	Foundatio.Redis
RedisFileStorage	IFileStorage	Foundatio.Redis
CacheLockProvider	ILockProvider	Foundatio (with Redis cache)

Installation

dotnet add package Foundatio.Redis

Connection Setup

Basic Connection

using StackExchange.Redis;

var redis = await ConnectionMultiplexer.ConnectAsync("localhost:6379");

Production Connection

var options = new ConfigurationOptions
{
    EndPoints = { "redis-primary:6379", "redis-replica:6379" },
    Password = "your-password",
    Ssl = true,
    AbortOnConnectFail = false,
    ConnectRetry = 5,
    ConnectTimeout = 5000,
    SyncTimeout = 5000,
    AsyncTimeout = 5000
};

var redis = await ConnectionMultiplexer.ConnectAsync(options);

Connection String Format

redis:6379,password=secret,ssl=true,abortConnect=false

RedisCacheClient

A distributed cache backed by Redis.

Basic Usage

using Foundatio.Caching;

var cache = new RedisCacheClient(options =>
{
    options.ConnectionMultiplexer = redis;
});

// Store and retrieve
await cache.SetAsync("user:123", user);
var cachedUser = await cache.GetAsync<User>("user:123");

// With expiration
await cache.SetAsync("session:abc", session, TimeSpan.FromHours(1));

Configuration Options

var cache = new RedisCacheClient(options =>
{
    options.ConnectionMultiplexer = redis;
    options.LoggerFactory = loggerFactory;
    options.Serializer = new SystemTextJsonSerializer();
    options.ReadMode = CommandFlags.PreferReplica; // Route reads to replicas
});

Advanced Operations

// Increment/Decrement
await cache.IncrementAsync("counter", 1);
await cache.IncrementAsync("views", 1.5);

// Set if not exists
var added = await cache.AddAsync("lock-key", "locked", TimeSpan.FromSeconds(30));

// Batch operations
await cache.SetAllAsync(new Dictionary<string, object>
{
    ["user:1"] = user1,
    ["user:2"] = user2
});

var users = await cache.GetAllAsync<User>(new[] { "user:1", "user:2" });

RedisHybridCacheClient

Combines Redis (L2 distributed cache) with a local in-memory cache (L1) for optimal performance. This implements the industry-standard L1/L2 caching architecture.

How It Works

Read Flow:

┌─────────┐     ┌──────────────┐     ┌──────────────┐
│ Request │────▶│  L1 Cache    │────▶│  L2 Cache    │
│         │     │ (In-Memory)  │     │   (Redis)    │
└─────────┘     └──────────────┘     └──────────────┘
                      │                      │
                      ▼                      ▼
                 Cache Hit?            Cache Hit?
                      │                      │
                  Yes: Return          Yes: Store in L1
                                       Then: Return

Write Flow (Distributed-First):

┌──────────────────┐
│ Write Operation  │
└────────┬─────────┘
         │
         ▼
  ┌──────────────┐
  │  L2 Cache    │  ◀── Write to L2 first (source of truth)
  │   (Redis)    │
  └──────┬───────┘
         │
         │ Success?
         │
   ┌─────┴─────┐
   │           │
   ▼           ▼
  Yes          No
   │           │
   ▼           │
┌──────────────┐ │
│  L1 Cache    │ │
│ (In-Memory)  │ │
└──────────────┘ │
   │           │
   └─────┬─────┘
         │
         ▼
  ┌──────────────┐
  │ Message Bus  │───▶ Other Instances:
  │ (Publish)    │     Clear SPECIFIC
  └──────────────┘     Keys Only

• On read: Check L1 (local) first, then L2 (Redis). Store in L1 if found in L2.
• On write: Write to L2 (Redis) first, then update L1 only on success, then publish invalidation so other instances clear only the affected keys from their L1 cache.
• Prefix removal: RemoveByPrefixAsync("user:") clears all user:* keys on all instances.
• Full flush: RemoveAllAsync() with no keys clears entire L1 cache on all instances.

Shared Message Bus Topic

By default, all instances share the same Redis pub/sub topic for invalidation. In high-write scenarios, consider using separate topics per feature area. See the Caching Guide for details.

Basic Usage

var hybridCache = new RedisHybridCacheClient(
    redisConfig => redisConfig.ConnectionMultiplexer(redis).LoggerFactory(loggerFactory),
    localConfig => localConfig.MaxItems(1000)
);

Cache Invalidation

The hybrid cache uses Redis pub/sub to invalidate local caches across all instances:

// When you update a value, all instances are notified
await hybridCache.SetAsync("config:app", newConfig);

// Other instances automatically invalidate their local copy

Benefits

• Reduced Latency: Local cache hits avoid network round-trips
• Reduced Load: Fewer Redis operations
• Automatic Sync: Pub/sub keeps caches consistent
• Configurable Size: Control local cache memory usage

RedisQueue

A reliable distributed queue with visibility timeout and dead letter support.

Basic Usage

using Foundatio.Queues;

var queue = new RedisQueue<WorkItem>(options =>
{
    options.ConnectionMultiplexer = redis;
    options.Name = "work-items";
});

// Enqueue
await queue.EnqueueAsync(new WorkItem { Id = 1 });

// Dequeue and process
var entry = await queue.DequeueAsync();
if (entry != null)
{
    try
    {
        await ProcessAsync(entry.Value);
        await entry.CompleteAsync();
    }
    catch
    {
        await entry.AbandonAsync();
    }
}

Configuration Options

var queue = new RedisQueue<WorkItem>(options =>
{
    options.ConnectionMultiplexer = redis;
    options.Name = "work-items";

    // Visibility timeout
    options.WorkItemTimeout = TimeSpan.FromMinutes(5);

    // Retry settings
    options.Retries = 3;
    options.RetryDelay = TimeSpan.FromSeconds(30);

    // Dead letter settings
    options.DeadLetterTimeToLive = TimeSpan.FromDays(1);
    options.DeadLetterMaxItems = 100;

    // Run maintenance (cleanup dead letters)
    options.RunMaintenanceTasks = true;

    // Route reads to replicas (see Read Routing section for caveats)
    options.ReadMode = CommandFlags.PreferReplica;

    options.LoggerFactory = loggerFactory;
});

Queue Features

// Get queue statistics
var stats = await queue.GetQueueStatsAsync();
Console.WriteLine($"Queued: {stats.Queued}");
Console.WriteLine($"Working: {stats.Working}");
Console.WriteLine($"Dead Letter: {stats.Deadletter}");

// Process continuously
await queue.StartWorkingAsync(async (entry, token) =>
{
    await ProcessWorkItemAsync(entry.Value);
});

RedisMessageBus

A pub/sub message bus using Redis for cross-process communication.

Basic Usage

using Foundatio.Messaging;

var messageBus = new RedisMessageBus(options =>
{
    options.Subscriber = redis.GetSubscriber();
});

// Subscribe
await messageBus.SubscribeAsync<OrderCreatedEvent>(async message =>
{
    await HandleOrderCreatedAsync(message);
});

// Publish
await messageBus.PublishAsync(new OrderCreatedEvent { OrderId = "123" });

Configuration Options

var messageBus = new RedisMessageBus(options =>
{
    options.Subscriber = redis.GetSubscriber();
    options.Topic = "myapp"; // Channel prefix
    options.LoggerFactory = loggerFactory;
    options.Serializer = serializer;
});

Topic-Based Routing

// Messages are published to channels based on type
// e.g., "myapp:OrderCreatedEvent"

// All instances subscribed to this type receive the message
await messageBus.SubscribeAsync<OrderCreatedEvent>(HandleOrder);

RedisFileStorage

Store files in Redis (suitable for small files and caching scenarios).

Basic Usage

using Foundatio.Storage;

var storage = new RedisFileStorage(options =>
{
    options.ConnectionMultiplexer = redis;
});

// Save file
await storage.SaveFileAsync("config/settings.json", settingsJson);

// Read file
var content = await storage.GetFileContentsAsync("config/settings.json");

Configuration Options

var storage = new RedisFileStorage(options =>
{
    options.ConnectionMultiplexer = redis;
    options.LoggerFactory = loggerFactory;
    options.Serializer = serializer;
    options.ReadMode = CommandFlags.PreferReplica; // Route reads to replicas
});

WARNING

Redis file storage is best for small files or caching scenarios. For large files, consider Azure Blob Storage or S3.

Distributed Locks with Redis

Use CacheLockProvider with Redis for distributed locking.

Basic Usage

using Foundatio.Lock;

var locker = new CacheLockProvider(
    cache: redisCacheClient,
    messageBus: redisMessageBus
);

await using var lockHandle = await locker.AcquireAsync(
    resource: "order:123",
    timeUntilExpires: TimeSpan.FromMinutes(5),
    cancellationToken: token
);

if (lockHandle != null)
{
    // Exclusive access to order:123
    await ProcessOrderAsync("123");
}

Lock Patterns

// Try to acquire, fail fast
var lockHandle = await locker.AcquireAsync("resource");
if (lockHandle == null)
{
    throw new ResourceBusyException();
}

// Wait for lock with timeout
var lockHandle = await locker.AcquireAsync(
    resource: "resource",
    acquireTimeout: TimeSpan.FromSeconds(30)
);

// Extend lock duration
await lockHandle.RenewAsync(TimeSpan.FromMinutes(5));

Complete Redis Setup

Service Registration

public static IServiceCollection AddFoundatioRedis(
    this IServiceCollection services,
    string connectionString)
{
    // Connection
    services.AddSingleton<IConnectionMultiplexer>(sp =>
        ConnectionMultiplexer.Connect(connectionString));

    // Cache (Hybrid for best performance)
    services.AddSingleton<ICacheClient>(sp =>
        new RedisHybridCacheClient(
            redisConfig => redisConfig
                .ConnectionMultiplexer(sp.GetRequiredService<IConnectionMultiplexer>())
                .LoggerFactory(sp.GetRequiredService<ILoggerFactory>()),
            localConfig => localConfig.MaxItems(1000)
        ));

    // Message Bus
    services.AddSingleton<IMessageBus>(sp =>
        new RedisMessageBus(options =>
        {
            options.Subscriber = sp
                .GetRequiredService<IConnectionMultiplexer>()
                .GetSubscriber();
            options.LoggerFactory =
                sp.GetRequiredService<ILoggerFactory>();
        }));

    services.AddSingleton<IMessagePublisher>(sp =>
        sp.GetRequiredService<IMessageBus>());
    services.AddSingleton<IMessageSubscriber>(sp =>
        sp.GetRequiredService<IMessageBus>());

    // Lock Provider
    services.AddSingleton<ILockProvider>(sp =>
        new CacheLockProvider(
            sp.GetRequiredService<ICacheClient>(),
            sp.GetRequiredService<IMessageBus>()));

    return services;
}

// Add queue
public static IServiceCollection AddRedisQueue<T>(
    this IServiceCollection services,
    string name) where T : class
{
    services.AddSingleton<IQueue<T>>(sp =>
        new RedisQueue<T>(options =>
        {
            options.ConnectionMultiplexer =
                sp.GetRequiredService<IConnectionMultiplexer>();
            options.Name = name;
            options.LoggerFactory =
                sp.GetRequiredService<ILoggerFactory>();
        }));

    return services;
}

Usage

var builder = WebApplication.CreateBuilder(args);

var redisConnection = builder.Configuration.GetConnectionString("Redis")
    ?? "localhost:6379";

builder.Services.AddFoundatioRedis(redisConnection);
builder.Services.AddRedisQueue<WorkItem>("work-items");
builder.Services.AddRedisQueue<EmailMessage>("emails");

Production Considerations

Connection Resilience

var options = new ConfigurationOptions
{
    EndPoints = { "redis:6379" },
    AbortOnConnectFail = false,  // Don't throw on startup
    ConnectRetry = 5,
    ReconnectRetryPolicy = new ExponentialRetry(5000)
};

Health Checks

builder.Services.AddHealthChecks()
    .AddRedis(redisConnection, name: "redis");

Monitoring

// Get server info
var server = redis.GetServer("redis:6379");
var info = await server.InfoAsync();

// Memory usage
var memory = info.FirstOrDefault(g => g.Key == "memory");

Cluster Support

var options = new ConfigurationOptions
{
    EndPoints =
    {
        "redis-1:6379",
        "redis-2:6379",
        "redis-3:6379"
    }
};

// StackExchange.Redis handles cluster topology automatically
var redis = await ConnectionMultiplexer.ConnectAsync(options);

Connection Lifetime & Graceful Shutdown

Foundatio's Redis providers (RedisCacheClient, RedisQueue<T>, RedisMessageBus, RedisFileStorage, CacheLockProvider) all borrow an IConnectionMultiplexer you supply -- they never own or close it. This is intentional: the same multiplexer is typically shared across cache, queue, message bus, and locks, so a single provider closing it on Dispose() would break the others. Closing the connection is your application's responsibility.

This matters most when a host or network failure prevents Redis from receiving a normal close. In cluster mode, a single multiplexer opens a connection to every shard, so a lost host can leave each shard with a half-open socket and output buffers queued for a client that will never read them again. Because Redis/Valkey's event loop is single-threaded, a pile-up of these stale sockets can pin a node's CPU at 100% until the connections are cleared. If a process exits on a live host -- even via SIGKILL -- the operating system normally closes its TCP descriptors and Redis observes a FIN or reset; graceful shutdown is still useful because it lets hosted work drain and closes the multiplexer deliberately.

Two complementary mitigations:

1. Let the DI container dispose the multiplexer on graceful shutdown. Register it with a factory (not a pre-built instance) so the host-owned service provider disposes it during shutdown and sends a clean FIN:

// ✅ Factory registration: container creates it, so container disposes it
services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect(connectionString));

If you must keep a pre-built instance around, dispose it explicitly:

var lifetime = app.Services.GetRequiredService<IHostApplicationLifetime>();
lifetime.ApplicationStopped.Register(() => redis.Dispose());

2. Configure server-side backstops for host or network failures (for example, a lost node or network partition) where no client-side shutdown code can run. Set these on your Redis/Valkey server or parameter group:

• timeout -- e.g. 300 (seconds). Forces the server to drop a connection that has been completely idle for this long.
• tcp-keepalive -- e.g. 300 or lower. Has the OS send low-level TCP probes to detect and reap dead sockets.

The timeout setting applies to normal clients, not clients in Pub/Sub mode. If you use RedisMessageBus (or another provider with a subscribed connection), also configure tcp-keepalive and an appropriate client-output-buffer-limit pubsub so Redis can disconnect dead or stalled subscribers. Graceful shutdown should still dispose the shared multiplexer explicitly, since server-side backstops cannot replace client cleanup.

StackExchange.Redis's own KeepAlive option defaults to 60 seconds, which is lower than the settings above, so healthy connections won't be culled by the server-side timeout.

Best Practices

1. Connection Management

// ✅ Singleton connection, registered as a factory so the DI container
// owns and disposes it (sends a clean FIN on shutdown)
services.AddSingleton<IConnectionMultiplexer>(sp =>
    ConnectionMultiplexer.Connect("redis:6379"));

// ❌ Registering a pre-built instance -- the container only disposes
// objects it creates, so this connection is never closed on shutdown
services.AddSingleton<IConnectionMultiplexer>(
    ConnectionMultiplexer.Connect("redis:6379"));

// ❌ Creating new connections per use
var redis = ConnectionMultiplexer.Connect("redis:6379");

See Connection Lifetime & Graceful Shutdown for why the registration style matters.

2. Key Naming

// ✅ Hierarchical, descriptive keys
await cache.SetAsync("user:123:profile", profile);
await cache.SetAsync("order:456:items", items);

// ❌ Flat, ambiguous keys
await cache.SetAsync("123", profile);

3. Serialization

// Use efficient serializers for large objects
var serializer = new MessagePackSerializer();
var cache = new RedisCacheClient(o => o.Serializer = serializer);

4. TTL Strategy

// Always set expiration for cached data
await cache.SetAsync("data", value, TimeSpan.FromHours(1));

// Use sliding expiration for frequently accessed data
await cache.SetAsync("session", data,
    expiresIn: TimeSpan.FromMinutes(30));

Read Routing (Replica Reads)

All Redis providers support a ReadMode option that controls how read operations are routed in a master-replica topology. By default, reads go to the master node (CommandFlags.None). Set ReadMode to CommandFlags.PreferReplica to distribute reads to replica nodes, reducing load on the master and improving read throughput.

Configuration

using StackExchange.Redis;

// Enable replica reads on cache
var cache = new RedisCacheClient(o => o
    .ConnectionMultiplexer(redis)
    .ReadMode(CommandFlags.PreferReplica));

// Enable replica reads on queue
var queue = new RedisQueue<WorkItem>(o => o
    .ConnectionMultiplexer(redis)
    .ReadMode(CommandFlags.PreferReplica));

// Enable replica reads on file storage
var storage = new RedisFileStorage(o => o
    .ConnectionMultiplexer(redis)
    .ReadMode(CommandFlags.PreferReplica));

PreferReplica is safe on single-node deployments -- it falls back to the master when no replica exists. Write operations always go to the master regardless of this setting. Distributed locks are not affected (all lock operations use writes or Lua scripts on the master).

ReadMode Values

Value	Behavior	Use case
CommandFlags.None (default)	Read from master	Backward compatible; strict consistency
CommandFlags.PreferReplica	Read from replica if available, fall back to master	Recommended for master-replica topologies
CommandFlags.DemandReplica	Replica only; error if none available	Dedicated read-scaling scenarios
CommandFlags.DemandMaster	Master only; error if unavailable	Critical path operations

Operation Routing by Provider

Provider	Operation	Routing
RedisCacheClient	GetAsync, GetAllAsync, GetListAsync	Via ReadMode
	ExistsAsync, GetExpirationAsync	Via ReadMode
	SetAsync, RemoveAsync, IncrementAsync	Always master
	GetAllExpirationAsync	Always master (Lua script)
	Lua scripts (SetIfHigher, ReplaceIfEqual, etc.)	Always master
RedisQueue	Internal payload/metadata reads	Via ReadMode
	Enqueue, dequeue, complete, abandon	Always master
	Maintenance (work list, wait list scans)	Always master
RedisFileStorage	GetFileStreamAsync, GetFileInfoAsync, ExistsAsync	Via ReadMode
	GetFileListAsync	Via ReadMode
	SaveFileAsync, DeleteFileAsync	Always master
RedisMessageBus	Pub/sub	N/A (not routable)

Replication Lag Considerations

WARNING

Redis/Valkey replication is asynchronous. When using PreferReplica, reads may return stale data during the replication lag window (typically sub-millisecond on AWS ElastiCache, but variable under load). Review the scenarios below before enabling replica reads.

Scenario	Risk	Impact
Queue: dequeue payload read	High	After enqueue writes a payload, a dequeue on another process reads it back. If the replica hasn't replicated yet, the payload is null, the item is removed from the work list, and the message is silently lost.
Queue: abandon retry count	Medium	The attempts counter is incremented on master, then read back during abandon. A stale replica read returns an old count, giving the item one extra retry before dead-lettering.
Queue: maintenance renewal check	Medium	Lock renewal writes a timestamp to master. Maintenance reads it to check timeout. A stale read may auto-abandon an item that was just renewed, causing spurious re-processing.
Queue: maintenance wait time	Low	Wait times for retry delays are read from cache. A stale read makes an item wait slightly longer before retry.
File storage: rename/copy	None	RenameFileAsync and CopyFileAsync always read from master regardless of ReadMode to prevent data loss.
Cache: sorted set expiration	None	SetListExpirationAsync always reads from master regardless of ReadMode since the result drives a subsequent write.
Distributed locks	None	Lock acquire, release, and renewal all use writes or Lua scripts that execute on master.

Per-provider guidance:

• RedisCacheClient: PreferReplica is safe for most read-heavy workloads. Risk exists only if you read a key immediately after writing it from a different process.
• RedisQueue: Use caution. Under very high throughput, dequeue can fail to read a just-enqueued payload, causing message loss. Consider keeping CommandFlags.None for queues processing critical work items.
• RedisFileStorage: Generally safe. Read-before-write flows (RenameFileAsync, CopyFileAsync) always read from master to prevent data loss.

Next Steps

• Azure Implementation - Azure Storage and Service Bus
• AWS Implementation - S3 and SQS
• In-Memory Implementation - Local development

GitHub Repository

• Foundatio.Redis - View source code and contribute