feat!: migrate to AWS SDK for .NET v4 with breaking changes

BREAKING CHANGE: Complete migration from AWS SDK for .NET v3 to v4

- Collections in AWS models now default to null instead of empty collections
- DynamoDB entity validation requires proper attribute decoration for GSI operations
- Applications must implement null-conditional operators for collection access

Key Changes:
- Fixed SNS Topics collection null-safety in functional tests
- Fixed SQS Messages collection null-safety in functional tests
- Added DynamoDB entity GSI attribute decoration for MovieEntity
- Corrected MovieTableMovie index name typo in test constants
- All 1,099 tests passing across .NET 8, 9, Standard 2.0, Framework 4.7.2

Author: Blind-Striker

CHANGELOG.md

@@ -1,5 +1,45 @@
 # LocalStack .NET Client Change Log
 
+### [v2.0.0-preview1](https://github.com/localstack-dotnet/localstack-dotnet-client/releases/tag/v2.0.0-preview1)
+
+#### 1. Breaking Changes
+
+- **Framework Support Updates:**
+  - **Deprecated** support for **.NET Framework 4.6.2**.
+  - **Added** support for **.NET Framework 4.7.2** (required for AWS SDK v4 compatibility).
+
+#### 2. General
+
+- **AWS SDK v4 Migration:**
+  - **Complete migration** from AWS SDK for .NET v3 to v4.
+  - **AWSSDK.Core** minimum version set to **4.0.0.15**.
+  - **AWSSDK.Extensions.NETCore.Setup** updated to **4.0.2**.
+  - All 70+ AWS SDK service packages updated to v4.x series.
+
+- **Framework Support:**
+  - **.NET 9**
+  - **.NET 8**  
+  - **.NET Standard 2.0**
+  - **.NET Framework 4.7.2**
+
+- **Testing Validation:**
+  - **1,099 total tests** passing across all target frameworks.
+  - Successfully tested with AWS SDK v4 across all supported .NET versions.
+  - Tested against following LocalStack versions:
+    - **v3.7.1**
+    - **v4.3.0**
+
+#### 3. Important Notes
+
+- **Preview Release**: This is a preview release for early adopters and testing. See the [v2.0.0 Roadmap & Migration Guide](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions/45) for the complete migration plan.
+- **No API Changes**: LocalStack.NET public APIs remain unchanged. All changes are internal to support AWS SDK v4 compatibility.
+- **Feedback Welcome**: Please report issues or feedback on [GitHub Issues](https://github.com/localstack-dotnet/localstack-dotnet-client/issues).
+- **v2.x series requires AWS SDK v4**: This version is only compatible with AWS SDK for .NET v4.x packages.
+- **Migration from v1.x**: Users upgrading from v1.x should ensure their projects reference AWS SDK v4 packages.
+- **Framework Requirement**: .NET Framework 4.7.2 or higher is now required (upgrade from 4.6.2).
+
+---
+
 ### [v1.6.0](https://github.com/localstack-dotnet/localstack-dotnet-client/releases/tag/v1.6.0)
 
 #### 1. General

tests/LocalStack.Client.Extensions.Tests/AwsClientFactoryWrapperTests.cs

@@ -49,8 +49,8 @@ public void CreateServiceClient_Should_Throw_LocalStackClientConfigurationExcept
 
         var exception = Assert.Throws<LocalStackClientConfigurationException>(
             () => _awsClientFactoryWrapper.CreateServiceClient<MockAmazonServiceClient>(_mockServiceProvider.Object, _awsOptions));
-        
-        Assert.Contains("Failed to find AWS SDK v4 ClientFactory<T>", exception.Message, StringComparison.Ordinal);
+
+        Assert.Contains("Failed to find internal ClientFactory<T>", exception.Message, StringComparison.Ordinal);
     }
 
     [Fact]

tests/LocalStack.Client.Functional.Tests/Scenarios/DynamoDb/BaseDynamoDbScenario.cs

