DynamoDBv2.Transactions 4.0.14.104

DynamoDBv2.Transactions

A high-performance .NET library for Amazon DynamoDB transactions with compile-time source generation — up to 60x faster than reflection-based mapping with 32% fewer allocations.

<p align="center">

</p>

<p align="center">

</p>

<p align="center">

</p>

Why This Library Instead of the Standard AWS SDK?

The standard AWS SDK DynamoDBContext has fundamental design limitations for transactions:

Performance: This Library vs Standard SDK

<table> <tr> <td width="50%">

End-to-End Transactions (with network I/O)

The gap grows with more items because the standard SDK issues separate DescribeTable + write calls per item, while this library batches everything into a single TransactWriteItems request.

</td> <td width="50%">

Mapper: Source-Generated vs Reflection Fallback

</td> </tr> </table>

Zero-allocation key lookups via compile-time switch expressions. Inline AttributeValue construction for primitives — no virtual dispatch, no boxing. Just add partial to your entity class.

Installation

dotnet add package DynamoDBv2.Transactions

The package includes the source generator automatically — no additional packages required.

Quick Start

1. Define Your Entity

Add partial and standard DynamoDB attributes. The source generator handles everything at compile time:

[DynamoDBTable("Orders")]
public partial class Order : ITransactional
{
    [DynamoDBHashKey("PK")]
    public string OrderId { get; set; }

    [DynamoDBProperty("CustomerName")]
    public string CustomerName { get; set; }

    [DynamoDBProperty("Total")]
    public decimal Total { get; set; }

    [DynamoDBProperty("Status")]
    public string Status { get; set; }

    [DynamoDBVersion]
    public long? Version { get; set; }
}

2. Write a Transaction

Transactions execute atomically on DisposeAsync — if any operation fails, they all roll back:

var client = new AmazonDynamoDBClient();

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.CreateOrUpdate(new Order
    {
        OrderId = "ORD-001",
        CustomerName = "Alice",
        Total = 99.99m,
        Status = "Confirmed"
    });
}

That's it. The source generator wires up all mapping at compile time, the transaction executes on dispose.

How It Works

Your Code                    Compile Time                     Runtime
   |                              |                              |
   v                              v                              v
[DynamoDBTable("Orders")]    Source Generator            DynamoDbTransactor
public partial class Order   generates switch-expr       batches operations
   |                         mappings (zero alloc)            |
   v                              |                           v
[DynamoDBHashKey("PK")]      [ModuleInitializer]        TransactWriteItems
public string OrderId        auto-registers at              (single call)
                             app startup

Two mapping strategies, one API:

Both strategies are transparent — the same DynamoDbTransactor API works with either. The source generator is automatically discovered at startup via [ModuleInitializer].

Features

When to Use This Library vs the Standard SDK

Code Comparison: This Library vs Standard SDK

<table> <tr> <th>DynamoDBv2.Transactions</th> <th>Standard AWS SDK</th> </tr> <tr> <td>

// Atomic: create order + update inventory
await using var tx = new DynamoDbTransactor(client);

tx.CreateOrUpdate(new Order
{
    OrderId = "ORD-001",
    Total = 99.99m,
    Version = null // auto-managed
});

tx.ConditionGreaterThan<Inventory, int>(
    "SKU-100", i => i.Quantity, 0);

tx.PatchAsync<Inventory, int>(
    "SKU-100", i => i.Quantity, newQty);
// executes on DisposeAsync

</td> <td>

// Manual: build request by hand
var request = new TransactWriteItemsRequest
{
    TransactItems = new List<TransactWriteItem>
    {
        new() { Put = new Put {
            TableName = "Orders",
            Item = new Dictionary<string, AttributeValue>
            {
                ["PK"] = new() { S = "ORD-001" },
                ["Total"] = new() { N = "99.99" },
                // manual version logic...
            }
        }},
        new() { ConditionCheck = new ConditionCheck {
            TableName = "Inventory",
            Key = new() { ["PK"] = new() { S = "SKU-100" } },
            ConditionExpression = "#qty > :zero",
            ExpressionAttributeNames = new() { ["#qty"] = "Quantity" },
            ExpressionAttributeValues = new() { [":zero"] = new() { N = "0" } }
        }},
        new() { Update = new Update {
            TableName = "Inventory",
            Key = new() { ["PK"] = new() { S = "SKU-100" } },
            UpdateExpression = "SET #qty = :val",
            ExpressionAttributeNames = new() { ["#qty"] = "Quantity" },
            ExpressionAttributeValues = new() { [":val"] = new() { N = newQty.ToString() } }
        }}
    }
};
await client.TransactWriteItemsAsync(request);

</td> </tr> </table>

Usage Examples

