Odex.AspNetCore.Caching.Redis 0.2.0

Odex.AspNetCore.Caching.Redis

Opinionated Redis caching for ASP.NET Core on top of IDistributedCache (StackExchange.Redis). Get JSON serialization, SHA-256 key hashing, configurable TTL, cache-aside helpers, and optional registration when Redis is not configured.

Table of contents

• About
• Installation
• Requirements
• Configuration
• Quick start
• Capabilities
• Key format
• Examples
• API reference
• Testing without Redis
• Upgrading
• CI/CD
• Contributing
• License
• Links

About

Odex.AspNetCore.Caching.Redis wraps IDistributedCache with a small, async-first surface area: GetAsync, SetAsync, InvalidateAsync, GetOrSetAsync, and ExistsAsync. Logical keys are hashed with SHA-256 so Redis keys stay short and safe. Application isolation uses a configurable key prefix (StackExchange InstanceName) plus a cache namespace segment in BuildKey.

Registration is conditional: if Redis:Configuration is missing or empty, AddOdexRedis does not register services—useful for local development or feature flags.

Installation

dotnet add package Odex.AspNetCore.Caching.Redis

Pin a version for reproducible builds:

dotnet add package Odex.AspNetCore.Caching.Redis --version 0.2.0

Requirements

NuGet dependencies: Microsoft.Extensions.Caching.StackExchangeRedis, Microsoft.Extensions.Options.ConfigurationExtensions. StackExchange.Redis is pulled transitively.

Configuration

Add a Redis section to appsettings.json (or environment variables / secrets):

{
  "Redis": {
    "Configuration": "localhost:6379,abortConnect=false",
    "KeyPrefix": "MyApp",
    "CacheName": "odexredis",
    "DefaultExpirationMinutes": 60,
    "UseCamelCaseJson": true
  }
}

Environment variable example: Redis__Configuration=host:6379,password=...

Quick start

1. Register services in Program.cs:

using Odex.AspNetCore.Caching.Redis;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOdexRedis(builder.Configuration);
var app = builder.Build();

2. Inject IOdexRedis and use hashed keys:

public class ProductService(IOdexRedis cache)
{
    public async Task<Product?> GetProductAsync(int id, CancellationToken ct = default)
    {
        var key = cache.BuildKey($"product:{id}");
        return await cache.GetAsync<Product>(key, ct);
    }

    public async Task SetProductAsync(int id, Product product, CancellationToken ct = default)
    {
        var key = cache.BuildKey($"product:{id}");
        await cache.SetAsync(key, product, ct);
    }
}

Capabilities

Key format

BuildKey returns the key passed to IDistributedCache:

{cacheName}:{sha256_hex_lowercase}

KeyPrefix is applied by Redis as InstanceName, not inside BuildKey:

Examples

Custom expiration

var options = new DistributedCacheEntryOptions
{
    AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10),
    SlidingExpiration = TimeSpan.FromMinutes(2)
};
await cache.SetAsync(key, data, options, cancellationToken);

Get-or-set (cache-aside)

var product = await cache.GetOrSetAsync(
    cache.BuildKey($"product:{id}"),
    ct => repository.GetProductAsync(id, ct),
    cancellationToken);

Optional Redis (e.g. local development)

When Redis:Configuration is empty, resolve IOdexRedis optionally:

public class MyService(IServiceProvider services)
{
    private readonly IOdexRedis? _cache = services.GetService<IOdexRedis>();

    public async Task DoWorkAsync(CancellationToken ct)
    {
        if (_cache is null) return;
        await _cache.SetAsync(_cache.BuildKey("key"), "value", ct);
    }
}

Post-configure options

builder.Services.AddOdexRedis(builder.Configuration, options =>
{
    options.CacheName = "catalog";
    options.DefaultExpirationMinutes = 30;
});

API reference

IOdexRedis

ServiceCollectionExtensions

XML documentation is included in the NuGet package for IntelliSense.

Testing without Redis

Use MemoryDistributedCache in tests:

services.AddDistributedMemoryCache();
services.Configure<OdexRedisOptions>(o =>
{
    o.KeyPrefix = "Test";
    o.DefaultExpirationMinutes = 5;
});
services.AddSingleton<IOdexRedis, OdexRedis>();

See Odex.AspNetCore.Caching.Redis.Tests in this repository for unit tests.

Upgrading

See the changelog for version history and breaking changes.

0.1.x → 0.2.0 (summary):

• AddOdexRedis now registers IOdexRedis.
• BuildKey no longer embeds KeyPrefix (avoids double-prefix with InstanceName).
• SetAsync overload uses DistributedCacheEntryOptions instead of object.
• Prefer ServiceCollectionExtensions over obsolete ServiceCollectionExtension.

CI/CD

Contributing

See CONTRIBUTING.md for local setup, pull-request guidelines, and release process.

License

This project is released under the MIT License.

Copyright (c) Asen O'Shabi.

Links