⚙️ Configuration

This guide describes every configuration option available in CoreSystem.Idempotency.

You'll learn how to configure:

• Framework behavior
• Request fingerprinting
• Supported HTTP methods
• Response expiration
• Instance naming
• appsettings.json integration

Note

Storage providers are configured independently. See the provider-specific documentation for Redis and PostgreSQL configuration.

---

Configuration Overview

Configure the framework using the AddCoreIdempotency() extension.

builder.Services.AddCoreIdempotency(options =>
{
    // Configure the framework here
});

The framework can also be configured using appsettings.json.

---

Configuration Options

Option	Description	Default
Enabled	Enables or disables the middleware	true
InstanceName	Optional prefix used by storage providers	null
Expiration	Lifetime of persisted responses	30 minutes
AllowedMethods	HTTP methods protected by the middleware	POST, PUT
Fingerprint	Request fingerprint generation options	Default configuration

---

Enable or Disable the Framework

Enable the middleware.

options.Enabled = true;

Disable the middleware without removing it from the dependency injection container.

options.Enabled = false;

---

Instance Name

InstanceName allows multiple applications or environments to safely share the same storage infrastructure.

Storage providers may use this value to prefix persisted keys and avoid collisions.

options.InstanceName = "Orders";

Typical examples include:

• Production
• Staging
• Development
• Multi-tenant applications

---

Allowed HTTP Methods

By default, the middleware protects:

• POST
• PUT

Add additional methods:

options.AddAllowedMethods(
    "PATCH",
    "DELETE");

Remove methods:

options.RemoveAllowedMethods(
    "PUT");

Requests using methods that are not configured bypass the middleware.

---

Response Expiration

Configure how long an idempotent response remains available for replay.

options.Expiration =
    TimeSpan.FromHours(24);

After the expiration period, the request is treated as a new operation.

---

Request Fingerprinting

Fingerprinting prevents an idempotency key from being reused with a different request.

Example:

options.Fingerprint.IncludedHeaders.Add("X-Tenant-Id");

options.Fingerprint.IncludedHeaders.Add("X-Region");

Additional options are also available.

options.Fingerprint.IncludeQueryString = true;

options.Fingerprint.IncludeContentType = true;

See Fingerprinting for a complete description of every available option.

---

Using appsettings.json

{
  "Core": {
    "Idempotency": {
      "Enabled": true,
      "InstanceName": "Orders",
      "Expiration": "1.00:00:00",
      "AllowedMethods": [
        "POST",
        "PUT"
      ],
      "Fingerprint": {
        "Enabled": true,
        "IncludeQueryString": true,
        "IncludeContentType": true,
        "IncludedHeaders": [
          "X-Tenant-Id",
          "X-Region"
        ]
      }
    }
  }
}

Bind the configuration.

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

Note

Storage provider configuration is performed separately. See the Redis or PostgreSQL provider documentation for provider-specific settings.

---

Storage Provider Configuration

CoreSystem.Idempotency does not configure storage providers.

After registering the framework, configure the provider package independently.

Example:

builder.Services
    .AddCoreIdempotency(options =>
    {
        options.InstanceName = "Orders";
    })
    .AddCoreIdempotencyRedis(options =>
    {
        // Redis configuration
    });

or

builder.Services
    .AddCoreIdempotency(options =>
    {
        options.InstanceName = "Orders";
    })
    .AddCoreIdempotencyPostgreSql(options =>
    {
        // PostgreSQL configuration
    });

---

Recommended Configurations

Development

Setting	Value
Instance Name	Development
Expiration	15 minutes
Fingerprint	Default

---

Production

Setting	Value
Instance Name	Application name
Expiration	24 hours
Fingerprint	Default + business headers

---

Best Practices

• Configure an InstanceName when multiple applications share the same storage.
• Use UUIDs for idempotency keys.
• Configure expiration according to your business requirements.
• Protect only operations that modify application state.
• Never reuse an idempotency key for different requests.
• Include only stable headers when customizing request fingerprinting.