DynamoDB C# and .NET: AWS SDK v4 Code Examples

Use AWSSDK.DynamoDBv2 4.x to work with DynamoDB from C# and .NET. It supports the low-level API, the Document model and the object persistence model through DynamoDBContextBuilder. The examples below use asynchronous operations, complete primary keys and explicit pagination, with the nullable response properties introduced in SDK v4.

Choose a programming model

All three use the same table and service APIs. A high-level model does not turn a scan into a key lookup or remove the need to handle errors.

Examples

• Setup
• Create table and model class
• Query
• Delete table
• Delete item
• Prevent overwriting existing records
• Scan
• Get items using a query filter
• Put item
• Get all items
• Get all items with pagination
• Get a single item
• Update item
• Batch get items
• Get items from multiple tables
• Batch write items
• Run transactions
• Run DynamoDB Local
• Migrating from SDK v3

Setup

Use a supported .NET SDK and install the current v4 package. These examples use language features available in .NET 8 or later. The package name still contains DynamoDBv2; that is the service name, not the AWS SDK's major version.

dotnet new console -n DynamoExamples
cd DynamoExamples
dotnet add package AWSSDK.DynamoDBv2 --version 4.0.109.1
dotnet new console -n DynamoExamples
cd DynamoExamples
dotnet add package AWSSDK.DynamoDBv2 --version 4.0.109.1

Replace Program.cs with the C# blocks below in order. Each partial-class block adds methods to the same EmployeeStore; the first block supplies shared imports, initialization and a key helper. The initial program constructs the store without making writes. Call individual methods explicitly when testing.

Use the default credential chain, such as a local AWS profile or an IAM role on AWS. Do not hard-code real access keys. The client Region must match the table's Region.

using Amazon;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using System.Globalization;
using AttributeValue = Amazon.DynamoDBv2.Model.AttributeValue;

using var client = new AmazonDynamoDBClient(RegionEndpoint.USEast1);
using var store = new EmployeeStore(client);
Console.WriteLine("Employee store ready");

public partial class EmployeeStore : IDisposable
{
    private const string TableName = "test_employee";
    private readonly IAmazonDynamoDB client;
    private readonly IDynamoDBContext context;
    private readonly Table table;

    public EmployeeStore(IAmazonDynamoDB client)
    {
        this.client = client;
        context = new DynamoDBContextBuilder()
            .WithDynamoDBClient(() => client)
            .Build();
        table = new TableBuilder(client, TableName)
            .AddHashKey("empId", DynamoDBEntryType.Numeric)
            .AddRangeKey("JoinedOn", DynamoDBEntryType.String)
            .AddGlobalSecondaryIndex("CategoryIndex", "EmployeeCategory",
                DynamoDBEntryType.String, "JoinedOn", DynamoDBEntryType.String)
            .Build();
    }

    private static Dictionary<string, AttributeValue> Key(int id, string joinedOn) => new()
    {
        ["empId"] = new() { N = id.ToString(CultureInfo.InvariantCulture) },
        ["JoinedOn"] = new() { S = joinedOn }
    };

    public void Dispose() => context.Dispose();
}
using Amazon;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using System.Globalization;
using AttributeValue = Amazon.DynamoDBv2.Model.AttributeValue;

using var client = new AmazonDynamoDBClient(RegionEndpoint.USEast1);
using var store = new EmployeeStore(client);
Console.WriteLine("Employee store ready");

public partial class EmployeeStore : IDisposable
{
    private const string TableName = "test_employee";
    private readonly IAmazonDynamoDB client;
    private readonly IDynamoDBContext context;
    private readonly Table table;

    public EmployeeStore(IAmazonDynamoDB client)
    {
        this.client = client;
        context = new DynamoDBContextBuilder()
            .WithDynamoDBClient(() => client)
            .Build();
        table = new TableBuilder(client, TableName)
            .AddHashKey("empId", DynamoDBEntryType.Numeric)
            .AddRangeKey("JoinedOn", DynamoDBEntryType.String)
            .AddGlobalSecondaryIndex("CategoryIndex", "EmployeeCategory",
                DynamoDBEntryType.String, "JoinedOn", DynamoDBEntryType.String)
            .Build();
    }

    private static Dictionary<string, AttributeValue> Key(int id, string joinedOn) => new()
    {
        ["empId"] = new() { N = id.ToString(CultureInfo.InvariantCulture) },
        ["JoinedOn"] = new() { S = joinedOn }
    };

    public void Dispose() => context.Dispose();
}

The context builder uses class attributes instead of fetching table metadata by default. The TableBuilder supplies equivalent metadata for Document operations. Neither builder creates an AWS table. Keep their declarations aligned with the actual schema.

