NexGen.MediatR.Extensions.Caching 2.0.0

NexGen.MediatR.Extensions.Caching

<p align="center"> <img src="https://raw.githubusercontent.com/MatinGhanbari/NexGen.MediatR.Extensions.Caching/main/assets/images/logo.png" alt="NexGen.MediatR.Extensions.Caching" width="280" /> </p>

<p align="center"> <strong>MediatR output caching</strong> with pipeline behaviors, tag-based invalidation, and optional Entity Framework auto-eviction. </p>

<p align="center"> <a href="https://github.com/MatinGhanbari/NexGen.MediatR.Extensions.Caching/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/MatinGhanbari/NexGen.MediatR.Extensions.Caching/.github%2Fworkflows%2Fci.yml?style=flat-square&label=CI" alt="CI" /></a> <a href="https://www.nuget.org/packages/NexGen.MediatR.Extensions.Caching"><img src="https://img.shields.io/nuget/v/NexGen.MediatR.Extensions.Caching.svg?style=flat-square" alt="NuGet" /></a> <a href="https://www.nuget.org/packages/NexGen.MediatR.Extensions.Caching"><img src="https://img.shields.io/nuget/dt/NexGen.MediatR.Extensions.Caching?style=flat-square" alt="Downloads" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a> <img src="https://img.shields.io/badge/.NET-8%20%7C%209%20%7C%2010-512BD4?style=flat-square" alt=".NET 8 | 9 | 10" /> </p>

Table of contents

• About
• Features
• Packages
• Requirements
• Installation
• Quick start
• Configuration
  • In-memory cache
  • Redis
  • Garnet
  • Entity Framework auto-evict
  • Distributed eviction (Redis / Garnet)
  • Clear cache on startup
• Caching requests
• Invalidation
• How it works
• Examples
• Samples and benchmarks
• Changelog
• Contributing
• License

About

NexGen.MediatR.Extensions.Caching extends MediatR with opt-in response caching as a cross-cutting concern. Mark a request with [RequestOutputCache], and a pipeline behavior serves cached responses on hits and stores results on misses.

Invalidation is tag-based: associate tags with cached requests, then evict by tag with [RequestOutputCacheEvict], manually, or automatically when Entity Framework Core saves related entity changes. In-memory cache is local to one process. Redis and Garnet add Pub/Sub so other hosts sharing the same cache prefix drop the same tags.

Features

Packages

All four packages share the same version (lockstep releases).

Requirements

• .NET 8, .NET 9, or .NET 10
• MediatR (registered in your app as usual)
• Optional: Redis/Garnet for distributed cache; EF Core for auto-evict

Installation

Core

dotnet add package NexGen.MediatR.Extensions.Caching

Providers (as needed)

dotnet add package NexGen.MediatR.Extensions.Caching.Redis
dotnet add package NexGen.MediatR.Extensions.Caching.Garnet
dotnet add package NexGen.MediatR.Extensions.Caching.EntityFramework

Or via Package Manager Console:

Install-Package NexGen.MediatR.Extensions.Caching

Quick start

// Program.cs
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseMemoryCache();
});

[RequestOutputCache(tags: ["weather"], expirationInSeconds: 300)]
public sealed class WeatherForecastRequest : IRequest<IEnumerable<WeatherForecastDto>>
{
    public int Limit { get; set; } = 10;
}

Send the request through MediatR as usual; the first call executes the handler and caches the response. Later identical requests (same type + payload) are served from cache until expiration or eviction.

Configuration

Register one cache provider via AddMediatROutputCache. Configuring more than one throws.

In-memory cache

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseMemoryCache();
});

In-memory cache is process-local. [RequestOutputCacheEvict] and EF auto-evict run only in this host. Cross-service or split CQRS invalidation is not supported with the memory provider — use Redis or Garnet for that.

Optional provider defaults (applied when the attribute omits an explicit expirationInSeconds, i.e. uses the library constant 300):

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseMemoryCache(o => o.DefaultExpirationInSeconds = 600);
});

Redis

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseRedisCache("localhost:6379,password=YourRedisPassword");
});

Provider-specific options (InstanceName, Database, default TTL, or advanced ConfigurationOptions):

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseRedisCache(o =>
    {
        o.ConnectionString = builder.Configuration.GetConnectionString("Redis")!;
        o.InstanceName = "my-app:";
        o.Database = 1;
        o.DefaultExpirationInSeconds = 300;
    });
});

Multiple apps on one Redis: set a distinct InstanceName (and/or Database) per service. CLR namespaces in response cache keys do not isolate the shared container index keys (…:Container:*). Without a prefix, apps share that metadata on the same database.

Garnet

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseGarnetCache("localhost:6379,password=YourGarnetPassword");
});

Same nested options pattern as Redis via UseGarnetCache(Action<GarnetRequestOutputCacheOptions>). Use a distinct InstanceName / Database when multiple apps share one Garnet instance (same guidance as Redis above).

TTL precedence: an explicit expirationInSeconds on [RequestOutputCache] always wins (including 0 for never expire). Provider DefaultExpirationInSeconds only replaces the library default when the attribute uses the constructor default (300). Explicit 300 is indistinguishable from that default.

Entity Framework auto-evict

After a successful SaveChanges / SaveChangesAsync, the interceptor collects distinct entity CLR type names and invalidates those tags. Request tags must match (typically nameof(YourEntity)). With Redis or Garnet, the same tags are also published on Pub/Sub when distributed eviction is enabled.

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseSqlServer(connectionString);
    options.UseMediatROutputCacheAutoEvict(sp);
});

Distributed eviction (Redis / Garnet)