@@ -10,9 +10,7 @@ protected BaseDynamoDbScenario(TestFixture testFixture, ILocalStackFixture local
                                    bool useServiceUrl = false) : base(testFixture, localStackFixture, configFile, useServiceUrl)
     {
         DynamoDb = ServiceProvider.GetRequiredService<IAmazonDynamoDB>();
-        DynamoDbContext = new DynamoDBContextBuilder()
-            .WithDynamoDBClient(() => DynamoDb)
-            .Build();
+        DynamoDbContext = new DynamoDBContextBuilder().WithDynamoDBClient(() => DynamoDb).Build();
     }
 
     protected IAmazonDynamoDB DynamoDb { get; private set; }
@@ -41,12 +39,25 @@ public virtual async Task DynamoDbService_Should_Delete_A_DynamoDb_Table_Async()
     public virtual async Task DynamoDbService_Should_Add_A_Record_To_A_DynamoDb_Table_Async()
     {
         var tableName = Guid.NewGuid().ToString();
+
         // Fix: Use GetTargetTableConfig instead of DynamoDBOperationConfig
         var getTargetTableConfig = new GetTargetTableConfig() { OverrideTableName = tableName };
+
         await CreateTestTableAsync(tableName);
 
+        var describeResponse = await DynamoDb.DescribeTableAsync(new DescribeTableRequest(tableName));
+        var gsiExists = describeResponse.Table.GlobalSecondaryIndexes?.Exists(gsi => gsi.IndexName == TestConstants.MovieTableMovieIdGsi) == true;
+
+        if (!gsiExists)
+        {
+            var availableGsis = describeResponse.Table.GlobalSecondaryIndexes?.Select(g => g.IndexName).ToArray() ?? ["none"];
+
+            throw new System.InvalidOperationException($"GSI '{TestConstants.MovieTableMovieIdGsi}' was not found on table '{tableName}'. " +
+                                                       $"Available GSIs: {string.Join(", ", availableGsis)}");
+        }
+
         // Fix: Cast to Table and use GetTargetTableConfig
-        Table targetTable = (Table)DynamoDbContext.GetTargetTable<MovieEntity>(getTargetTableConfig);
+        var targetTable = (Table)DynamoDbContext.GetTargetTable<MovieEntity>(getTargetTableConfig);
 
         var movieEntity = new Fixture().Create<MovieEntity>();
         string modelJson = JsonSerializer.Serialize(movieEntity);
@@ -55,14 +66,9 @@ public virtual async Task DynamoDbService_Should_Add_A_Record_To_A_DynamoDb_Tabl
         await targetTable.PutItemAsync(item);
 
         // Fix: Use QueryConfig instead of DynamoDBOperationConfig
-        var queryConfig = new QueryConfig()
-        {
-            OverrideTableName = tableName,
-            IndexName = TestConstants.MovieTableMovieIdGsi
-        };
+        var queryConfig = new QueryConfig() { OverrideTableName = tableName, IndexName = TestConstants.MovieTableMovieIdGsi };
 
-        List<MovieEntity> movieEntities =
-            await DynamoDbContext.QueryAsync<MovieEntity>(movieEntity.MovieId, queryConfig).GetRemainingAsync();
+        List<MovieEntity> movieEntities = await DynamoDbContext.QueryAsync<MovieEntity>(movieEntity.MovieId, queryConfig).GetRemainingAsync();
 
         Assert.True(movieEntity.DeepEquals(movieEntities[0]));
     }
@@ -78,31 +84,25 @@ public virtual async Task DynamoDbService_Should_List_Records_In_A_DynamoDb_Tabl
         await CreateTestTableAsync(tableName);
 
         // Fix: Cast to Table and use GetTargetTableConfig
-        Table targetTable = (Table)DynamoDbContext.GetTargetTable<MovieEntity>(getTargetTableConfig);
-        List<MovieEntity> movieEntities = new Fixture().CreateMany<MovieEntity>(recordCount).ToList();
-        List<Document> documents = movieEntities.Select(entity =>
+        var targetTable = (Table)DynamoDbContext.GetTargetTable<MovieEntity>(getTargetTableConfig);
+        List<MovieEntity> movieEntities = [.. new Fixture().CreateMany<MovieEntity>(recordCount)];
+        List<Document> documents = [.. movieEntities.Select(entity =>
                                                 {
                                                     string serialize = JsonSerializer.Serialize(entity);
                                                     Document item = Document.FromJson(serialize);
 
                                                     return item;
-                                                })
-                                                .ToList();
+                                                }),];
 
         foreach (Document document in documents)
         {
             await targetTable.PutItemAsync(document);
         }
 
         // Fix: Use ScanConfig instead of DynamoDBOperationConfig