Create table and model class

The employee table uses Number empId as its partition key and String JoinedOn as its sort key. Use normalized UTC strings such as 2026-10-23T09:00:00Z consistently so lexical order matches time order. CategoryIndex allows a separate query by category and date.

The C# property can have a different name from the stored attribute. The hash-key annotation maps EmpId to empId; the range-key and index annotations describe the remaining key metadata.

[DynamoDBTable("test_employee")]
public class Employee
{
    [DynamoDBHashKey("empId")]
    public int EmpId { get; set; }

    [DynamoDBRangeKey]
    [DynamoDBGlobalSecondaryIndexRangeKey("CategoryIndex")]
    public string JoinedOn { get; set; } = "";

    [DynamoDBGlobalSecondaryIndexHashKey("CategoryIndex")]
    public string EmployeeCategory { get; set; } = "";

    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string EmailAddress { get; set; } = "";
}

public partial class EmployeeStore
{
    public async Task CreateTableAsync(CancellationToken ct = default)
    {
        await client.CreateTableAsync(new CreateTableRequest
        {
            TableName = TableName,
            BillingMode = BillingMode.PAY_PER_REQUEST,
            AttributeDefinitions = new()
            {
                new("empId", ScalarAttributeType.N),
                new("JoinedOn", ScalarAttributeType.S),
                new("EmployeeCategory", ScalarAttributeType.S)
            },
            KeySchema = new()
            {
                new("empId", KeyType.HASH), new("JoinedOn", KeyType.RANGE)
            },
            GlobalSecondaryIndexes = new()
            {
                new()
                {
                    IndexName = "CategoryIndex",
                    KeySchema = new()
                    {
                        new("EmployeeCategory", KeyType.HASH),
                        new("JoinedOn", KeyType.RANGE)
                    },
                    Projection = new() { ProjectionType = ProjectionType.ALL }
                }
            }
        }, ct);
        using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
        timeout.CancelAfter(TimeSpan.FromMinutes(2));
        while (true)
        {
            var response = await client.DescribeTableAsync(
                new DescribeTableRequest { TableName = TableName }, timeout.Token);
            if (response.Table?.TableStatus == TableStatus.ACTIVE) return;
            await Task.Delay(TimeSpan.FromSeconds(2), timeout.Token);
        }
    }
}
[DynamoDBTable("test_employee")]
public class Employee
{
    [DynamoDBHashKey("empId")]
    public int EmpId { get; set; }

    [DynamoDBRangeKey]
    [DynamoDBGlobalSecondaryIndexRangeKey("CategoryIndex")]
    public string JoinedOn { get; set; } = "";

    [DynamoDBGlobalSecondaryIndexHashKey("CategoryIndex")]
    public string EmployeeCategory { get; set; } = "";

    public string FirstName { get; set; } = "";
    public string LastName { get; set; } = "";
    public string EmailAddress { get; set; } = "";
}

public partial class EmployeeStore
{
    public async Task CreateTableAsync(CancellationToken ct = default)
    {
        await client.CreateTableAsync(new CreateTableRequest
        {
            TableName = TableName,
            BillingMode = BillingMode.PAY_PER_REQUEST,
            AttributeDefinitions = new()
            {
                new("empId", ScalarAttributeType.N),
                new("JoinedOn", ScalarAttributeType.S),
                new("EmployeeCategory", ScalarAttributeType.S)
            },
            KeySchema = new()
            {
                new("empId", KeyType.HASH), new("JoinedOn", KeyType.RANGE)
            },
            GlobalSecondaryIndexes = new()
            {
                new()
                {
                    IndexName = "CategoryIndex",
                    KeySchema = new()
                    {
                        new("EmployeeCategory", KeyType.HASH),
                        new("JoinedOn", KeyType.RANGE)
                    },
                    Projection = new() { ProjectionType = ProjectionType.ALL }
                }
            }
        }, ct);
        using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
        timeout.CancelAfter(TimeSpan.FromMinutes(2));
        while (true)
        {
            var response = await client.DescribeTableAsync(
                new DescribeTableRequest { TableName = TableName }, timeout.Token);
            if (response.Table?.TableStatus == TableStatus.ACTIVE) return;
            await Task.Delay(TimeSpan.FromSeconds(2), timeout.Token);
        }
    }
}

Only key attributes belong in AttributeDefinitions; do not add every entity property. Creation is asynchronous, so the example waits for ACTIVE with a bounded application timeout.

Query

