Bsft.Idempotency 2.2.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Bsft.Idempotency --version 2.2.0
                    


                    

                
NuGet\Install-Package Bsft.Idempotency -Version 2.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Bsft.Idempotency" Version="2.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Bsft.Idempotency" Version="2.2.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Bsft.Idempotency" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Bsft.Idempotency --version 2.2.0
                    


                    

                
#r "nuget: Bsft.Idempotency, 2.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Bsft.Idempotency@2.2.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Bsft.Idempotency&version=2.2.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Bsft.Idempotency&version=2.2.0
                    


                            Install as a Cake Tool

Bsft.Idempotency

Makes an unsafe HTTP endpoint safe to retry: a client sends an Idempotency-Key, and a repeat of that request replays the first response instead of running again.

Install

dotnet add package Bsft.Idempotency

Requires Bsft.Core, Bsft.Http, Bsft.Data and Bsft.Instrumentation (pulled transitively) and ASP.NET Core. Bsft.Idempotency.EFCore is the shared record store a host running more than one replica needs.

Register

services.AddBsftIdempotency(options =>
{
    options.ShouldRequireKey = true;
    options.Retention = TimeSpan.FromHours(24);
});

// or bound from configuration, section "Bsft:Idempotency"
services.AddBsftIdempotency(configuration);

The pipeline half is a second call, and its position matters: app.UseBsftIdempotency() goes after UseBsftDefaults(), after UseRouting() and after authentication. Then opt an endpoint in with [Idempotent] on a controller action or .RequireIdempotency() on a minimal-API route group.

Configure

Option Default Effect
BsftIdempotencyOptions.HeaderName Idempotency-Key The request header the key is read from.
BsftIdempotencyOptions.Methods POST Which methods the middleware considers.
BsftIdempotencyOptions.ShouldRequireKey false When true, an opted-in endpoint without a key answers 428.
BsftIdempotencyOptions.Retention 24 h How long a stored response is replayed.
BsftIdempotencyOptions.InProgressTimeout 60 s After which an unfinished reservation is retryable.
BsftIdempotencyOptions.InProgressRetryAfter 1 s The Retry-After on the in-progress 409, capped by the lease.
BsftIdempotencyOptions.MaxBodyBytes 1 MiB Above which the request is refused with 413 rather than left unprotected.
BsftIdempotencyOptions.MaxResponseBytes 1 MiB Above which the response is sent but not stored, so the key runs again.
BsftIdempotencyOptions.MaxKeyLength 255 Longest key accepted; at most 512, the shared store's column.
BsftIdempotencyOptions.CachedResponseHeaders Location, Content-Type The allowlist replayed with the body.
BsftIdempotencyOptions.NonReplayableStatusCodes 401, 403, 408, 429 Client errors that run again instead of being replayed.
BsftIdempotencyOptions.Mode Detached Detached or Enlisted; see the guarantee table on the topic page.

Validation: ValidateOnStart rejects a blank header name, an empty method list, a non-positive window, a MaxKeyLength outside 1–512, and an InProgressTimeout longer than Retention — the last one because a reservation that outlived the replay window would be pruned while it was still refusing concurrent requests.

Extend

  • IIdempotencyStore — where records live. The default is in-process and is not enough for two replicas; Bsft.Idempotency.EFCore replaces it with a shared table.
  • IIdempotencyFingerprintContributor — adds or removes a segment of the request fingerprint.
  • IIdempotencyAuditSink — receives replay, key-reuse and in-progress decisions. The default discards them.

Documentation

Topic page: docs/idempotency.md. Conventions: docs/package-conventions.md.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Bsft.Idempotency:

Package Downloads
Bsft.Idempotency.EFCore

BSFT Framework EF Core persistence for idempotency records: the shared store behind Idempotency-Key replay, its unique index and the sweeper

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.2.0 150 10/23/2026
2.1.0 123 9/28/2026