Transformations.Dapper 3.0.0

Transformations.Dapper

Resilient Dapper query wrappers with built-in transient SQL fault detection — drop-in replacements for standard Dapper methods that automatically retry on deadlocks, timeouts, and Azure SQL throttling.

📖 Overview

Transformations.Dapper brings the hardened retry semantics of Transformations.Core directly into your Dapper workflows. Cloud databases regularly drop connections or trigger transient deadlocks — this library automatically identifies retriable SQL error codes and re-executes queries transparently.

🚀 Why Transformations.Dapper?

Instead of manually catching SqlException and writing retry loops everywhere, you swap connection.QueryAsync for connection.QueryWithRetryAsync. The built-in transient fault detector handles the backoff strategy. The result is database code that's both cleaner and more resilient — with no extra ceremony.

📦 Install

<PackageReference Include="Transformations.Dapper" Version="3.0.0.0" />

💡 What's Included

Resilient Async Queries

Swap connection.QueryAsync for connection.QueryWithRetryAsync. Transient SQL faults are detected automatically and retried with exponential backoff.

// 3 retries, 500ms initial delay — doubles each attempt
var users = await connection.QueryWithRetryAsync<User>(
    "SELECT * FROM Users WHERE Status = @Status",
    new { Status = UserStatus.Active },
    retryCount: 3,
    initialDelay: TimeSpan.FromMilliseconds(500));

// Single row — returns null rather than throwing on no result
var user = await connection.QuerySingleOrDefaultWithRetryAsync<User>(
    "SELECT * FROM Users WHERE Id = @Id",
    new { Id = userId });

// Execute (INSERT/UPDATE/DELETE) and scalar
int affected = await connection.ExecuteWithRetryAsync(
    "DELETE FROM Sessions WHERE ExpiredAt < @Now", new { Now = DateTime.UtcNow });

int count = await connection.ExecuteScalarWithRetryAsync<int>(
    "SELECT COUNT(*) FROM Users WHERE Active = 1");

Transient Fault Detection

SqlTransientFaultDetector.IsTransient classifies SQL Server errors that are safe to retry, and TimeoutException. It lives in the Transformations.Sql package, which this package depends on, so import that namespace. The SQL Server error numbers are:

GetTransientErrorNumbers() returns the same set. A test pins that set, so changing the codes means updating the test and this table together. SQLite and other providers have no entries here, so their busy errors are not retried by these wrappers. Use it in your own catch blocks:

using Transformations.Sql;

catch (SqlException ex) when (SqlTransientFaultDetector.IsTransient(ex))
{
    logger.LogWarning(ex, "Transient SQL fault on attempt {Attempt}", attempt);
}

Migrating from Transformations.Dapper.SqlTransientFaultDetector

Earlier 3.x releases had the detector in this package's namespace. It is now [Obsolete] and forwards to Transformations.Sql.SqlTransientFaultDetector. The compiler reports CS0618 with that replacement. The forwarder will be removed in the next major version.

Change the using and keep the calls as they are:

// Before
using Transformations.Dapper;

// After
using Transformations.Sql;

If your file also imports Transformations.Dapper for the extension methods, the unqualified name is ambiguous (CS0104). Qualify the call instead:

catch (SqlException ex) when (Transformations.Sql.SqlTransientFaultDetector.IsTransient(ex))

SqlParameter Bridge

Converts anonymous or POCO objects to SqlParameter[] — useful when bridging legacy SqlCommand code or when you need explicit SqlDbType control that Dapper's anonymous parameters don't offer.

// From an anonymous object
IReadOnlyList<SqlParameter> sqlParams = SqlParameterBridge.ToSqlParameters(
    new { UserId = 42, Name = "Alice" });

// With explicit SqlDbType overrides
IReadOnlyList<SqlParameter> sqlParams = SqlParameterBridge.ToSqlParameters(
    new { UserId = 42, Bio = longText },
    new Dictionary<string, SqlDbType>
    {
        ["Bio"] = SqlDbType.NVarChar
    });

// NativeAOT / trimmer-safe generic overload
IReadOnlyList<SqlParameter> sqlParams = SqlParameterBridge.ToSqlParameters<MyParams>(myParams);

🛠 API Reference

📦 Dependencies

• Transformations.Core
• Dapper
• Microsoft.Data.SqlClient

License

PolyForm Strict 1.0.0 — Copyright © 2026 opentail.net