Query selects one partition, optionally restricted by a sort-key condition. This object-model example selects one employee's records from October onward. QueryAsync creates a search; awaiting GetNextSetAsync fetches a page.

public partial class EmployeeStore
{
    public async Task QueryEmployeeAsync(int empId, CancellationToken ct = default)
    {
        var search = context.QueryAsync<Employee>(empId, QueryOperator.GreaterThanOrEqual,
            new object[] { "2026-10-01T00:00:00Z" }, new QueryConfig());
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine($"{employee.EmpId}: {employee.JoinedOn}");
        }
    }

    public async Task QueryCategoryAsync(string category, CancellationToken ct = default)
    {
        var search = context.QueryAsync<Employee>(category,
            new QueryConfig { IndexName = "CategoryIndex", ConsistentRead = false });
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine(employee.FirstName);
        }
    }
}
public partial class EmployeeStore
{
    public async Task QueryEmployeeAsync(int empId, CancellationToken ct = default)
    {
        var search = context.QueryAsync<Employee>(empId, QueryOperator.GreaterThanOrEqual,
            new object[] { "2026-10-01T00:00:00Z" }, new QueryConfig());
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine($"{employee.EmpId}: {employee.JoinedOn}");
        }
    }

    public async Task QueryCategoryAsync(string category, CancellationToken ct = default)
    {
        var search = context.QueryAsync<Employee>(category,
            new QueryConfig { IndexName = "CategoryIndex", ConsistentRead = false });
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine(employee.FirstName);
        }
    }
}

For a GSI query, specify the index name and its partition key value, as QueryCategoryAsync does. GSIs support eventual consistency only. A local secondary index can use the same table partition key with a different sort key; its schema must also be declared in the model.

Delete table

Deleting a table is a different operation from deleting an entity. Use the low-level DeleteTableAsync API; it removes all items and indexes. A successful response starts deletion, so wait for absence if a subsequent step requires it.

public partial class EmployeeStore
{
    public Task<DeleteTableResponse> DeleteTableAsync(CancellationToken ct = default) =>
        client.DeleteTableAsync(new DeleteTableRequest { TableName = TableName }, ct);
}
public partial class EmployeeStore
{
    public Task<DeleteTableResponse> DeleteTableAsync(CancellationToken ct = default) =>
        client.DeleteTableAsync(new DeleteTableRequest { TableName = TableName }, ct);
}

Delete item

Both models require the complete primary key. An unconditional delete succeeds even if the item is already absent. The object-model version derives the table and key mapping from the class attributes.

public partial class EmployeeStore
{
    public Task<DeleteItemResponse> DeleteLowLevelAsync(int id, string joinedOn,
        CancellationToken ct = default) => client.DeleteItemAsync(new DeleteItemRequest
        {
            TableName = TableName, Key = Key(id, joinedOn)
        }, ct);

    public Task DeleteObjectAsync(int id, string joinedOn, CancellationToken ct = default) =>
        context.DeleteAsync<Employee>(id, joinedOn, new DeleteConfig(), ct);
}
public partial class EmployeeStore
{
    public Task<DeleteItemResponse> DeleteLowLevelAsync(int id, string joinedOn,
        CancellationToken ct = default) => client.DeleteItemAsync(new DeleteItemRequest
        {
            TableName = TableName, Key = Key(id, joinedOn)
        }, ct);

    public Task DeleteObjectAsync(int id, string joinedOn, CancellationToken ct = default) =>
        context.DeleteAsync<Employee>(id, joinedOn, new DeleteConfig(), ct);
}

Prevent overwriting existing records

A Document-model conditional put inserts only if the item at that complete key is absent. The condition is checked atomically; checking existence in a separate read would leave a race. A failed condition throws ConditionalCheckFailedException.

public partial class EmployeeStore
{
    public async Task<bool> InsertOnlyAsync(Employee employee, CancellationToken ct = default)
    {
        var condition = new Expression
        {
            ExpressionStatement = "attribute_not_exists(#pk)",
            ExpressionAttributeNames = new() { ["#pk"] = "empId" }
        };
        try
        {
            await table.PutItemAsync(context.ToDocument(employee),
                new PutItemOperationConfig { ConditionalExpression = condition }, ct);
            return true;
        }
        catch (ConditionalCheckFailedException)
        {
            return false;
        }
    }
}
public partial class EmployeeStore
{
    public async Task<bool> InsertOnlyAsync(Employee employee, CancellationToken ct = default)
    {
        var condition = new Expression
        {
            ExpressionStatement = "attribute_not_exists(#pk)",
            ExpressionAttributeNames = new() { ["#pk"] = "empId" }
        };
        try
        {
            await table.PutItemAsync(context.ToDocument(employee),
                new PutItemOperationConfig { ConditionalExpression = condition }, ct);
            return true;
        }
        catch (ConditionalCheckFailedException)
        {
            return false;
        }
    }
}

