Features/dynamo db update behavior attribute #4049

irina-herciu · 2025-10-15T10:52:32Z

Add support for [DynamoDbUpdateBehavior] attribute to the .NET SDK for DynamoDB, enabling update behavior for a property when performing DynamoDB update operations. This feature aligns with the Java SDK's @DynamoDbUpdateBehavior.

Description

New Attribute: [DynamoDbUpdateBehavior]

[DynamoDbUpdateBehavior] Specifies the update behavior for a property when performing DynamoDB update operations. This attribute can be used to control whether a property is always updated, only updated if not null.

Update Behavior Modes:
- IfNotExists: Set the value only when the item is created.
- Always: Set the value on both create and update.

Usage:

class Order
{
    [DynamoDBHashKey]
    public string Id { get; set; }

    [DynamoDBAutoGeneratedTimestamp]
    [DynamoDbUpdateBehavior(UpdateBehavior.IfNotExists)]
    public DateTime CreatedAt { get; set; }

    [DynamoDBAutoGeneratedTimestamp]
    [DynamoDBProperty(StoreAsEpoch = true)]
    public DateTime? UpdatedAt { get; set; }
}

Motivation and Context

Testing

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist

My code follows the code style of this project
My change requires a change to the documentation
I have updated the documentation accordingly
I have read the README document
I have added tests to cover my changes
All new and existing tests passed

License

I confirm that this pull request can be released under the Apache 2 license

Copilot

Pull Request Overview

This PR adds support for the [DynamoDbUpdateBehavior] attribute to the .NET SDK for DynamoDB, enabling control over property update behavior during DynamoDB update operations. The feature aligns with the Java SDK's @DynamoDbUpdateBehavior annotation and introduces an IfNotExists mode that sets property values only when items are created (not on updates), alongside the default Always mode.

Key Changes

New DynamoDbUpdateBehaviorAttribute and UpdateBehavior enum to specify update behavior (Always/IfNotExists)
Updates to the update expression generation logic to support conditional if_not_exists clauses for properties marked with IfNotExists behavior
Integration with existing auto-generated timestamp functionality to enable create-only timestamp tracking

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
sdk/src/Services/DynamoDBv2/Custom/DataModel/Attributes.cs	Adds new `DynamoDbUpdateBehaviorAttribute` and `UpdateBehavior` enum
sdk/src/Services/DynamoDBv2/Custom/DataModel/InternalModel.cs	Adds `UpdateBehaviorMode` property to `PropertyStorage` and validation logic
sdk/src/Services/DynamoDBv2/Custom/DataModel/ContextInternal.cs	Implements `GetUpdateIfNotExistsAttributeNames` helper to identify properties with IfNotExists behavior
sdk/src/Services/DynamoDBv2/Custom/DataModel/Context.cs	Updates save operations to pass IfNotExists attribute names to update helpers
sdk/src/Services/DynamoDBv2/Custom/DataModel/TransactWrite.cs	Updates transact write to support IfNotExists attributes
sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Table.cs	Modifies `UpdateHelper` methods to accept and process IfNotExists attribute names
sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Util.cs	Updates expression generation to wrap IfNotExists attributes in `if_not_exists()` function
sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Expression.cs	Adds `MergeUpdateExpressions` method for combining multiple update expressions
sdk/src/Services/DynamoDBv2/Custom/DocumentModel/DocumentTransactWrite.cs	Updates transact write document operations to support IfNotExists attributes
sdk/src/Services/DynamoDBv2/Custom/DataModel/Utils.cs	Updates error message for validation
sdk/test/Services/DynamoDBv2/UnitTests/Custom/DataModel/ContextInternalTests.cs	Adds unit tests for `GetUpdateIfNotExistsAttributeNames` functionality
sdk/test/Services/DynamoDBv2/UnitTests/Custom/DocumentModel/TableTests.cs	New test file covering various update scenarios with and without IfNotExists attributes
sdk/test/Services/DynamoDBv2/UnitTests/Custom/DocumentModel/ExpressionsTest.cs	New test file for expression merging functionality
sdk/test/Services/DynamoDBv2/IntegrationTests/DataModelTests.cs	Updates integration tests to verify IfNotExists behavior with auto-generated timestamps
generator/.DevConfigs/9490947f-209f-47e9-8c70-3698872df304.json	Adds dev config for minor version bump

Copilot · 2025-10-15T13:53:18Z

sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Util.cs


                var update = kvp.Value;

+                var createOnly = ifNotExistAttributeNames?.Contains(attribute) ?? false;


Linear search through ifNotExistAttributeNames list occurs for every attribute update. Consider converting the list to a HashSet<string> at the call site for O(1) lookup performance when processing multiple attribute updates.

Copilot · 2025-10-15T13:53:19Z

sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Util.cs

