StackExchange.Redis.Extensions

StackExchange.Redis.Extensions is a library that extends StackExchange.Redis, making it easier to work with Redis in .NET applications. It wraps the base library with serialization, connection pooling, and higher-level APIs so you can store and retrieve complex objects without writing boilerplate code.

AI-Ready: This library provides an llms.txt file for AI coding assistants and a Claude Code plugin for configuration, scaffolding, and troubleshooting.

claude plugin add imperugo/StackExchange.Redis.Extensions

Then use /redis-configure, /redis-scaffold, or /redis-diagnose in Claude Code.

Features

• Store and retrieve complex .NET objects with automatic serialization
• Multiple serialization providers (System.Text.Json, Newtonsoft, Protobuf, MsgPack, MemoryPack, and more)
• Connection pooling with LeastLoaded and RoundRobin strategies
• Pub/Sub messaging with typed handlers
• Hash operations with per-field expiry (Redis 7.4+)
• GeoSpatial indexes (GEOADD, GEOSEARCH, GEODIST, etc.)
• Redis Streams with consumer group support
• Set, List, and Sorted Set operations with Set Combine (union, intersect, diff)
• HyperLogLog for probabilistic cardinality estimation
• Distributed locking with IAsyncDisposable auto-release
• Bitmap operations for analytics and feature flags
• Lua scripting for atomic server-side operations
• Key tagging and search
• Key management (rename, type, dump/restore)
• Atomic counters (StringIncrement/StringDecrement)
• Transparent compression (GZip, Brotli, LZ4, Snappy, Zstandard)
• IDistributedCache adapter (Microsoft-compatible Hash schema)
• ASP.NET Core Health Check for connection pool monitoring
• Azure Managed Identity support
• ASP.NET Core integration with DI and .NET 8+ Keyed Services
• Multiple named Redis instances with [FromKeyedServices] support
• OpenTelemetry integration
• .NET Standard 2.1, .NET 8, .NET 9, .NET 10

Architecture

Quick Start

1. Install packages

dotnet add package StackExchange.Redis.Extensions.Core
dotnet add package StackExchange.Redis.Extensions.System.Text.Json
dotnet add package StackExchange.Redis.Extensions.AspNetCore

2. Configure in appsettings.json

{
  "Redis": {
    "Password": "",
    "AllowAdmin": true,
    "Ssl": false,
    "ConnectTimeout": 5000,
    "SyncTimeout": 5000,
    "Database": 0,
    "Hosts": [
      { "Host": "localhost", "Port": 6379 }
    ],
    "PoolSize": 5,
    "IsDefault": true
  }
}

3. Register in DI

var redisConfig = builder.Configuration.GetSection("Redis").Get<RedisConfiguration>();
builder.Services.AddStackExchangeRedisExtensions<SystemTextJsonSerializer>(redisConfig);

4. Use it

public class MyService(IRedisDatabase redis)
{
    public async Task Example()
    {
        // Store an object
        await redis.AddAsync("user:1", new User { Name = "Ugo", Age = 38 });

        // Retrieve it
        var user = await redis.GetAsync<User>("user:1");

        // Store with expiry
        await redis.AddAsync("session:abc", sessionData, TimeSpan.FromMinutes(30));

        // Bulk operations
        var items = new[]
        {
            Tuple.Create("key1", "value1"),
            Tuple.Create("key2", "value2"),
        };
        await redis.AddAllAsync(items, TimeSpan.FromHours(1));

        // Search keys
        var keys = await redis.SearchKeysAsync("user:*");
    }
}

NuGet Packages

Core

Package	Description	NuGet
Core	Core library with abstractions and implementations
AspNetCore	ASP.NET Core DI integration and middleware

Serializers (pick one)

Package	Description	NuGet
System.Text.Json	Recommended for most scenarios
Newtonsoft	JSON.NET for legacy compatibility
MemoryPack	High-performance binary (net7.0+)
MsgPack	MessagePack binary format
Protobuf	Protocol Buffers
Utf8Json	UTF-8 native JSON

Compressors (optional)

Package	Algorithm	Best for	NuGet
Compression.LZ4	LZ4	Lowest latency
Compression.Snappier	Snappy	Low latency
Compression.ZstdSharp	Zstandard	Best ratio/speed
Compression.GZip	GZip	Wide compatibility
Compression.Brotli	Brotli	Best ratio for text

Usage Examples

Hash Operations

// Set a hash field
await redis.HashSetAsync("user:1", "name", "Ugo");
await redis.HashSetAsync("user:1", "email", "ugo@example.com");

// Get a hash field
var name = await redis.HashGetAsync<string>("user:1", "name");

// Set with per-field expiry (Redis 7.4+)
await redis.HashSetWithExpiryAsync("user:1", "session", sessionData, TimeSpan.FromMinutes(30));

// Query field TTL
var ttl = await redis.HashFieldGetTimeToLiveAsync("user:1", new[] { "session" });

GeoSpatial

// Add locations
await redis.GeoAddAsync("restaurants", new[]
{
    new GeoEntry(13.361389, 38.115556, "Pizzeria Da Michele"),
    new GeoEntry(15.087269, 37.502669, "Trattoria del Corso"),
    new GeoEntry(12.496366, 41.902782, "Da Enzo al 29"),
});

// Distance between two places
var km = await redis.GeoDistanceAsync("restaurants",
    "Pizzeria Da Michele", "Trattoria del Corso", GeoUnit.Kilometers);

// Search within 200km of a point
var nearby = await redis.GeoSearchAsync("restaurants", 13.361389, 38.115556,
    new GeoSearchCircle(200, GeoUnit.Kilometers),
    count: 10, order: Order.Ascending);

Redis Streams

// Publish typed events
await redis.StreamAddAsync("orders", "payload", new Order { Id = 1, Total = 99.99m });

// Consumer group workflow
await redis.StreamCreateConsumerGroupAsync("orders", "processors");

var entries = await redis.StreamReadGroupAsync("orders", "processors", "worker-1");
foreach (var entry in entries)
{
    // Process the message
    await redis.StreamAcknowledgeAsync("orders", "processors", entry.Id!);
}

Pub/Sub

// Subscribe to typed messages
await redis.SubscribeAsync<OrderEvent>("orders:new", async order =>
{
    Console.WriteLine($"New order: {order.Id}");
});

// Publish
await redis.PublishAsync("orders:new", new OrderEvent { Id = 42 });

Atomic Counters

// Increment/decrement with long (default step = 1)
var views = await redis.StringIncrementAsync("page:views");
var stock = await redis.StringDecrementAsync("product:123:stock");

// Custom step
await redis.StringIncrementAsync("stats:bytes", 1024);

// Double precision
await redis.StringIncrementAsync("account:balance", 49.99);

Set Operations

// Combine sets: union, intersect, difference
var allTags = await redis.SetCombineAsync<string>(SetOperation.Union, "user:1:tags", "user:2:tags");
var commonTags = await redis.SetCombineAsync<string>(SetOperation.Intersect, "user:1:tags", "user:2:tags");

// Store result in a new key
await redis.SetCombineAndStoreAsync(SetOperation.Union, "all:tags", new[] { "set:a", "set:b", "set:c" });

HyperLogLog

// Count unique visitors
await redis.HyperLogLogAddAsync("page:home:visitors", userId);
var uniqueCount = await redis.HyperLogLogLengthAsync("page:home:visitors");

// Merge daily counts into a monthly aggregate
await redis.HyperLogLogMergeAsync("visitors:2024:01", new[]
{
    "visitors:2024:01:01",
    "visitors:2024:01:02",
    "visitors:2024:01:03",
});

Distributed Lock

// Acquire a lock with automatic release on dispose
await using var lockObj = await redis.LockAcquireAsync(
    "resource:order:123",
    expiry: TimeSpan.FromSeconds(30),
    maxRetries: 5,
    retryDelay: TimeSpan.FromMilliseconds(200));

if (lockObj is not null)
{
    // Critical section — lock is held
    await ProcessOrder(123);
}
// Lock released automatically on dispose

Bitmap Operations

// Track daily active users (1 bit per user ID)
await redis.StringSetBitAsync("dau:2024-01-15", userId, true);

// Count active users
var activeCount = await redis.StringBitCountAsync("dau:2024-01-15");

// Compute users active on ALL days (AND operation)
await redis.StringBitOperationAsync(Bitwise.And, "wau:all-days", new[]
{
    "dau:2024-01-15", "dau:2024-01-16", "dau:2024-01-17",
});

Lua Scripting

// Atomic server-side operations
var script = @"
    local current = tonumber(redis.call('GET', KEYS[1]) or '0')
    if current < tonumber(ARGV[1]) then
        return redis.call('INCR', KEYS[1])
    end
    return current";

var result = await redis.ScriptEvaluateAsync(
    script,
    new RedisKey[] { "counter:views" },
    new RedisValue[] { 100 });

Key Management

// Rename a key
await redis.KeyRenameAsync("old-key", "new-key");

// Check key type
var type = await redis.KeyTypeAsync("my-key"); // RedisType.String, Set, Hash, ...

// Dump and restore (migrate between databases)
var dump = await redis.KeyDumpAsync("my-key");
await redis.KeyRestoreAsync("my-key-copy", dump, TimeSpan.FromHours(1));

IDistributedCache

// Register the IDistributedCache adapter (call after AddStackExchangeRedisExtensions)
builder.Services.AddStackExchangeRedisExtensions<SystemTextJsonSerializer>(redisConfig);
builder.Services.AddRedisDistributedCache();

// Use standard IDistributedCache anywhere
public class MyService(IDistributedCache cache)
{
    public async Task CacheData()
    {
        await cache.SetAsync("session:abc", data, new DistributedCacheEntryOptions
        {
            SlidingExpiration = TimeSpan.FromMinutes(20),
            AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(4),
        });

        var cached = await cache.GetAsync("session:abc");
    }
}

Note: Uses a Hash-based schema (data/absexp/sldexp) compatible with Microsoft.Extensions.Caching.StackExchangeRedis, enabling zero-downtime migration between providers.

Health Check

// Register the health check
builder.Services.AddHealthChecks()
    .AddRedisExtensionsHealthCheck();

// Returns:
// - Healthy: all pool connections active + PING OK
// - Degraded: some connections invalid but Redis responding
// - Unhealthy: all connections invalid or PING fails

Keyed DI Services (.NET 8+)

// Register with named configurations
builder.Services.AddStackExchangeRedisExtensions<SystemTextJsonSerializer>(new[]
{
    new RedisConfiguration { Name = "cache", IsDefault = true, /* ... */ },
    new RedisConfiguration { Name = "session", /* ... */ },
});

// Inject by name using [FromKeyedServices]
public class MyService(
    [FromKeyedServices("cache")] IRedisDatabase cacheDb,
    [FromKeyedServices("session")] IRedisDatabase sessionDb)
{
    // Each resolves to its own Redis instance with isolated connection pool
}

Compression

// Enable transparent compression with any serializer
services.AddStackExchangeRedisExtensions<SystemTextJsonSerializer>(config);
services.AddRedisCompression<LZ4Compressor>();  // That's it!

// All operations automatically compress/decompress
await redis.AddAsync("large-data", myLargeObject);  // stored compressed
var obj = await redis.GetAsync<MyObject>("large-data");  // decompressed automatically

Azure Managed Identity

var config = new RedisConfiguration { /* ... */ };
config.ConfigurationOptionsAsyncHandler = async opts =>
{
    await opts.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());
    return opts;
};

Connection Pooling

The pool automatically skips disconnected connections and falls back gracefully when all connections are down, letting StackExchange.Redis's internal reconnection logic recover.

Serialization Behavior

All values stored in Redis go through the configured ISerializer. This means:

• A string value "hello" is stored as "\"hello\"" (JSON-encoded)
• Use IRedisDatabase.Database for raw Redis operations without serialization
• All serializers follow the same convention: null input produces an empty byte array

Configuration Reference

Documentation

Full documentation is available in the doc/ folder:

Getting Started

• Setup & Installation
• Dependency Injection
• ASP.NET Core Integration

Configuration

• Configuration Overview — JSON | C# | Connection Pool

Serializers

• Serializers Overview — System.Text.Json | Newtonsoft | MemoryPack | MsgPack | Protobuf

Features

• Usage Guide — Add, Get, Replace, Bulk operations
• GeoSpatial Indexes
• VectorSet — AI/ML Similarity Search (Redis 8.0+)
• Redis Streams
• Pub/Sub Messaging
• HyperLogLog — Probabilistic cardinality estimation
• Distributed Lock — Redis-based locking with IAsyncDisposable
• Bitmap Operations — Bit-level analytics and feature flags
• Lua Scripting — Server-side script execution
• Hash Field Expiry (Redis 7.4+)
• Compression — GZip, Brotli, LZ4, Snappy, Zstandard
• Health Check
• IDistributedCache Adapter

Advanced

• Migration Guide: v12 → v13
• Migration Guide: v11 → v12
• Logging & Diagnostics
• Multiple Redis Servers — including Keyed DI Services
• Azure Managed Identity
• OpenTelemetry
• Redis Information Middleware
• NuGet Packages

Contributing

Thanks to all the people who already contributed!

Please read CONTRIBUTING.md before submitting a pull request. PRs target the master branch only.

License

StackExchange.Redis.Extensions is Copyright © Ugo Lattanzi and other contributors under the MIT license.