Use conditional writes for insert-only behavior, optimistic concurrency and state transitions. A condition failure is an application conflict; do not treat it like transient throttling.

Scan

A Scan evaluates table items and then applies its conditions. This filters for internal employees with IDs above 10. It uses async pagination rather than a synchronous enumerable, and an empty filtered page does not end the search.

public partial class EmployeeStore
{
    public async Task ScanInternalAsync(CancellationToken ct = default)
    {
        var search = context.ScanAsync<Employee>(new[]
        {
            new ScanCondition(nameof(Employee.EmpId), ScanOperator.GreaterThan, 10),
            new ScanCondition(nameof(Employee.EmployeeCategory), ScanOperator.Equal, "Internal")
        }, new ScanConfig());
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine(employee.FirstName);
        }
    }
}
public partial class EmployeeStore
{
    public async Task ScanInternalAsync(CancellationToken ct = default)
    {
        var search = context.ScanAsync<Employee>(new[]
        {
            new ScanCondition(nameof(Employee.EmpId), ScanOperator.GreaterThan, 10),
            new ScanCondition(nameof(Employee.EmployeeCategory), ScanOperator.Equal, "Internal")
        }, new ScanConfig());
        while (!search.IsDone)
        {
            foreach (var employee in await search.GetNextSetAsync(ct))
                Console.WriteLine(employee.FirstName);
        }
    }
}

The filter saves response payload, not the capacity used to evaluate the scanned items. Prefer a query on CategoryIndex when category is the access pattern.

Get items using a query filter

Use sort-key conditions to restrict what DynamoDB reads. Use a filter for other fields, such as FirstName. The object-model filter below is applied after selecting the employee's partition. GetRemainingAsync collects all remaining matches in memory, so use it only for bounded result sets.

public partial class EmployeeStore
{
    public Task<List<Employee>> QueryFilteredAsync(int id, string namePrefix,
        CancellationToken ct = default) => context.QueryAsync<Employee>(id,
            new QueryConfig
            {
                QueryFilter = new()
                {
                    new ScanCondition(nameof(Employee.FirstName), ScanOperator.BeginsWith, namePrefix)
                }
            }).GetRemainingAsync(ct);

    public async Task QueryLowLevelAsync(int id, string namePrefix, CancellationToken ct = default)
    {
        var request = new QueryRequest
        {
            TableName = TableName,
            KeyConditionExpression = "#pk = :id AND #sk >= :date",
            FilterExpression = "begins_with(#name, :name)",
            ExpressionAttributeNames = new()
            {
                ["#pk"] = "empId", ["#sk"] = "JoinedOn", ["#name"] = "FirstName"
            },
            ExpressionAttributeValues = new()
            {
                [":id"] = new() { N = id.ToString(CultureInfo.InvariantCulture) },
                [":date"] = new() { S = "2026-10-01T00:00:00Z" },
                [":name"] = new() { S = namePrefix }
            }
        };
        do
        {
            var response = await client.QueryAsync(request, ct);
            foreach (var item in response.Items ?? new())
                Console.WriteLine(Document.FromAttributeMap(item).ToJson());
            request.ExclusiveStartKey = response.LastEvaluatedKey;
        } while (request.ExclusiveStartKey?.Count > 0);
    }
}
public partial class EmployeeStore
{
    public Task<List<Employee>> QueryFilteredAsync(int id, string namePrefix,
        CancellationToken ct = default) => context.QueryAsync<Employee>(id,
            new QueryConfig
            {
                QueryFilter = new()
                {
                    new ScanCondition(nameof(Employee.FirstName), ScanOperator.BeginsWith, namePrefix)
                }
            }).GetRemainingAsync(ct);

    public async Task QueryLowLevelAsync(int id, string namePrefix, CancellationToken ct = default)
    {
        var request = new QueryRequest
        {
            TableName = TableName,
            KeyConditionExpression = "#pk = :id AND #sk >= :date",
            FilterExpression = "begins_with(#name, :name)",
            ExpressionAttributeNames = new()
            {
                ["#pk"] = "empId", ["#sk"] = "JoinedOn", ["#name"] = "FirstName"
            },
            ExpressionAttributeValues = new()
            {
                [":id"] = new() { N = id.ToString(CultureInfo.InvariantCulture) },
                [":date"] = new() { S = "2026-10-01T00:00:00Z" },
                [":name"] = new() { S = namePrefix }
            }
        };
        do
        {
            var response = await client.QueryAsync(request, ct);
            foreach (var item in response.Items ?? new())
                Console.WriteLine(Document.FromAttributeMap(item).ToJson());
            request.ExclusiveStartKey = response.LastEvaluatedKey;
        } while (request.ExclusiveStartKey?.Count > 0);
    }
}