Query and command hosts use the same registration. No second DI entry point and no message bus.

// every host
builder.Services.AddMediatROutputCache(opt =>
    opt.UseRedisCache(o =>
    {
        o.ConnectionString = builder.Configuration.GetConnectionString("Redis")!;
        o.InstanceName = "my-app:";
        // o.EnableDistributedEviction = true; // default
    }));

[RequestOutputCache(tags: [nameof(User)], expirationInSeconds: 300)]
public sealed record GetUsersQuery : IRequest<Result<List<UserDto>>>;

[RequestOutputCacheEvict(nameof(User), nameof(Order), "dashboard-stats")]
public sealed record CreateUserCommand(string Name) : IRequest<Result>;

The publishing host evicts locally first, then notifies others. Each host ignores its own Pub/Sub echo. Redis Pub/Sub is at-most-once; a missed message is repaired by TTL.

UseGarnetCache mirrors the same options (EnableDistributedEviction, EvictionChannel, InstanceName).

Clear cache on startup

builder.Services.AddMediatROutputCache(opt =>
{
    opt.UseMemoryCache();
    opt.ClearCacheOnStartup();
});

Caching requests

Apply [RequestOutputCache] on the request type (the class that implements IRequest<TResponse>).

Note: TResponse should be a reference type (class, record, or interface), consistent with typical MediatR query responses.

Important: For EF auto-evict, include nameof for every related entity type in tags.

[RequestOutputCache(
    tags: ["weather", nameof(WeatherForecastDbEntity)],
    expirationInSeconds: 3600)]
public sealed class WeatherForecastRequest : IRequest<IEnumerable<WeatherForecastDto>>
{
    public int Limit { get; set; } = 10;
    public int Offset { get; set; } = 0;
}

Invalidation

Manual (by tags)

Inject IRequestOutputCacheInvalidator or IRequestOutputCache<TRequest, TResponse>:

public sealed class WeatherForecastUpdateHandler(
    IRequestOutputCacheInvalidator cache)
    : IRequestHandler<WeatherForecastUpdateRequest, string>
{
    public async Task<string> Handle(
        WeatherForecastUpdateRequest request,
        CancellationToken cancellationToken)
    {
        await cache.EvictByTagsAsync(["weather"], cancellationToken);
        return "Evicted";
    }
}

Flush everything

await cache.FlushAll(cancellationToken);

Automatic (EF Core)

When UseMediatROutputCacheAutoEvict is configured, you usually do not need manual eviction for data that changes through that DbContext. With Redis or Garnet, the interceptor also notifies other hosts when distributed eviction is enabled.

Command attribute

Eviction runs only after the handler returns successfully. A thrown exception or a failed FluentResults IResultBase skips eviction. Pass any number of tags; they are sent in one call.

[RequestOutputCacheEvict(nameof(User), nameof(Order), "dashboard-stats")]
public sealed record CreateUserCommand(string Name) : IRequest<Result>;

How it works

[RequestOutputCache]  →  RequestOutputCacheBehavior
                              │
                              ├─ hit  → return cached TResponse
                              └─ miss → handler → store → return TResponse

[RequestOutputCacheEvict] → handler succeeds → RequestOutputCacheEvictionDispatcher
                              ├─ local EvictByTagsAsync
                              └─ Redis/Garnet Pub/Sub (when enabled) → other hosts EvictByTagsAsync

Key:   NexGen.MediatR.Extensions:{Namespace:with:colons}:{TypeName}:{sha256(json(request))}
Index: tag → request types → cache keys  (via IRequestOutputCacheContainer)
Evict: EvictByTagsAsync(tags)
       or EF ChangeTracker → entity type Name as tags

Distributed providers (Redis / Garnet) also keep request→response type metadata so payloads can be deserialized correctly across nodes.

Examples

Cache a query

[RequestOutputCache(tags: ["weather"], expirationInSeconds: 300)]
public sealed class WeatherForecastRequest : IRequest<IEnumerable<WeatherForecastDto>>
{
    public int Limit { get; set; } = 10;
}

public sealed class WeatherForecastRequestHandler
    : IRequestHandler<WeatherForecastRequest, IEnumerable<WeatherForecastDto>>
{
    public async Task<IEnumerable<WeatherForecastDto>> Handle(
        WeatherForecastRequest request,
        CancellationToken cancellationToken)
    {
        await Task.Delay(2000, cancellationToken); // simulate work
        // ... build and return forecast list
        return [];
    }
}

Invalidate after an update

[RequestOutputCacheEvict("weather")]
public sealed class WeatherForecastUpdateRequest : IRequest<string>;

Or call the invalidator from a handler:

public sealed class WeatherForecastUpdateRequestHandler(
    IRequestOutputCacheInvalidator cache)
    : IRequestHandler<WeatherForecastUpdateRequest, string>
{
    public async Task<string> Handle(
        WeatherForecastUpdateRequest request,
        CancellationToken cancellationToken)
    {
        await cache.EvictByTagsAsync(["weather"], cancellationToken);
        return "Evicted!";
    }
}

Samples and benchmarks

Larger or more complex responses use more memory with the in-memory provider. Prefer Redis or Garnet for multi-instance and production workloads.

Migrating from 1.x

Version 2.0.0 removes the eviction-bus APIs. Use attributes plus one AddMediatROutputCache call.

Changelog

Release notes are maintained in CHANGELOG.md (Keep a Changelog format). Check that file for what changed in each version.

Contributing

Contributions are welcome through GitHub Issues and Pull Requests.

Please read CONTRIBUTING.md for the full contribution guide (development setup, coding standards, tests, and PR expectations) before opening an issue or PR.

License

This project is licensed under the MIT License.