NexGen.MediatR.Extensions.Caching 1.0.2

<div align="center"> <h1>⚡ NexGen.MediatR.Extensions.Caching ⚡</h1> <img src="assets/images/logo.png" height="200"> </div>

A lightweight and flexible library that extends MediatR to provide seamless caching and cache invalidation for requests using pipeline behaviors in .NET applications.
This library integrates caching as a cross-cutting concern, enabling developers to cache query results 🚀 and invalidate caches efficiently within the MediatR pipeline, improving application performance and scalability.

📑 Table of Contents

• Features
• Installation
• Configuration
  • Configure MediatR and Caching Services
  • Using Caching Services
  • Invalidate Cached Responses
• Examples
• Contributing
• License

✨ Features

• Seamless Integration: Adds caching to MediatR requests using pipeline behaviors.
• Flexible Cache Storage: Supports both in-memory (IMemoryCache) 💾 and distributed caching (IDistributedCache) 🌐.
• Automatic Cache Invalidation: Invalidate cached requests based on other requests or notifications.
• Customizable Cache Options: Configure expiration ⏳, sliding expiration, and cache keys per request.
• ASP.NET Core Compatibility: Works with ASP.NET Core’s DI and caching infrastructure.
• Extensible Design: Easily extend or customize caching behavior to suit your needs.

📦 Installation

You can install NexGen.MediatR.Extensions.Caching via NuGet Package Manager or the .NET CLI.

Using NuGet Package Manager

Install-Package NexGen.MediatR.Extensions.Caching

Using .NET CLI

dotnet add package NexGen.MediatR.Extensions.Caching

⚙️ Configuration

Step 1: Configure MediatR and Caching Services

In your Startup.cs or Program.cs, register MediatR and caching:

• Using MemoryCache

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

• Using Redis (NexGen.MediatR.Extensions.Caching.Redis)

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

Step 2: Using Caching Services

Add RequestOutputCache attribute to your IRequest class:

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

Step 3: Invalidate Cached Responses

Invalidate cached responses by tags:

public class TestClass
{
    private readonly IRequestOutputCache<WeatherForecastEvictRequest, string> _cache;

    public TestClass(IRequestOutputCache<WeatherForecastEvictRequest, string> cache)
    {
        _cache = cache;
    }

    public async Task EvictWeatherResponses()
    {
        List<string> tags = [ "weather" ];
        await _cache.EvictByTagsAsync(tags);
    }
}

💡 Examples

Example 1: Caching a List of Items

Suppose you have a query to fetch a list of Weather Forecasts:

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

public class WeatherForecastRequestHandler : IRequestHandler<WeatherForecastRequest, IEnumerable<WeatherForecastDto>>
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    public async Task<IEnumerable<WeatherForecastDto>> Handle(WeatherForecastRequest request, CancellationToken cancellationToken)
    {
        await Task.Delay(2000, cancellationToken);
        return Enumerable.Range(1, request.Limit).Select(index => new WeatherForecastDto
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        }).ToArray();
    }
}

The response will be cached with the key "weather" for 5 minutes.

Example 2: Invalidation on Update

When a response must be updated, invalidate the product list cache:

public class WeatherForecastUpdateRequest : IRequest<string>
{
}

public class WeatherForecastUpdateRequestHandler : IRequestHandler<WeatherForecastUpdateRequest, string>
{
    private readonly IRequestOutputCache<WeatherForecastUpdateRequest, string> _cache;

    public WeatherForecastUpdateRequestHandler(IRequestOutputCache<WeatherForecastUpdateRequest, string> cache)
    {
        _cache = cache;
    }

    public async Task<string> Handle(WeatherForecastUpdateRequest request, CancellationToken cancellationToken)
    {
        var tags = new List<string> { nameof(WeatherForecastDto) };
        await _cache.EvictByTagsAsync(tags, cancellationToken);

        return "Evicted!";
    }
}

NOTE: See Integration Test in test folder to see for example.

🤝 Contributing

Contributions are welcome! To contribute to NexGen.MediatR.Extensions.Caching:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Make your changes and commit them (git commit -m "Add your feature").
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

Please ensure your code follows the project's coding standards and includes unit tests where applicable.

📃 License

This project is licensed under the MIT License. See the LICENSE file for details.