Every placeholder must have a matching value or name alias. The Query API reference describes key conditions, filters, sorting and pagination. Set ScanIndexForward = false on the request to reverse sort-key order.

Put item

A low-level PutItem replaces the entire item at that key. ALL_OLD can return the previous item; PutItem cannot return ALL_NEW. Store a DynamoDB null with the NULL attribute-value flag. Empty non-key strings and binary values are allowed, but empty sets and empty key values are not.

public partial class EmployeeStore
{
    public Task<PutItemResponse> PutLowLevelAsync(Employee employee, CancellationToken ct = default)
    {
        var item = Key(employee.EmpId, employee.JoinedOn);
        item["FirstName"] = new() { S = employee.FirstName };
        item["LastName"] = new() { S = employee.LastName };
        item["EmailAddress"] = new() { S = employee.EmailAddress };
        item["EmployeeCategory"] = new() { S = employee.EmployeeCategory };
        return client.PutItemAsync(new PutItemRequest
        {
            TableName = TableName, Item = item,
            ReturnValues = Amazon.DynamoDBv2.ReturnValue.ALL_OLD
        }, ct);
    }

    public Task SaveObjectAsync(Employee employee, CancellationToken ct = default) =>
        context.SaveAsync(employee, new SaveConfig(), ct);
}
public partial class EmployeeStore
{
    public Task<PutItemResponse> PutLowLevelAsync(Employee employee, CancellationToken ct = default)
    {
        var item = Key(employee.EmpId, employee.JoinedOn);
        item["FirstName"] = new() { S = employee.FirstName };
        item["LastName"] = new() { S = employee.LastName };
        item["EmailAddress"] = new() { S = employee.EmailAddress };
        item["EmployeeCategory"] = new() { S = employee.EmployeeCategory };
        return client.PutItemAsync(new PutItemRequest
        {
            TableName = TableName, Item = item,
            ReturnValues = Amazon.DynamoDBv2.ReturnValue.ALL_OLD
        }, ct);
    }

    public Task SaveObjectAsync(Employee employee, CancellationToken ct = default) =>
        context.SaveAsync(employee, new SaveConfig(), ct);
}

SaveAsync persists mapped properties according to its save configuration; it is not a guarantee that concurrent edits are preserved. Use a version property or a low-level condition for concurrency-sensitive changes. Because EmployeeCategory is an index key, give it a nonempty value when saving this model.

Get all items

For small tables, the object model can gather the remaining scan pages into a list. This still performs a Scan, and it still reads every item. For larger tables, process pages as they arrive instead of building an unbounded list.

public partial class EmployeeStore
{
    public Task<List<Employee>> GetAllAsync(CancellationToken ct = default) =>
        context.ScanAsync<Employee>(Array.Empty<ScanCondition>(), new ScanConfig())
            .GetRemainingAsync(ct);
}
public partial class EmployeeStore
{
    public Task<List<Employee>> GetAllAsync(CancellationToken ct = default) =>
        context.ScanAsync<Employee>(Array.Empty<ScanCondition>(), new ScanConfig())
            .GetRemainingAsync(ct);
}

Get all items with pagination

The Document model exposes a pagination token. Return one page and its token to a caller, then pass that token into the next ScanOperationConfig. Tokens belong to their search configuration; do not interchange them with low-level LastEvaluatedKey maps. See DynamoDB pagination.

public record EmployeePage(List<Employee> Employees, string? NextToken);

public partial class EmployeeStore
{
    public async Task<EmployeePage> GetPageAsync(string? token = null,
        CancellationToken ct = default)
    {
        var search = table.Scan(new ScanOperationConfig
        {
            Limit = 25, PaginationToken = token
        });
        var documents = await search.GetNextSetAsync(ct);
        return new EmployeePage(context.FromDocuments<Employee>(documents).ToList(),
            search.IsDone ? null : search.PaginationToken);
    }
}
public record EmployeePage(List<Employee> Employees, string? NextToken);

public partial class EmployeeStore
{
    public async Task<EmployeePage> GetPageAsync(string? token = null,
        CancellationToken ct = default)
    {
        var search = table.Scan(new ScanOperationConfig
        {
            Limit = 25, PaginationToken = token
        });
        var documents = await search.GetNextSetAsync(ct);
        return new EmployeePage(context.FromDocuments<Employee>(documents).ToList(),
            search.IsDone ? null : search.PaginationToken);
    }
}

The service evaluates up to 1 MB before filtering, and Limit counts evaluated items. A page may contain fewer matches, or none, while still having a continuation token. Scan has no guaranteed ordering and does not provide a point-in-time snapshot.

Get a single item

Load by both key components, and check for an absent result before accessing properties. Use LoadConfig for a strongly consistent base-table read. Do not try to load an item directly by a GSI key; query the GSI instead.

public partial class EmployeeStore
{
    public async Task<Employee?> GetAsync(int id, string joinedOn, CancellationToken ct = default)
    {
        return await context.LoadAsync<Employee>(id, joinedOn,
            new LoadConfig { ConsistentRead = true }, ct);
    }
}
public partial class EmployeeStore
{
    public async Task<Employee?> GetAsync(int id, string joinedOn, CancellationToken ct = default)
    {
        return await context.LoadAsync<Employee>(id, joinedOn,
            new LoadConfig { ConsistentRead = true }, ct);
    }
}

Update item

For a targeted change, use an update expression rather than reading and saving an entire entity. This changes only the email and requires the item to exist. ReturnValues.ALL_NEW returns the resulting attributes.

public partial class EmployeeStore
{
    public Task<UpdateItemResponse> UpdateEmailAsync(int id, string joinedOn,
        string email, CancellationToken ct = default) => client.UpdateItemAsync(new UpdateItemRequest
        {
            TableName = TableName, Key = Key(id, joinedOn),
            UpdateExpression = "SET #email = :email",
            ConditionExpression = "attribute_exists(#pk)",
            ExpressionAttributeNames = new() { ["#email"] = "EmailAddress", ["#pk"] = "empId" },
            ExpressionAttributeValues = new() { [":email"] = new() { S = email } },
            ReturnValues = Amazon.DynamoDBv2.ReturnValue.ALL_NEW
        }, ct);
}
public partial class EmployeeStore
{
    public Task<UpdateItemResponse> UpdateEmailAsync(int id, string joinedOn,
        string email, CancellationToken ct = default) => client.UpdateItemAsync(new UpdateItemRequest
        {
            TableName = TableName, Key = Key(id, joinedOn),
            UpdateExpression = "SET #email = :email",
            ConditionExpression = "attribute_exists(#pk)",
            ExpressionAttributeNames = new() { ["#email"] = "EmailAddress", ["#pk"] = "empId" },
            ExpressionAttributeValues = new() { [":email"] = new() { S = email } },
            ReturnValues = Amazon.DynamoDBv2.ReturnValue.ALL_NEW
        }, ct);
}

To update an entity with the object model, load it, change its properties, then call SaveAsync with SaveConfig. That read-modify-write flow needs optimistic locking if multiple writers can edit the same properties.

Batch get items

Batch reads retrieve known keys, not query conditions. Results need not follow request order, and missing items are omitted. Never index into the result list assuming every key was found. The object model handles service batch sizing and unprocessed-key retries; keep a cancellation deadline for the operation.

public partial class EmployeeStore
{
    public async Task<List<Employee>> BatchGetAsync(CancellationToken ct = default)
    {
        var batch = context.CreateBatchGet<Employee>(new BatchGetConfig());
        batch.AddKey(101, "2026-10-23T09:00:00Z");
        batch.AddKey(102, "2026-10-23T09:00:00Z");
        await batch.ExecuteAsync(ct);
        return batch.Results;
    }
}
public partial class EmployeeStore
{
    public async Task<List<Employee>> BatchGetAsync(CancellationToken ct = default)
    {
        var batch = context.CreateBatchGet<Employee>(new BatchGetConfig());
        batch.AddKey(101, "2026-10-23T09:00:00Z");
        batch.AddKey(102, "2026-10-23T09:00:00Z");
        await batch.ExecuteAsync(ct);
        return batch.Results;
    }
}

At the low-level API, one batch supports up to 100 items and a 16 MB response. Retry UnprocessedKeys with backoff until complete or your deadline expires.

Get items from multiple tables

Create a batch for each mapped type, then combine them. The second example table, test_employee_work, must already exist with Number empId and String ProjectId keys. Both tables must be accessible to the same client.

[DynamoDBTable("test_employee_work")]
public class EmployeeWork
{
    [DynamoDBHashKey("empId")]
    public int EmpId { get; set; }
    [DynamoDBRangeKey]
    public string ProjectId { get; set; } = "";
    public string Description { get; set; } = "";
}

