Transformations 2.0.2

Transformations

Transformations is a .NET extension method library designed to reduce boilerplate across your projects. It provides safe type conversions, context-aware string manipulation, and resilient data access through clean one-liners on the types you already use.

Initially developed to handle the edge cases of tricky automapping conversions, the library has since expanded into a comprehensive utility suite for strings, collections, date arithmetic, and database resilience.

Built by opentail.net — Dmitri Rechetilov

Why This Exists

Every .NET project ends up writing the same utility code. Safe type conversion with fallbacks. String truncation that doesn't break HTML entities. Date arithmetic that handles edge cases. Retry loops with backoff. Pluralization. CSV export. DataRow extraction that doesn't throw on DBNull.

This library is that code — battle-tested, documented, and shipped as a single using Transformations; import.

Modular Packages

You can install the full library or pick specific slices to keep your dependency graph lean.

Core Capabilities

Safe Type Conversion

Moves between types with explicit fallbacks rather than throwing exceptions.

C#
string input = "42";
int value = input.ConvertTo<int>(); // 42
int safe = "nope".ConvertTo<int>(-1); // -1
bool active = "yes".ConvertTo<bool>(); // Handles common truthy strings

Context-Aware Strings

Handles text based on its structure, such as HTML or grammatical rules.

C#
// HTML-aware truncation that respects tags and entities
string html = "<div>Hello <b>World</b></div>";
var teaser = html.TruncateSemantic(10); // "<div>Hello...</div>"

// Pluralization for irregular nouns
"child".Pluralize(3); // "children"
"person".Pluralize(5); // "people"

// Strips scripts and unsafe tags
var clean = rawHtml.SanitizeHtml(HtmlSanitizationPolicy.PermitLinks);

Infrastructure Resilience

Built-in logic for transient SQL fault detection and exponential backoff.

C#
// Simple retry with exponential backoff
int result = Resilience.Retry(() => CallService(), retryCount: 3);

// SQL transient fault detection for deadlocks and timeouts
catch (SqlException ex) when (SqlTransientFaultDetector.IsTransient(ex)) {
// Safely retry or log
}

Compile-Time Mapping (Transformations.Mapping)

The library’s original core, this module uses C# Source Generators to create mapping code at compile time. This avoids the runtime performance cost of reflection and ensures type safety during the build.

C#
[MapTo<UserDto>]
public partial class User
{
public int Id { get; set; }
public string Name { get; set; }

\[IgnoreMap\]  
public string InternalToken { get; set; }  

}

// Usage: user.ToUserDto() is generated at compile time

Install

Pick what you need:

Core has zero ASP.NET Core dependency. If you're building a console app, background service, or library — use Core and keep your dependency graph lean.

<PackageReference Include="Transformations" Version="2.0.0" />


<PackageReference Include="Transformations.Core" Version="2.0.0" />
<PackageReference Include="Transformations.Data" Version="2.0.0" />
<PackageReference Include="Transformations.Web" Version="2.0.0" />
<PackageReference Include="Transformations.Dapper" Version="2.0.0" />
<PackageReference Include="Transformations.EntityFramework" Version="2.0.0" />
<PackageReference Include="Transformations.Mapping" Version="2.0.0" />

Quick Start

using Transformations;

// Type conversion — safe, with fallbacks
string input = "42";
int value = input.ConvertTo<int>();          // 42
int safe  = "nope".ConvertTo<int>(-1);       // -1

// String helpers
"Hello World".GetInitials();                 // "HW"
"test".Repeat(3);                            // "testtesttest"
"<b>Hello</b>".StripHtml();                  // "Hello"

// Pluralization (regex-based, handles irregulars)
"child".Pluralize(3);                        // "children"
"person".Pluralize(5);                       // "people"
"Box".Pluralize(2);                          // "Boxes"
"item".Pluralize(1);                         // "item"

// Range checks
5.IsBetween(1, 10);                          // true

// Enum utilities
MyEnum.Value.GetEnumDescription2();          // reads [Description] attribute
"Active".ToEnum<Status>();                   // parses string to enum

// Date helpers
DateTime.Now.IsWeekend();                    // true/false
2024.GetEasterSunday();                      // Easter date calculation

// Semantic compare
"+1 (555) 111-2222".IsSemanticMatch("15551112222", SemanticType.PhoneNumber); // true

// Diagnostics (chainable trace — zero-cost when disabled)
var userId = 42.Trace("resolved user id");

// Resilience (sync retry with exponential backoff)
int result = Resilience.Retry(() => int.Parse("42"), retryCount: 3,
    initialDelay: TimeSpan.FromMilliseconds(50));

What's In The Box

Core Type Conversion

Every numeric type, bool, char, string, DateTime, Guid — covered with both ConvertTo<T> and TryConvertTo<T> overloads, plus nullable variants with explicit defaults.

Strings

HTML Sanitization

string safe = rawHtml.SanitizeHtml(HtmlSanitizationPolicy.PermitLinks);
string preview = rawHtml.TruncateSemantic(140, countHtmlTags: false);

Three policies: StripAll, PermitInlineFormatting (b/i/u/em/strong), PermitLinks (+ safe anchor tags). Script blocks, on* event attributes, and javascript: hrefs are always stripped.

See Sanitation.md for the technical deep dive.

Date & Time

TimeSpanHelper output formats:

Collections

Batch Processing

// Convert a mixed array with a fallback for failures
var converted = BatchTransformations.BatchConvert(
    new object?[] { "1", "bad", 3 }, defaultValue: -1).ToList();

// In-place HTML stripping on a span — zero allocation
string?[] lines = { "<b>alpha</b>", "<i>beta</i>" };
BatchTransformations.BatchTransformInPlace(lines.AsSpan(),
    BatchTransformations.BatchStringTransformation.StripHtml);

See Batching.md for the performance deep dive.

File & Directory

Diagnostics & Resilience

Semantic & Delta Utilities

Data Access (Transformations.Data)

Dapper Resilience (Transformations.Dapper)

// Retry-wrapped query — 3 retries with 200ms exponential backoff
var users = await connection.QueryWithRetryAsync<User>(
    "SELECT * FROM Users WHERE Active = @Active",
    new { Active = true });

// Check if a caught exception is transient
catch (SqlException ex) when (SqlTransientFaultDetector.IsTransient(ex))
{
    logger.LogWarning(ex, "Transient SQL fault, will retry");
}

EF Core (Transformations.EntityFramework)

// Resilient save with retry
int saved = await context.SaveChangesWithRetryAsync();

// Capture audit entries before save
var audit = context.GetAuditEntries(EntityState.Modified);
await context.SaveChangesWithRetryAsync();
foreach (var entry in audit)
    logger.LogInformation("{Entity}.{Prop}: {Old} → {New}",
        entry.EntityType, entry.PropertyName, entry.OriginalValue, entry.CurrentValue);

// Export query results to CSV
string csv = await context.Users.Select(u => u.Name).ToCsvAsync();

Zero-Reflection Mapper (Transformations.Mapping)

Zero reflection. NativeAOT safe. Compile-time validated. Type mismatches are resolved automatically via ConvertTo<T>.

Generated mapper diagnostics:

• TXMAP001 warns when a target member is not mapped from source.
• Opt-in error mode:

<PropertyGroup>
  <TransformationsMappingUnmappedMembersAsErrors>true</TransformationsMappingUnmappedMembersAsErrors>
</PropertyGroup>

[MapTo<UserDto>]
public partial class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime Birthday { get; set; }  // auto-converted to string via .ToString()

    [IgnoreMap]
    public string PasswordHash { get; set; }
}

// Generated at compile time — no reflection, no runtime cost:
UserDto dto = user.ToUserDto();
User back = User.FromUserDto(dto);

ASP.NET Core / Web (Transformations.Web)

Building

dotnet build
dotnet test

Prerequisites: .NET 8, 9, or 10 SDK

Project Structure