+                if (update.Action == AttributeAction.DELETE && !createOnly)
                {


DELETE actions are silently suppressed for createOnly attributes without any indication to the caller. This could lead to unexpected behavior where a delete operation is ignored. Consider throwing an exception or logging a warning when attempting to delete a createOnly attribute.

Suggested change

if (update.Action == AttributeAction.DELETE && !createOnly)

{

if (update.Action == AttributeAction.DELETE)

{

if (createOnly)

{

throw new InvalidOperationException(

$"DELETE action is not allowed for createOnly attribute '{attribute}'.");

}

Copilot · 2025-10-15T13:53:19Z

sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Expression.cs

+                keywordsOrder.Where(k => mergedSections.ContainsKey(k))
+                             .Select(k => $"{k} {mergedSections[k]}"));
+
+            var mergedNames = Common.Combine(left.ExpressionAttributeNames, right.ExpressionAttributeNames, StringComparer.Ordinal);


The Common.Combine method is being called but may throw InvalidOperationException for duplicate keys with different values (as shown in the test at line 96-113 of ExpressionsTest.cs). However, this exception would be thrown inside Common.Combine, not in the calling code shown here. Consider documenting this behavior or handling the exception at this level to provide better error context.

Suggested change

var mergedNames = Common.Combine(left.ExpressionAttributeNames, right.ExpressionAttributeNames, StringComparer.Ordinal);

Dictionary<string, string> mergedNames;

try

{

mergedNames = Common.Combine(left.ExpressionAttributeNames, right.ExpressionAttributeNames, StringComparer.Ordinal);

}

catch (InvalidOperationException ex)

{

throw new InvalidOperationException("Failed to combine ExpressionAttributeNames due to duplicate keys with different values.", ex);

}

Copilot · 2025-10-15T13:53:20Z

sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Expression.cs

+                if (positions.Count == 0)
+                {
+                    // No recognized keywords, treat as a single section
+                    result[string.Empty] = expr.Trim();


Using an empty string as a dictionary key when no keywords are found is unclear and could lead to unexpected behavior. Consider using a more explicit sentinel value or throwing an exception if no valid update expression keywords are found.

Copilot · 2025-10-15T13:53:20Z

sdk/src/Services/DynamoDBv2/Custom/DataModel/Context.cs

+            var returnValues = counterConditionExpression == null && !updateIfNotExistsAttributeName.Any()
+                ? ReturnValues.None
+                : ReturnValues.AllNewAttributes;


The return value logic now includes updateIfNotExistsAttributeName.Any() which forces enumeration. Since this list is used multiple times (lines 381, 406, and later in UpdateHelperAsync), consider caching the result of .Any() in a boolean variable to avoid multiple enumerations.

Copilot · 2025-10-15T13:53:20Z

sdk/src/Services/DynamoDBv2/Custom/DataModel/Attributes.cs

+
+    /// <summary>
+    /// Specifies the update behavior for a property when performing DynamoDB update operations.
+    /// This attribute can be used to control whether a property is always updated, only updated if not null.


The documentation is incomplete and incorrect. It states 'only updated if not null' but the actual behavior is 'only set if the attribute does not exist in DynamoDB'. Update to: 'This attribute can be used to control whether a property is always updated or only set when the item is created (if the attribute does not exist).'

Suggested change

/// This attribute can be used to control whether a property is always updated, only updated if not null.

/// This attribute can be used to control whether a property is always updated or only set when the item is created (if the attribute does not exist).

Copilot · 2025-10-15T13:53:21Z

sdk/src/Services/DynamoDBv2/Custom/DocumentModel/Util.cs

+            }
+            else
+            {
+                var setStatement = updateExpression != null ? updateExpression.ExpressionStatement : "";


When there are no sets or removes and only an existing updateExpression, this code appends the expression statement directly without properly handling the case where it might be empty. If updateExpression.ExpressionStatement is empty or whitespace, this will create an invalid update expression with just whitespace. Add validation to only append when the statement is not null or whitespace.

Suggested change

var setStatement = updateExpression != null ? updateExpression.ExpressionStatement : "";

var setStatement = (updateExpression != null && !string.IsNullOrWhiteSpace(updateExpression.ExpressionStatement))

? updateExpression.ExpressionStatement

: "";

GarrettBeatty · 2025-10-15T22:28:24Z

ill give this a review later this week. thanks for the pr!

irina-herciu added 2 commits October 15, 2025 13:45

implement DynamoDbUpdateBehavior(UpdateBehavior.IfNotExists)

b7ac55a

add change file

ecb51e7

irina-herciu mentioned this pull request Oct 15, 2025

Add support for DynamoDBAutoGeneratedTimestampAttribute and DynamoDbUpdateBehaviorAttribute #3892

Closed

10 tasks

dscpinheiro changed the base branch from main to development October 15, 2025 12:32

GarrettBeatty requested review from GarrettBeatty, Copilot and normj October 15, 2025 13:50

Copilot AI reviewed Oct 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Features/dynamo db update behavior attribute #4049

Features/dynamo db update behavior attribute #4049

Uh oh!

irina-herciu commented Oct 15, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

GarrettBeatty commented Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		var update = kvp.Value;

		var createOnly = ifNotExistAttributeNames?.Contains(attribute) ?? false;

		if (update.Action == AttributeAction.DELETE && !createOnly)
		{

-                if (update.Action == AttributeAction.DELETE && !createOnly)
-                {
+                if (update.Action == AttributeAction.DELETE)
+                {
+                    if (createOnly)
+                    {
+                        throw new InvalidOperationException(
+                            $"DELETE action is not allowed for createOnly attribute '{attribute}'.");
+                    }

-            var mergedNames = Common.Combine(left.ExpressionAttributeNames, right.ExpressionAttributeNames, StringComparer.Ordinal);
+            Dictionary<string, string> mergedNames;
+            try
+            {
+                mergedNames = Common.Combine(left.ExpressionAttributeNames, right.ExpressionAttributeNames, StringComparer.Ordinal);
+            }
+            catch (InvalidOperationException ex)
+            {
+                throw new InvalidOperationException("Failed to combine ExpressionAttributeNames due to duplicate keys with different values.", ex);
+            }

	/// This attribute can be used to control whether a property is always updated, only updated if not null.
	/// This attribute can be used to control whether a property is always updated or only set when the item is created (if the attribute does not exist).

Features/dynamo db update behavior attribute #4049

Are you sure you want to change the base?

Features/dynamo db update behavior attribute #4049

Uh oh!

Conversation

irina-herciu commented Oct 15, 2025

Description

Motivation and Context

Testing

Screenshots (if appropriate)

Types of changes

Checklist

License

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

GarrettBeatty commented Oct 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants