AutoNormalize.Abstractions 1.0.0-preview.1

This is a prerelease version of AutoNormalize.Abstractions.
There is a newer version of this package available.
See the version list below for details.
dotnet add package AutoNormalize.Abstractions --version 1.0.0-preview.1
                    
NuGet\Install-Package AutoNormalize.Abstractions -Version 1.0.0-preview.1
                    
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="AutoNormalize.Abstractions" Version="1.0.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="AutoNormalize.Abstractions" Version="1.0.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="AutoNormalize.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 AutoNormalize.Abstractions --version 1.0.0-preview.1
                    
#r "nuget: AutoNormalize.Abstractions, 1.0.0-preview.1"
                    
#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 AutoNormalize.Abstractions@1.0.0-preview.1
                    
#: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=AutoNormalize.Abstractions&version=1.0.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=AutoNormalize.Abstractions&version=1.0.0-preview.1&prerelease
                    
Install as a Cake Tool

<p align="center"> <img src="assets/branding/logo.svg" alt="DotNet.AutoNormalize Logo" width="580" /> </p>

<p align="center"> <strong>Consistent, configurable, safe-by-default input normalization for modern .NET applications.</strong> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License" /></a> <a href="https://dotnet.microsoft.com/"><img src="https://img.shields.io/badge/.NET-8.0%20%7C%209.0-purple.svg" alt="Supported Frameworks" /></a> <a href="docs/installation.md"><img src="https://img.shields.io/badge/NuGet-1.0.0--preview.1-004880.svg" alt="NuGet Preview" /></a> <a href="docs/benchmark-report.md"><img src="https://img.shields.io/badge/Clean%20String%20Allocation-0%20Bytes-success.svg" alt="Zero Allocation" /></a> </p>


1. Problem Statement

Across ASP.NET Core applications, developers repeatedly write boilerplate logic to canonicalize incoming text data:

  • Trimming leading and trailing whitespace from strings.
  • Converting empty or whitespace-only strings to null.
  • Canonicalizing Unicode character sequences into standard Unicode Normalization Form C.
  • Enforcing standardized casing rules across DTOs and database models.

When performed manually, normalization is scattered across controllers, validators, or repository layers. This leads to subtle defects:

  • Missing .Trim() calls causing duplicate database records (e.g. "user@example.com " vs "user@example.com").
  • Inadvertent mutilation of sensitive fields (such as passwords, tokens, API keys, or Base64 payloads) when naive global string converters are used.
  • Accidental mutation crashes on immutable C# positional records.
  • Unnecessary managed heap allocations on strings that were already clean.

2. Why DotNet.AutoNormalize Exists

DotNet.AutoNormalize provides representation canonicalization at application ingress and persistence boundaries. It integrates directly with:

  • System.Text.Json: Canonicalizes string tokens in-flight during deserialization, binding cleanly into immutable C# positional records before constructor invocation.
  • ASP.NET Core Minimal APIs & MVC: Normalizes JSON request bodies, query strings, route parameters, and form fields via unified dependency injection.
  • Entity Framework Core: Hooks SaveChanges() via an ISaveChangesInterceptor, canonicalizing Added and Modified entity states prior to database write while skipping unchanged entities.
       RAW INPUT                             CANONICAL OUTPUT
┌──────────────────────────┐          ┌──────────────────────────┐
│ Name:     "   Ada   "    │  ──────► │ Name:     "Ada"          │
│ Bio:      "     "        │          │ Bio:      null           │
│ Password: "  secret  "   │          │ Password: "  secret  "   │ (Shielded)
└──────────────────────────┘          └──────────────────────────┘

<p align="center"> <img src="docs/images/before-and-after.svg" alt="Before and After Normalization" width="850" /> </p>


3. Key Features

  • Zero-Allocation Fast Path: Clean strings that do not require trimming or Unicode re-encoding bypass allocation, completing in 4.83 nanoseconds with 0 bytes allocated.
  • Constructor-Time Record Normalization: Position records (public record User(string Name, string Email)) normalize during JSON deserialization without unsafe IL or reflection mutations.
  • Defense-in-Depth Sensitive Guard: Built-in heuristic shielding for sensitive property names (Password, Token, ApiKey, Secret, Signature, Hash, Salt).
  • Explicit Opt-Out Attributes: Declarative control via [PreserveWhitespace], [DoNotNormalize], and [NormalizeWith(typeof(T))].
  • Cycle-Safe Object Graphs: Traverses complex DTO hierarchies with circular reference tracking and configurable recursion limits.
  • Dictionary Safety: Dictionaries normalize string values only; dictionary keys are never mutated to avoid hash bucket corruption or collisions.

4. Supported Target Frameworks

Target Framework Implementation Tier Minimum SDK
.NET 9.0 (STS) Native multi-target 9.0.100+
.NET 8.0 (LTS) Native multi-target 8.0.100+
.NET Standard 2.0 DotNet.AutoNormalize.Abstractions Compatible with .NET Framework 4.6.2+ & .NET Core
.NET 10.0 Forward-compatible via NuGet asset resolution Compatible

5. Package Ecosystem & Installation

Install the specific package matching your architectural layer. See docs/installation.md for full package details.

# Core standalone engine
dotnet add package AutoNormalize.Core

# ASP.NET Core (Minimal APIs, MVC & System.Text.Json)
dotnet add package AutoNormalize.AspNetCore

# Entity Framework Core persistence interceptor
dotnet add package AutoNormalize.EntityFrameworkCore

6. Basic Usage (Standalone Engine)

using DotNet.AutoNormalize.Core;
using DotNet.AutoNormalize.Core.Engine;

var options = new AutoNormalizeOptions
{
    TrimStrings = true,
    EmptyStringsToNull = true,
    UnicodeNormalization = System.Text.NormalizationForm.FormC
};

IAutoNormalizer normalizer = new AutoNormalizer(options);

var user = new UserProfile
{
    DisplayName = "   Nikola Tesla   ",
    Bio = "      "
};

normalizer.Normalize(user);

// user.DisplayName == "Nikola Tesla"
// user.Bio == null

<p align="center"> <img src="docs/images/basic-normalization-flow.svg" alt="Basic Normalization Flow" width="850" /> </p>


7. ASP.NET Core Integration

In your Program.cs, call AddAutoNormalize() on builder.Services:

var builder = WebApplication.CreateBuilder(args);

// Configures Minimal APIs, MVC Model Binding, and System.Text.Json
builder.Services.AddAutoNormalize(options =>
{
    options.TrimStrings = true;
    options.EmptyStringsToNull = true;
    options.UnicodeNormalization = NormalizationForm.FormC;
});

var app = builder.Build();

// Positional records normalized at birth during JSON deserialization
app.MapPost("/api/users", (RegisterUserCommand command) =>
{
    return Results.Ok(command);
});

app.Run();

public record RegisterUserCommand(string FullName, string Email);

<p align="center"> <img src="docs/images/aspnetcore-integration-flow.svg" alt="ASP.NET Core Integration Flow" width="850" /> </p>


8. System.Text.Json Integration

When configuring standalone JsonSerializerOptions:

using System.Text.Json;
using DotNet.AutoNormalize.Json.Extensions;

var options = new JsonSerializerOptions().AddAutoNormalize(opt =>
{
    opt.TrimStrings = true;
    opt.EmptyStringsToNull = true;
});

string json = """{"Name": "   Grace Hopper   ", "Email": "   grace@navy.mil   "}""";
var customer = JsonSerializer.Deserialize<CustomerRecord>(json, options);

// customer.Name == "Grace Hopper"
// customer.Email == "grace@navy.mil"

<p align="center"> <img src="docs/images/json-deserialization-flow.svg" alt="JSON Deserialization Flow" width="850" /> </p>


9. Entity Framework Core Integration

Add the interceptor to your DbContext:

using Microsoft.EntityFrameworkCore;

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(connectionString)
           .AddAutoNormalize(opt =>
           {
               opt.TrimStrings = true;
               opt.EmptyStringsToNull = true;
           });
});

<p align="center"> <img src="docs/images/efcore-savechanges-flow.svg" alt="EF Core SaveChanges Flow" width="850" /> </p>


10. Attributes and Opt-Outs

Fine-tune normalization behavior on individual properties or classes:

using DotNet.AutoNormalize.Abstractions;

