🚀 Getting Started

Welcome to CoreSystem.Idempotency, a production-ready distributed idempotency library for .NET 8.

In this guide you'll learn how to:

• Install the package
• Configure the framework
• Register the services
• Enable the middleware
• Execute your first idempotent request

Estimated time: 5 minutes

---

Prerequisites

Before getting started, ensure you have:

• .NET 8 SDK
• An ASP.NET Core application
• Redis 7+ or PostgreSQL 16+

---

Choose a Storage Provider

CoreSystem.Idempotency requires a persistent storage provider to store request fingerprints and cached responses.

Currently supported providers:

• Redis
• PostgreSQL

Each provider has its own setup guide, configuration, and operational recommendations.

See Storage Providers for more information.

Step 1 — Install the Package

Install the NuGet package.

dotnet add package CoreSystem.Idempotency

Installing CoreSystem.Idempotency automatically installs the required CoreSystem packages through NuGet dependencies.

Step 2 — Configure the Framework

Configure the framework in your appsettings.json.

{
  "Core": {
    "Idempotency": {
      "Enabled": true,
      "Provider": "Redis"
    }
  }
}

Note

The configuration shown above contains only the minimum required settings. See Configuration for all available options.

---

Step 3 — Register the Framework

Register CoreSystem.Idempotency during application startup.

builder.Services.AddCoreIdempotency(options =>
{
    builder.Configuration
        .GetSection("Core:Idempotency")
        .Bind(options);
});

builder.Services.AddProblemDetails();

AddCoreIdempotency() registers the middleware, storage abstractions, request fingerprinting services, and all required dependencies in the ASP.NET Core dependency injection container.

Step 4 — Enable the Middleware

Configure the ASP.NET Core request pipeline.

var app = builder.Build();

app.UseExceptionHandler();

app.UseCoreIdempotency();

app.Run();

Warning

Register UseExceptionHandler() before UseCoreIdempotency() so that exceptions generated by the idempotency middleware are handled by ASP.NET Core's exception handling pipeline.

---

Step 5 — Send an Idempotent Request

Include an idempotency key in every request that should be executed only once.

POST /orders HTTP/1.1
X-Idempotency-Key: 8db99b84-6b57-41e3-ae66-98c4d4a2d9d5
Content-Type: application/json

{
  "productId": 1,
  "quantity": 2
}

If the same request is received again with the same idempotency key, the previously stored response is returned instead of executing the business operation again.