DynamoDBv2.Transactions 4.0.14.103

DynamoDBv2.Transactions

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

<p align="center">

</p>

<p align="center">

</p>

<p align="center">

</p>

Why This Library?

The standard AWS SDK DynamoDBContext makes an implicit DescribeTable network call to resolve key schemas at runtime. DynamoDBv2.Transactions eliminates that entirely by reading [DynamoDBHashKey] attributes directly — and with the included source generator, all mapping is resolved at compile time with zero reflection overhead.

Performance at a Glance

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

Mapper: Source-Generated vs Reflection

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

End-to-End: This Library vs Standard SDK Wrapper

The standard SDK wrapper issues separate DescribeTable + write calls per item. This library batches everything into a single TransactWriteItems request.

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

All key lookups are zero-allocation via compile-time switch expressions. Just add partial to your entity class — no other changes needed.

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

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) — compile-time serialization (no PropertyInfo.GetValue())
  • GetVersion(T) — direct property access
• DynamoDbMappingRegistration.g.cs — [ModuleInitializer] that registers all types at app startup

Fallback Behavior

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

// Source-generated (82x faster lookups)
public partial class FastEntity { ... }

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

Detailed Benchmark Results

Mapper: Source-Generated vs Reflection

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
.NET SDK 9.0.311, .NET 9.0.13, X64 RyuJIT x86-64-v3

Runtime=.NET 9.0  IterationCount=20  LaunchCount=3  WarmupCount=5

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.

Run Benchmarks Yourself

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

# 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