Webority.Retention.Abstractions 0.5.2

dotnet add package Webority.Retention.Abstractions --version 0.5.2
                    
NuGet\Install-Package Webority.Retention.Abstractions -Version 0.5.2
                    
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="Webority.Retention.Abstractions" Version="0.5.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Webority.Retention.Abstractions" Version="0.5.2" />
                    
Directory.Packages.props
<PackageReference Include="Webority.Retention.Abstractions" />
                    
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 Webority.Retention.Abstractions --version 0.5.2
                    
#r "nuget: Webority.Retention.Abstractions, 0.5.2"
                    
#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 Webority.Retention.Abstractions@0.5.2
                    
#: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=Webority.Retention.Abstractions&version=0.5.2
                    
Install as a Cake Addin
#tool nuget:?package=Webority.Retention.Abstractions&version=0.5.2
                    
Install as a Cake Tool

Webority.Retention

Runs every retention purge of a product. Register tables are trimmed by age: finished work rows in webhook intake, outboxes, idempotency records, side effects and job state. The tables and their rules come from the product's storage register, so the rules live in one place and a push check can verify them. Purges that need code (files, child rows, a clear) are classes the product or another package registers, and they join the same run.

Using it in a product

1. List the work tables in the register

.webority/data-placement.json names every table with a MAX column or that grows by appending. Entries of class workflow:<days> are trimmed:

{
  "schemaVersion": 1,
  "tables": [
    { "table": "dbo.InboundWebhookDelivery", "class": "workflow:30", "finishedAt": "ProcessedDateTimeUtc", "status": { "column": "Status", "finished": ["Processed", "Ignored"] } },
    { "table": "dbo.NotificationOutboxMessage", "class": "workflow:30", "finishedAt": "SentDateTimeUtc" },
    { "table": "dbo.SalesLead", "class": "record" }
  ]
}
Field Meaning
table schema.table, or the table alone for dbo
class workflow:<days> (1 to 3650) is trimmed; record, bounded-text, document-pointer, analytics and history:<years> are read and left alone
finishedAt The UTC time the row finished (datetime2, datetime or datetimeoffset); a row where it is null is never deleted
status Optional: column and the finished values. Pending and failed statuses are left out, so those rows are never deleted
hold Optional, workflow entries only: a bit column on the same table. A row where it is 1 is never deleted; null or 0 is not held. The run is refused when the column is missing or not bit
batchSize Optional: rows one delete statement removes from this table, 1 to 4000; the host's Retention:BatchSize when left out

A wrong entry, or one that names a missing table or column, fails the whole run before anything is deleted.

An entry or status object with a key the package does not list (table, class, finishedAt, status, hold, batchSize, reason, package; status takes column and finished) fails parsing, so a misspelled key never goes unnoticed.

Each table needs an unfiltered index whose first column is finishedAt (with status as its second column when the entry has one), because each run reads the oldest due rows first. A table without one fails the run before anything is deleted, and the message names the index to add.

2. Copy the register into the Functions output

<None Include="..\.webority\data-placement.json" Link="data-placement.json" CopyToOutputDirectory="PreserveNewest" />

3. Register and configure