-        var scanConfig = new ScanConfig()
-        {
-            OverrideTableName = tableName,
-            IndexName = TestConstants.MovieTableMovieIdGsi
-        };
+        var scanConfig = new ScanConfig() { OverrideTableName = tableName, IndexName = TestConstants.MovieTableMovieIdGsi };
 
-        List<MovieEntity> returnedMovieEntities =
-            await DynamoDbContext.ScanAsync<MovieEntity>(new List<ScanCondition>(), scanConfig).GetRemainingAsync();
+        List<MovieEntity> returnedMovieEntities = await DynamoDbContext.ScanAsync<MovieEntity>(new List<ScanCondition>(), scanConfig).GetRemainingAsync();
 
         Assert.NotNull(movieEntities);
         Assert.NotEmpty(movieEntities);
@@ -120,29 +120,28 @@ protected Task<CreateTableResponse> CreateTestTableAsync(string? tableName = nul
         var postTableCreateRequest = new CreateTableRequest
         {
             AttributeDefinitions =
-                new List<AttributeDefinition>
-                {
-                    new() { AttributeName = nameof(MovieEntity.DirectorId), AttributeType = ScalarAttributeType.S },
-                    new() { AttributeName = nameof(MovieEntity.CreateDate), AttributeType = ScalarAttributeType.S },
-                    new() { AttributeName = nameof(MovieEntity.MovieId), AttributeType = ScalarAttributeType.S },
-                },
+            [
+                new AttributeDefinition { AttributeName = nameof(MovieEntity.DirectorId), AttributeType = ScalarAttributeType.S },
+                new AttributeDefinition { AttributeName = nameof(MovieEntity.CreateDate), AttributeType = ScalarAttributeType.S },
+                new AttributeDefinition { AttributeName = nameof(MovieEntity.MovieId), AttributeType = ScalarAttributeType.S },
+            ],
             TableName = tableName ?? TestTableName,
             KeySchema =
-                new List<KeySchemaElement>()
-                {
-                    new() { AttributeName = nameof(MovieEntity.DirectorId), KeyType = KeyType.HASH },
-                    new() { AttributeName = nameof(MovieEntity.CreateDate), KeyType = KeyType.RANGE },
-                },
-            GlobalSecondaryIndexes = new List<GlobalSecondaryIndex>
-            {
-                new()
+            [
+                new KeySchemaElement { AttributeName = nameof(MovieEntity.DirectorId), KeyType = KeyType.HASH },
+                new KeySchemaElement { AttributeName = nameof(MovieEntity.CreateDate), KeyType = KeyType.RANGE },
+            ],
+            GlobalSecondaryIndexes =
+            [
+                new GlobalSecondaryIndex
                 {
                     Projection = new Projection { ProjectionType = ProjectionType.ALL },
                     IndexName = TestConstants.MovieTableMovieIdGsi,
-                    KeySchema = new List<KeySchemaElement> { new() { AttributeName = nameof(MovieEntity.MovieId), KeyType = KeyType.HASH } },
-                    ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 5, WriteCapacityUnits = 5 }
-                }
-            },
+                    KeySchema = [new KeySchemaElement { AttributeName = nameof(MovieEntity.MovieId), KeyType = KeyType.HASH }],
+                    ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 5, WriteCapacityUnits = 5 },
+                },
+
+            ],
             ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 5, WriteCapacityUnits = 6 },
         };
 

tests/LocalStack.Client.Functional.Tests/Scenarios/DynamoDb/Entities/MovieEntity.cs

@@ -8,10 +8,10 @@ public class MovieEntity
     public Guid DirectorId { get; set; }
 
     [DynamoDBRangeKey]
-
     public string CreateDate { get; set; }
 