Create or Update

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.CreateOrUpdate(new Order
    {
        OrderId = "ORD-001",
        CustomerName = "Alice",
        Total = 149.99m,
        Status = "Confirmed"
    });
}
// Transaction executes atomically on DisposeAsync

Delete

// Delete by hash key (attribute name inferred from [DynamoDBHashKey])
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.DeleteAsync<Order>("ORD-001");
}

// Delete with explicit key name
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.DeleteAsync<Order>("PK", "ORD-001");
}

// Delete with expression (type-safe)
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.DeleteAsync<Order, string>(o => o.OrderId, "ORD-001");
}

Patch a Single Property

Update one field without touching the rest of the item:

// Expression-based (type-safe)
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.PatchAsync<Order, string>("ORD-001", o => o.Status, "Shipped");
}

// Instance-based (patch from an existing object)
await using (var transactor = new DynamoDbTransactor(client))
{
    order.Status = "Shipped";
    transactor.PatchAsync(order, nameof(order.Status));
}

Conditional Checks

Assert conditions before writing — the entire transaction rolls back if any check fails:

await using (var transactor = new DynamoDbTransactor(client))
{
    // Only update if the order total is above the threshold
    transactor.ConditionGreaterThan<Order, decimal>("ORD-001", o => o.Total, 50.0m);
    transactor.PatchAsync<Order, string>("ORD-001", o => o.Status, "Priority");
}

Available condition methods:

• ConditionEquals<TModel, TValue> — field must equal value
• ConditionNotEquals<TModel, TValue> — field must not equal value
• ConditionGreaterThan<TModel, TValue> — field must be greater than value
• ConditionLessThan<TModel, TValue> — field must be less than value
• ConditionVersionEquals<TModel> — optimistic concurrency version check

Optimistic Concurrency (Versioning)

Implement ITransactional to get automatic version management:

[DynamoDBTable("Orders")]
public partial class Order : ITransactional
{
    [DynamoDBHashKey("PK")]
    public string OrderId { get; set; }

    [DynamoDBVersion]
    public long? Version { get; set; }  // Auto-incremented on every write
}

// First write: Version is set to 0
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.CreateOrUpdate(new Order { OrderId = "ORD-001" });
}

// Second write: Version auto-increments to 1, with a condition check
// that the current version in DynamoDB matches the expected version.
// If another writer modified the item, this transaction fails.
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.CreateOrUpdate(existingOrder);  // Version check is automatic
}

// Explicit version check
await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.ConditionVersionEquals<Order>("ORD-001", o => o.Version, 1);
    transactor.PatchAsync<Order, string>("ORD-001", o => o.Status, "Completed");
}

Complex Multi-Operation Transaction

Combine multiple operations in a single atomic transaction (up to 100 items):

await using (var transactor = new DynamoDbTransactor(client))
{
    // Check: inventory must be sufficient
    transactor.ConditionGreaterThan<Inventory, int>(
        "SKU-100", i => i.Quantity, 0);

    // Create the order
    transactor.CreateOrUpdate(new Order
    {
        OrderId = "ORD-042",
        CustomerName = "Bob",
        Total = 299.99m,
        Status = "Confirmed"
    });

    // Update inventory count
    transactor.PatchAsync<Inventory, int>(
        "SKU-100", i => i.Quantity, currentQuantity - 1);

    // Log the transaction
    transactor.CreateOrUpdate(new AuditLog
    {
        LogId = Guid.NewGuid().ToString(),
        Action = "OrderCreated",
        Timestamp = DateTime.UtcNow
    });
}
// All 4 operations succeed or fail together

Transaction Options

Configure idempotency and capacity tracking:

await using (var transactor = new DynamoDbTransactor(client))
{
    transactor.Options = new TransactionOptions
    {
        // Idempotency token — retrying with the same token within 10 minutes
        // returns the original result instead of executing again
        ClientRequestToken = "order-042-confirm-v1",

        // Track consumed read/write capacity units
        ReturnConsumedCapacity = ReturnConsumedCapacity.TOTAL,

        // Track item collection metrics (useful for tables with LSIs)
        ReturnItemCollectionMetrics = ReturnItemCollectionMetrics.SIZE
    };

    transactor.CreateOrUpdate(order);
    transactor.PatchAsync<Inventory, int>("SKU-100", i => i.Quantity, newQty);
}

Dependency Injection

Use ITransactionManager for testable, DI-friendly code:

// Registration
services.AddSingleton<IAmazonDynamoDB>(new AmazonDynamoDBClient());
services.AddSingleton<ITransactionManager, TransactionManager>();

// Usage
public class OrderService(ITransactionManager transactionManager)
{
    public async Task ConfirmOrder(Order order)
    {
        await using var transactor = new DynamoDbTransactor(transactionManager);
        transactor.CreateOrUpdate(order);
    }
}

Source Generator Deep Dive

How Discovery Works

The source generator runs at compile time and discovers entities via two pipelines:

1. Auto-discovery — any partial class with a [DynamoDBHashKey] property
2. Explicit opt-in — classes decorated with [DynamoDbGenerateMapping]

// Auto-discovered (recommended)
[DynamoDBTable("Orders")]
public partial class Order
{
    [DynamoDBHashKey("PK")]
    public string OrderId { get; set; }
}

// Explicit opt-in
[DynamoDbGenerateMapping]
[DynamoDBTable("Orders")]
public partial class Order
{
    [DynamoDBHashKey("PK")]
    public string OrderId { get; set; }
}

What Gets Generated

For each discovered entity, the generator emits:

• __DynamoDbMetadata nested class with:
  • GetPropertyAttributeName(string) — zero-allocation switch expression
  • MapToAttributes(T) — inline AttributeValue construction for known types (string, int, long, decimal, float, double, bool, DateTime, Guid, and their nullable variants) — no virtual dispatch, no boxing. Complex types (nested objects, collections, dictionaries) fall back to the runtime converter.
  • Pre-sized Dictionary<string, AttributeValue> with the exact property count known at compile time
  • GetVersion(T) — direct property access
• DynamoDbMappingRegistration.g.cs — [ModuleInitializer] that registers all types at app startup

Example of generated code for a string and decimal property:

// Generated — no function call, no boxing, no null check for value types
attributeMap["CustomerName"] = new AttributeValue { S = obj.CustomerName };
attributeMap["Total"] = new AttributeValue { N = obj.Total.ToString(CultureInfo.InvariantCulture) };

Fallback Behavior

Non-partial classes work seamlessly via cached reflection. You can mix both in the same project:

// Source-generated (60x faster lookups, inline AttributeValue)
public partial class FastEntity { ... }

// Reflection fallback (still fast with warmed caches)
public class LegacyEntity { ... }

Detailed Benchmark Results

Simple Entity (15 properties)

Isolated mapping operations — no DynamoDB I/O. Entity with 15 properties including all common types. Reflection results use warmed-up ConcurrentDictionary caches (best-case reflection).

BenchmarkDotNet v0.15.8, Linux Ubuntu 25.10
Intel Core i7-8700 CPU 3.20GHz (Coffee Lake), .NET 10.0.3, X64 RyuJIT x86-64-v3

IterationCount=20  LaunchCount=3  WarmupCount=5

Complex Entity (19 properties, nested objects, collections)

Realistic e-commerce order entity with strings, decimals, booleans, DateTimes, nested Address object, List<OrderItem>, and Dictionary<string, string>.

The complex entity gap is smaller for MapToAttribute because nested objects and collections still go through the runtime converter — the source generator inlines only primitive types. As more of your entity consists of primitive fields, the speedup approaches the 5x+ range.

End-to-End: Full Transaction (includes network I/O)

BenchmarkDotNet v0.13.12, Windows 11
AMD Ryzen 9 6900HS, .NET 8.0.2

Job=OutOfProc  IterationCount=15  LaunchCount=3  WarmupCount=10

The 3-item gap is dramatic because the standard SDK issues separate DescribeTable + write calls per item, while this library sends a single TransactWriteItems request.

What the Source Generator Optimizes

For primitive types, the generator emits direct AttributeValue construction — no method calls, no boxing, no virtual dispatch:

Run Benchmarks Yourself

# Simple entity benchmarks (source-gen vs reflection)
dotnet run --project test/DynamoDBv2.Transactions.Benchmarks -c Release -- --filter '*MapperBenchmark*'

# Complex entity benchmarks (19-property entity with nested objects)
dotnet run --project test/DynamoDBv2.Transactions.Benchmarks -c Release -- --filter '*ComplexEntity*'

# End-to-end benchmarks (requires localstack)
dotnet run --project test/DynamoDBv2.Transactions.Benchmarks -c Release -- --filter '*Benchmark*'

Running Tests

# Integration tests (requires Docker + localstack)
docker-compose up --exit-code-from tests tests localstack

# Unit tests
docker-compose up --exit-code-from unittests unittests

Test coverage: 259 unit tests, 33 integration tests, 16 source generator tests — all validated in CI on every push.

Versioning

This library's version tracks the underlying AWSSDK.DynamoDBv2 version:

Format: {aws_major}.{aws_minor}.{aws_patch}.{aws_rev * 100 + lib_rev}

The first three segments always tell you which AWS SDK version is inside. New AWS SDK versions are auto-released via Dependabot + CI pipeline.

Contributing

When creating PRs, please ensure:

• No sensitive information (tokens, keys, credentials) is included
• All existing tests pass (docker-compose up --exit-code-from tests tests localstack)
• New features include appropriate test coverage

License

Copyright © 2026, Vitali Bibikov. Code released under the MIT license.

Contact

Vitali Bibikov — bibikovvitaly@gmail.com