services.AddWeborityRetention();
"Retention": {
  "RegisterPath": "data-placement.json",
  "ConnectionStringName": "WeborityDbConnection",
  "Brake": { "Mode": "DryRun" }
}
Setting Default Meaning
Retention:RegisterPath required The register; a relative path is read from the app's base directory
Retention:ConnectionStringName required Which ConnectionStrings:<name> to trim
Retention:BatchSize 2,000 Rows per delete statement (100 to 4,000, below SQL Server's lock escalation)
Retention:TimeBudget 4 minutes A run stops cleanly when it passes this; the next run carries on
Retention:CommandTimeoutSeconds 60 Per statement
Retention:DryRunOnly Empty Table or purge names held in dry run while the brake is Live; an unknown name refuses the run
Retention:Brake:Mode DryRun Live deletes; DryRun only logs what would go
Retention:Brake:MaxPerRun 50,000 Most rows one run takes from one table
Retention:Brake:MaxShareOfPopulation 1.0 No share limit: a quiet table can be entirely due

To add a new table or purge to a host in Live, add its name to Retention:DryRunOnly first, read its RetentionDryRun trace, then remove the name. No deploy is needed.

4. Call it from a timer

public sealed class RetentionFunction(RetentionRunner runner)
{
    [Function("Retention")]
    public Task RunAsync([TimerTrigger("0 15 * * * *")] TimerInfo timer, CancellationToken cancellationToken)
    {
        return runner.RunAsync(cancellationToken);
    }
}

RunAsync returns a RetentionRunReport, whose Results holds one RetentionResult per table and per purge, each with the outcome Removed, NothingDue, DryRun, Refused, OutOfTime or Failed. When the brake refuses a table or purge, or one fails, the others still run, and the run then throws RetentionRunFailedException so it shows as failed.

Add a purge

A purge that needs code implements IRetentionPurge and is registered beside the runner. The contract types live in Webority.Retention.Abstractions, a package with no dependencies, so a library implements a purge without referencing Webority.Retention; the product references Webority.Retention and registers the purge:

public sealed class SessionFilePurge(IFileStore files) : IRetentionPurge
{
    public string Name => "SessionFiles";

    public Task<RetentionPurgePlan> PlanAsync(RetentionPurgeContext context, CancellationToken cancellationToken) =>
        files.PlanExpiredAsync(context.NowDateTimeUtc, context.MaxPerRun, cancellationToken);

    public async Task<int> PurgeAsync(RetentionPurgeContext context, RetentionPurgePlan plan, CancellationToken cancellationToken)
    {
        var removed = 0;
        while (removed < plan.Due && !context.IsOutOfTime)
        {
            var batch = await files.DeleteExpiredBatchAsync(context.NowDateTimeUtc, Math.Min(500, plan.Due - removed), cancellationToken);
            if (batch == 0)
            {
                break;
            }
            removed += batch;
        }
        return removed;
    }
}
services.AddWeborityRetention();
services.AddWeborityRetentionPurge<SessionFilePurge>();
  • PlanAsync never changes data and is cheap when nothing is due.
  • PurgeAsync removes at most plan.Due and repeats its own due check, so a row that changed after planning stays. A purge that removes more than it planned is reported as Failed.
  • PurgeAsync stops when a batch removes nothing: the rows it planned may already be gone.
  • PurgeAsync stops between batches when context.IsOutOfTime is true.

How a run works

  1. Checks every register entry against the live schema, and refuses the whole run before anything is deleted when one does not match.
  2. Plans every table and purge.
  3. Starts with the oldest due table or purge, so a large backlog in one never keeps the others out of time.
  4. Checks each plan with the Webority.Jobs destructive-run guard (job Retention).
  5. In Live, removes in batches. Each delete repeats the due check, so a row that changed after it was planned stays. A row whose hold column is 1 is never planned or deleted.

Build, test, release

dotnet restore Webority.Retention.slnx
dotnet build Webority.Retention.slnx -c Release --no-restore -v q
dotnet test --solution Webority.Retention.slnx -c Release --no-build

The set release tool in package-publisher publishes this package; a merge to main publishes nothing.

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net11.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Webority.Retention.Abstractions:

Package Downloads
Webority.Retention

Deletes finished work rows from a product's SQL tables once they pass their retention window. The tables, their finished-time column and their finished statuses come from the product's storage register (.webority/data-placement.json); every column is checked against the live schema first, and every run is checked by the Webority.Jobs destructive-run guard. Purges that need code join the same run through IRetentionPurge.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.5.2 0 11/19/2026
0.5.1 0 11/19/2026
0.5.0 0 11/19/2026