+    [DynamoDBGlobalSecondaryIndexHashKey(TestConstants.MovieTableMovieIdGsi)]
     public Guid MovieId { get; set; }
 
     public string MovieName { get; set; }
-}
+}

tests/LocalStack.Client.Functional.Tests/Scenarios/RealLife/BaseRealLife.cs

@@ -66,7 +66,7 @@ public virtual async Task
 
         Assert.Equal(HttpStatusCode.OK, receiveMessageResponse.HttpStatusCode);
 
-        if (receiveMessageResponse.Messages.Count == 0)
+        if ((receiveMessageResponse.Messages?.Count ?? 0) == 0)
         {
             await Task.Delay(2000);
             receiveMessageResponse = await AmazonSqs.ReceiveMessageAsync(receiveMessageRequest);
@@ -75,7 +75,7 @@ public virtual async Task
         }
 
         Assert.NotNull(receiveMessageResponse.Messages);
-        Assert.NotEmpty(receiveMessageResponse.Messages);
+        Assert.NotEmpty(receiveMessageResponse.Messages!);
         Assert.Single(receiveMessageResponse.Messages);
 
         dynamic? deserializedMessage = JsonConvert.DeserializeObject<ExpandoObject>(receiveMessageResponse.Messages[0].Body, new ExpandoObjectConverter());

tests/LocalStack.Client.Functional.Tests/Scenarios/SNS/BaseSnsScenario.cs

@@ -22,7 +22,7 @@ public async Task SnsService_Should_Create_A_Sns_Topic_Async()
         Assert.Equal(HttpStatusCode.OK, createTopicResponse.HttpStatusCode);
 
         ListTopicsResponse listTopicsResponse = await AmazonSimpleNotificationService.ListTopicsAsync();
-        Topic? snsTopic = listTopicsResponse.Topics.SingleOrDefault(topic => topic.TopicArn == createTopicResponse.TopicArn);
+        Topic? snsTopic = listTopicsResponse.Topics?.SingleOrDefault(topic => topic.TopicArn == createTopicResponse.TopicArn);
 
         Assert.NotNull(snsTopic);
         Assert.EndsWith(topicName, snsTopic.TopicArn, StringComparison.Ordinal);
@@ -41,7 +41,7 @@ public async Task SnsService_Should_Delete_A_Sns_Topic_Async()
         Assert.Equal(HttpStatusCode.OK, deleteTopicResponse.HttpStatusCode);
 
         ListTopicsResponse listTopicsResponse = await AmazonSimpleNotificationService.ListTopicsAsync();
-        bool hasAny = listTopicsResponse.Topics.Exists(topic => topic.TopicArn == createTopicResponse.TopicArn);
+        bool hasAny = listTopicsResponse.Topics?.Exists(topic => topic.TopicArn == createTopicResponse.TopicArn) ?? false;
 
         Assert.False(hasAny);
     }
@@ -91,9 +91,10 @@ public virtual async Task Multi_Region_Tests_Async(string systemName)
         var topicArn = $"arn:aws:sns:{systemName}:000000000000:{topicName}";
 
         ListTopicsResponse listTopicsResponse = await AmazonSimpleNotificationService.ListTopicsAsync();
-        Topic? snsTopic = listTopicsResponse.Topics.SingleOrDefault(topic => topic.TopicArn == topicArn);
+        Topic? snsTopic = listTopicsResponse.Topics?.SingleOrDefault(topic => topic.TopicArn == topicArn);
 
         Assert.NotNull(snsTopic);
+        Assert.NotNull(listTopicsResponse.Topics);
         Assert.Single(listTopicsResponse.Topics);
 
         await DeleteSnsTopicAsync(topicArn); //Cleanup

tests/LocalStack.Client.Functional.Tests/TestConstants.cs

@@ -7,5 +7,5 @@ public static class TestConstants
     public const string LocalStackV37 = "3.7.1";
     public const string LocalStackV43 = "4.3.0";
 
-    public const string MovieTableMovieIdGsi = "MoiveTableMovie-Index";
+    public const string MovieTableMovieIdGsi = "MovieTableMovie-Index";
 }