public partial class EmployeeStore
{
    public async Task MultiTableGetAsync(CancellationToken ct = default)
    {
        var employees = context.CreateBatchGet<Employee>(new BatchGetConfig());
        employees.AddKey(101, "2026-10-23T09:00:00Z");
        var work = context.CreateBatchGet<EmployeeWork>(new BatchGetConfig());
        work.AddKey(101, "P1");
        work.AddKey(101, "P2");
        await context.CreateMultiTableBatchGet(employees, work).ExecuteAsync(ct);
        foreach (var employee in employees.Results) Console.WriteLine(employee.FirstName);
        foreach (var project in work.Results) Console.WriteLine(project.ProjectId);
    }
}
[DynamoDBTable("test_employee_work")]
public class EmployeeWork
{
    [DynamoDBHashKey("empId")]
    public int EmpId { get; set; }
    [DynamoDBRangeKey]
    public string ProjectId { get; set; } = "";
    public string Description { get; set; } = "";
}

public partial class EmployeeStore
{
    public async Task MultiTableGetAsync(CancellationToken ct = default)
    {
        var employees = context.CreateBatchGet<Employee>(new BatchGetConfig());
        employees.AddKey(101, "2026-10-23T09:00:00Z");
        var work = context.CreateBatchGet<EmployeeWork>(new BatchGetConfig());
        work.AddKey(101, "P1");
        work.AddKey(101, "P2");
        await context.CreateMultiTableBatchGet(employees, work).ExecuteAsync(ct);
        foreach (var employee in employees.Results) Console.WriteLine(employee.FirstName);
        foreach (var project in work.Results) Console.WriteLine(project.ProjectId);
    }
}

Read each batch's typed Results after the combined execution. Multi-table batch reads are not transactional; use a read transaction when the reads must be atomic.

Batch write items

Object-model batch writes support puts and deletes, not partial updates or per-item conditions. The SDK breaks work into service-sized batches and retries unprocessed writes. The batch as a whole is not atomic.

public partial class EmployeeStore
{
    public async Task BatchWriteAsync(CancellationToken ct = default)
    {
        var batch = context.CreateBatchWrite<Employee>(new BatchWriteConfig());
        batch.AddPutItems(new[]
        {
            new Employee { EmpId = 101, JoinedOn = "2026-10-23T09:00:00Z",
                FirstName = "Jane", EmployeeCategory = "Internal" },
            new Employee { EmpId = 102, JoinedOn = "2026-10-23T09:00:00Z",
                FirstName = "John", EmployeeCategory = "Internal" }
        });
        batch.AddDeleteKey(111, "2026-10-23T09:00:00Z");
        await batch.ExecuteAsync(ct);
    }
}
public partial class EmployeeStore
{
    public async Task BatchWriteAsync(CancellationToken ct = default)
    {
        var batch = context.CreateBatchWrite<Employee>(new BatchWriteConfig());
        batch.AddPutItems(new[]
        {
            new Employee { EmpId = 101, JoinedOn = "2026-10-23T09:00:00Z",
                FirstName = "Jane", EmployeeCategory = "Internal" },
            new Employee { EmpId = 102, JoinedOn = "2026-10-23T09:00:00Z",
                FirstName = "John", EmployeeCategory = "Internal" }
        });
        batch.AddDeleteKey(111, "2026-10-23T09:00:00Z");
        await batch.ExecuteAsync(ct);
    }
}

At the low-level API, explicitly handle UnprocessedItems, use exponential backoff with jitter and retain leftovers if your retry budget expires. Each service request is limited to 25 puts/deletes and 16 MB. Do not put and delete the same key in one batch.

Run transactions

A transaction can atomically check, put, update or delete distinct items. This example requires employee 101 to exist and writes a different employee record. It does not apply a condition check and a write to the same item, which DynamoDB rejects.