public class EmployeeRecord
{
    public string Name { get; set; } = string.Empty; // Normalized

    [PreserveWhitespace]
    public string FormattedCode { get; set; } = string.Empty; // Whitespace preserved

    [DoNotNormalize]
    public string RawHash { get; set; } = string.Empty; // Excluded completely

    public string Password { get; set; } = string.Empty; // Protected by sensitive name heuristic
}

11. Custom Normalizers

Implement IStringNormalizer to enforce domain-specific rules:

public class UppercasePostalCodeNormalizer : IStringNormalizer
{
    public string? Normalize(string? value, NormalizationContext context)
    {
        return value?.Trim().ToUpperInvariant();
    }
}

// Register globally in options:
options.AddNormalizer(new UppercasePostalCodeNormalizer());

// Or attach via attribute:
public class Address
{
    [NormalizeWith(typeof(UppercasePostalCodeNormalizer))]
    public string? PostalCode { get; set; }
}

12. Security Considerations

Normalization Boundary Rules

  1. Normalization IS NOT Validation: Normalization canonicalizes representation. It never asserts business rules, regex formats, or ranges. Use FluentValidation or DataAnnotations for validation.
  2. Normalization IS NOT Sanitization: Normalization does not strip HTML tags or escape script tags. Use dedicated sanitizers for HTML sanitization.
  3. Normalization IS NOT SQL Injection Defense: Always use parameterized queries for SQL injection protection.

Sensitive Field Protection

By default, properties matching the following names are shielded from trimming and modification: Password, Passcode, Token, AuthToken, AccessToken, RefreshToken, Secret, ClientSecret, SecretKey, ApiKey, PrivateKey, Signature, Hash, Salt, Passphrase, Certificate.


13. Audited Benchmarks

Tested via BenchmarkDotNet v0.14.0 on .NET 9.0 (RyuJIT AVX2, Windows 11):

Workload Method Mean Duration Managed Allocation
Clean String CleanString_AutoNormalize 4.83 ns 0 B (Zero Allocation)
Dirty String DirtyString_AutoNormalize 17.35 ns 112 B
Whitespace to Null WhitespaceOnly_AutoNormalize 12.49 ns 0 B
Decomposed Unicode DecomposedUnicode_AutoNormalize 136.37 ns 32 B
Typical DTO (6 props) TypicalDto_AutoNormalize 283.55 ns 912 B
JSON Deserialization Deserialize_AutoNormalize 601.90 ns 952 B
EF Core SaveChanges SaveChanges_WithAutoNormalize 22.23 µs 30.95 KB

All microbenchmarks use non-constant runtime inputs (string.Concat) to prevent RyuJIT constant-folding. See docs/benchmark-audit.md.


14. Known Limitations

  1. In-Memory Positional Records: Calling normalizer.Normalize(record) on an already-instantiated positional record cannot mutate properties post-construction. Full record normalization occurs during System.Text.Json deserialization.
  2. Dictionary Keys: Dictionaries normalize values only. Keys are never mutated to prevent hashcode invalidation or key collisions.
  3. Read-Only Collections: In-place normalization cannot mutate IReadOnlyList<T> elements and safely skips them.

15. Documentation Index


16. Contributing & Community

Contributions are welcome! Please review CONTRIBUTING.md and SECURITY.md before opening a pull request or submitting a report.


17. License

Distributed under the MIT License. Copyright © DotNet.AutoNormalize Contributors.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  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 is compatible.  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 was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on AutoNormalize.Abstractions:

Package Downloads
AutoNormalize.EntityFrameworkCore

Entity Framework Core SaveChanges interceptor and entity input normalization for DotNet.AutoNormalize.

AutoNormalize.Core

High-performance input normalization engine, built-in rules, metadata caching, and cycle-safe graph traversal for DotNet.AutoNormalize.

AutoNormalize.Json

System.Text.Json type contract modifiers and metadata-aware deserialization hooks for DotNet.AutoNormalize.

AutoNormalize.AspNetCore

Unified ASP.NET Core integration for DotNet.AutoNormalize: Minimal APIs, MVC Model Binding, and System.Text.Json configuration.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 50 11/21/2026
1.0.0-preview.2 51 11/21/2026
1.0.0-preview.1 52 11/21/2026