RequestContext 2.0.0

RequestContext

A lightweight .NET 8 package for production-ready request handling in ASP.NET Core APIs.

RequestContext helps you standardize:

• Correlation IDs for tracing requests across services
• Idempotency for safe retry of write operations
• Global exception handling with structured JSON responses
• Request context access (IRequestContext) from your application services

What this package provides

1) Correlation ID middleware

• Reads X-Correlation-Id from incoming requests
• Generates a new correlation id if missing
• Sets HttpContext.TraceIdentifier
• Returns the correlation id in response headers
• Adds logging scope with CorrelationId

Header used: X-Correlation-Id

2) Idempotency middleware

• Applies only to endpoints marked with [Idempotency]
• Uses X-Idempotency-Id request header as idempotency key
• Uses Redis for short-lived lock + cooldown cache
• Persists idempotency records in your EF Core DbContext
• Prevents duplicate processing of same key

Header used: X-Idempotency-Id

3) Global exception middleware

• Catches unhandled exceptions
• Returns consistent JSON response with status code + trace info
• Maps common exceptions:
  • ArgumentException → 400
  • UnauthorizedAccessException → 401
  • KeyNotFoundException → 404
  • all others → 500

4) IRequestContext

Inject IRequestContext anywhere to access request metadata:

• CorrelationId
• UserName
• ClientIp
• UserAgent
• IsAuthenticated
• IdempotencyKey (exposed by contract)

Installation

dotnet add package RequestContext

Quick start

1) Register services

using RequestContext.DependancyInjection;
using RequestContext.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpContextAccessor();
builder.Services.AddRequestContext();

// Register your DbContext (example)
builder.Services.AddDbContext<AppDbContext>(options =>
{
    // options.UseSqlServer(...);
});

// Register Redis connection multiplexer
builder.Services.AddSingleton<IConnectionMultiplexer>(_ =>
    ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!));

builder.Services.AddIdempotency(options =>
{
    options.DbContextType = typeof(AppDbContext);
});

2) Add middleware pipeline

using RequestContext.Middlewares;
using RequestContext.Extensions;

var app = builder.Build();

app.UseMiddleware<GlobalExceptionMiddleware>();
app.UseMiddleware<CorrelationIdMiddleware>();
app.UseIdempotency();

app.MapControllers();
app.Run();

Recommended order: GlobalExceptionMiddleware → CorrelationIdMiddleware → UseIdempotency()

Using idempotency on endpoints

Annotate write endpoints with [Idempotency]:

[HttpPost("payments")]
[Idempotency(120)] // key valid for 120 seconds
public IActionResult CreatePayment([FromBody] CreatePaymentRequest request)
{
    // Your write logic
    return Ok(new { success = true });
}

Without expiry (never expires):

[Idempotency]

Client request must include:

X-Idempotency-Id: your-unique-operation-key

Consuming IRequestContext

public class AuditService
{
    private readonly IRequestContext _requestContext;

    public AuditService(IRequestContext requestContext)
    {
        _requestContext = requestContext;
    }

    public void WriteAudit()
    {
        var correlationId = _requestContext.CorrelationId;
        var user = _requestContext.UserName;
        var ip = _requestContext.ClientIp;
        // use metadata in logs/audit trail
    }
}

EF Core model requirements

Your configured DbContext should include IdempotencyRecord:

public class AppDbContext : DbContext
{
    public DbSet<IdempotencyRecord> IdempotencyRecords => Set<IdempotencyRecord>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<IdempotencyRecord>()
            .HasIndex(x => x.Key)
            .IsUnique();
    }
}

Then create/apply migrations.

Expected runtime behavior

• First request with new idempotency key: request is processed and persisted
• Concurrent duplicate request: returns 409 Conflict
• Replayed request within cooldown or existing persisted key: returns 409 Conflict
• Missing idempotency header: middleware skips idempotency handling
• Endpoints without [Idempotency]: middleware skips idempotency handling

Notes

• Package target: .NET 8
• Requires ASP.NET Core pipeline
• Requires Redis (StackExchange.Redis) and EF Core for idempotency functionality

License

Use according to your package/repository license.