├── Transformations/                     # Monolith (all-in-one package)
│   ├── BasicTypeConverter.cs            # Safe generic type conversion
│   ├── StringHelper.cs                  # Core string extensions
│   ├── AdditionalStringHelper.cs        # HTML sanitization, pluralization, encoding
│   ├── CollectionConvertor.cs           # Bulk collection conversion
│   ├── CollectionHelper.cs              # List/collection utilities
│   ├── BatchTransformations.cs          # Low-allocation batch conversion/transform
│   ├── DateHelper.cs                    # Date arithmetic, IsToday, CalculateAge
│   ├── TimeSpanHelper.cs               # Readable time string formatting
│   ├── StopwatchHelper.cs              # Stopwatch elapsed extraction
│   ├── HolidayHelper.cs                # UK & US public holiday calculations
│   ├── ArrayHelper.cs                   # BlockCopy, CombineArrays, PrependItem
│   ├── BitConvertor.cs                  # Byte/primitive round-trip conversion
│   ├── FileInfoHelper.cs               # File rename, copy, delete
│   ├── DirectoryInfoHelper.cs          # Directory copy, recursive file search
│   ├── StreamHelper.cs                  # Stream read/write/copy
│   ├── StreamExtensions.cs             # Line iteration and copy progress
│   ├── CsvHelper.cs                     # CSV generation from collections/DataTable
│   ├── DataRowConverter.cs              # Safe DataRow value access
│   ├── DataReaderHelper.cs              # IDataReader extensions
│   ├── SqlHelper.cs                     # SqlParameter builder
│   ├── ConfigurationHelper.cs          # IConfiguration extensions
│   ├── QueryStringHelper.cs            # Query string utilities
│   ├── SessionHelper.cs                # Session state extensions
│   ├── CookieHelper.cs                 # Cookie management
│   ├── WebHelper.cs                     # HTTP redirect/status helpers
│   ├── ResponseHelper.cs               # Response extensions
│   ├── Inspect.cs                       # Type validation (IsNumeric, IsDate, etc.)
│   ├── Helper.cs                        # IsNull, IsNotNull, ComputeHash
│   ├── DiagnosticsProbe.cs             # Process + lightweight GPU/VRAM metrics
│   ├── DiagnosticExtensions.cs         # Chainable trace helper
│   ├── Resilience.cs                    # Sync retry with exponential backoff
│   ├── SemanticStringComparer.cs       # Intent-based string comparisons
│   ├── ObjectDelta.cs                   # Shallow object diff + SkipDelta
│   ├── MeasurementExtensions.cs        # Size/time compact formatting
│   ├── WebAndFileExtensions.cs         # URL segment + local path helpers
│   ├── EnumHelper.cs                    # Enum description/parse extensions
│   ├── ComparableHelper.cs             # Range/between checks
│   ├── ExtensionHelper.cs              # Clamped index helpers
│   ├── RegExHelper.cs                   # Regex match/split wrappers
│   ├── MiscHelper.cs                    # Miscellaneous utilities
│   └── Transform.cs                     # Shared enumerations
│
├── Transformations.Core/               # Core-only package (no ASP.NET Core)
├── Transformations.Data/               # Data package (Core + DataRow/SQL)
├── Transformations.Web/                # Web package (Core + ASP.NET Core)
│   └── SelectListExtensions.cs         # DataTable → SelectListItem
│
├── Transformations.Dapper/             # Dapper package (Core + Dapper + SqlClient)
│   ├── DapperResilienceExtensions.cs   # Retry-wrapped Query/Execute
│   ├── SqlTransientFaultDetector.cs    # Transient SQL error classification
│   └── SqlParameterBridge.cs           # Anonymous object → SqlParameter[]
│
├── Transformations.EntityFramework/    # EF Core package (Core + EF Core)
│   ├── DbContextResilienceExtensions.cs # SaveChangesWithRetryAsync
│   ├── ChangeTrackerAuditExtensions.cs  # ChangeTracker → AuditEntry[]
│   └── QueryableCsvExtensions.cs        # IQueryable → CSV
│
├── Transformations.Mapping/            # Zero-reflection mapper (Core + source generator)
│   └── Attributes.cs                   # [MapTo<T>], [IgnoreMap], [MapProperty]
│
├── Transformations.Mapping.Generator/  # Incremental source generator (netstandard2.0)
│   └── MappingGenerator.cs             # Emits To{Target}() and From{Target}() methods
│
├── Transformations.Analyzers/          # Roslyn analyzer (netstandard2.0)
│   ├── DeprecatedApiAnalyzer.cs        # TX0001 diagnostic
│   └── DeprecatedApiCodeFixProvider.cs # Lightbulb rename fix
│
├── Transformations.Tests/              # NUnit test project (90+ test files)
├── Transformations.Dapper.Tests/       # Dapper package tests
├── Transformations.EntityFramework.Tests/ # EF Core package tests
├── Transformations.Mapping.Tests/      # Mapper tests (verifies generated code)
├── Transformations.Analyzers.Tests/    # Analyzer tests
│
├── COOKBOOK.md                           # Problem-first recipes
├── Batching.md                          # Performance deep dive
├── Sanitation.md                        # HTML sanitization deep dive
├── DEPRECATION_POLICY.md               # Versioned API deprecation plan
└── README.md

API Migration Guidance (2.x)

Legacy APIs are retained with [Obsolete] markers and explicit replacements:

Deprecation timeline:

See DEPRECATION_POLICY.md for full details.

Dependencies

Transformations.Core and Transformations.Data have no ASP.NET Core dependency.

CI Quality Gates

GitHub Actions workflow: .github/workflows/ci-quality-gates.yml

• Build + test on .NET 10
• Line/branch coverage thresholds from Cobertura report
• Public-method test policy for critical modules (BasicTypeConverter, CollectionConvertor, HolidayHelper)
• XML documentation artifact publication

Further Reading

• COOKBOOK.md — Problem-first recipes: "How do I safely convert untrusted input?", "How do I strip scripts from HTML?", etc.
• Batching.md — Performance deep dive on ArrayHelper and BatchTransformations
• Sanitation.md — Technical deep dive on the HTML sanitization policy engine
• DEPRECATION_POLICY.md — Versioned API deprecation timeline

License

MIT — Copyright © 2026 opentail.net

Built for .NET professionals by opentail.net