public partial class EmployeeStore
{
    public async Task TransactAsync(string token, CancellationToken ct = default)
    {
        var newEmployee = Key(102, "2026-10-23T09:00:00Z");
        newEmployee["FirstName"] = new() { S = "Jane" };
        newEmployee["EmployeeCategory"] = new() { S = "Internal" };
        try
        {
            await client.TransactWriteItemsAsync(new TransactWriteItemsRequest
            {
                ClientRequestToken = token,
                TransactItems = new()
                {
                    new() { ConditionCheck = new()
                    {
                        TableName = TableName, Key = Key(101, "2026-10-23T09:00:00Z"),
                        ConditionExpression = "attribute_exists(empId)"
                    }},
                    new() { Put = new()
                    {
                        TableName = TableName, Item = newEmployee,
                        ConditionExpression = "attribute_not_exists(empId)"
                    }}
                }
            }, ct);
        }
        catch (TransactionCanceledException ex)
        {
            foreach (var reason in ex.CancellationReasons ?? new())
                Console.Error.WriteLine(reason.Code);
            throw;
        }
    }
}
public partial class EmployeeStore
{
    public async Task TransactAsync(string token, CancellationToken ct = default)
    {
        var newEmployee = Key(102, "2026-10-23T09:00:00Z");
        newEmployee["FirstName"] = new() { S = "Jane" };
        newEmployee["EmployeeCategory"] = new() { S = "Internal" };
        try
        {
            await client.TransactWriteItemsAsync(new TransactWriteItemsRequest
            {
                ClientRequestToken = token,
                TransactItems = new()
                {
                    new() { ConditionCheck = new()
                    {
                        TableName = TableName, Key = Key(101, "2026-10-23T09:00:00Z"),
                        ConditionExpression = "attribute_exists(empId)"
                    }},
                    new() { Put = new()
                    {
                        TableName = TableName, Item = newEmployee,
                        ConditionExpression = "attribute_not_exists(empId)"
                    }}
                }
            }, ct);
        }
        catch (TransactionCanceledException ex)
        {
            foreach (var reason in ex.CancellationReasons ?? new())
                Console.Error.WriteLine(reason.Code);
            throw;
        }
    }
}

Use a stable, unique token for retries of one logical transaction with identical parameters. Its idempotency window lasts 10 minutes after completion. Transactions support up to 100 unique items and 4 MB in one account and Region; MRSC global tables do not support them. A canceled transaction may reflect a condition failure, a conflict or another service validation issue, so inspect the cancellation reasons.

Run DynamoDB Local

Use a local endpoint and dummy credentials for an emulator. The signing Region is still required. Pass the returned client into the same EmployeeStore constructor. Keep this configuration separate from your real AWS profile.

public partial class EmployeeStore
{
    public static AmazonDynamoDBClient CreateLocalClient() => new(
        new BasicAWSCredentials("local", "local"),
        new AmazonDynamoDBConfig
        {
            ServiceURL = "http://localhost:8000",
            AuthenticationRegion = "us-east-1"
        });
}
public partial class EmployeeStore
{
    public static AmazonDynamoDBClient CreateLocalClient() => new(
        new BasicAWSCredentials("local", "local"),
        new AmazonDynamoDBConfig
        {
            ServiceURL = "http://localhost:8000",
            AuthenticationRegion = "us-east-1"
        });
}

In ASP.NET Core, register a single reusable IAmazonDynamoDB client and an EmployeeStore through dependency injection. For example, put the following registration in Program.cs before building the web application. The web project's implicit imports include dependency-injection extensions:

// ASP.NET Core Program.cs registration, instead of the console entry point.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IAmazonDynamoDB>(_ =>
    builder.Configuration.GetValue<bool>("DynamoDb:LocalMode")
        ? EmployeeStore.CreateLocalClient()
        : new AmazonDynamoDBClient(RegionEndpoint.USEast1));
builder.Services.AddSingleton<EmployeeStore>();
var app = builder.Build();
app.Run();
// ASP.NET Core Program.cs registration, instead of the console entry point.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IAmazonDynamoDB>(_ =>
    builder.Configuration.GetValue<bool>("DynamoDb:LocalMode")
        ? EmployeeStore.CreateLocalClient()
        : new AmazonDynamoDBClient(RegionEndpoint.USEast1));
builder.Services.AddSingleton<EmployeeStore>();
var app = builder.Build();
app.Run();

Use a local development configuration to enable DynamoDb:LocalMode. The production branch uses the default credential chain. The endpoint can be moved into configuration when your emulator runs on another port.

Migrating from SDK v3

AWS SDK for .NET v3 reached end of support on June 1, 2026. When updating to v4:

• Replace obsolete new DynamoDBContext(client) construction with DynamoDBContextBuilder.
• Replace DynamoDBOperationConfig overloads with operation-specific QueryConfig, ScanConfig, SaveConfig, LoadConfig and related types.
• Initialize request dictionaries and lists explicitly. Response collections can be null; check them before iterating.
• Handle nullable value properties. For example, use response.Count ?? 0, and distinguish an unset nullable Boolean from an explicit false when that distinction matters.
• Recheck date serialization and custom Document JSON handling. V4 uses UTC retrieval by default and System.Text.Json for Document JSON conversion.

The v4 migration guide lists the breaking changes. The current C# examples provide additional low-level operations. For access-pattern decisions, see Query vs. Scan.