Migrating to version 4 of the AWS SDK for .NET

Add the AWSSDK.Extensions.Logging.Log4NetAdaptor NuGet package and call the static ConfigureAWSSDKLogging method from Log4NetAWSExtensions.

using Amazon.DynamoDBv2;
using Amazon.Extensions.Logging.Log4NetAdaptor;
using log4net;

[assembly: log4net.Config.XmlConfigurator(ConfigFile = "log4net.config")]

Log4NetAWSExtensions.ConfigureAWSSDKLogging();
var logger = LogManager.GetLogger(typeof(Program));

using Amazon.DynamoDBv2;
using Amazon.Extensions.Logging.Log4NetAdaptor;
using log4net;

[assembly: log4net.Config.XmlConfigurator(ConfigFile = "log4net.config")]

Log4NetAWSExtensions.ConfigureAWSSDKLogging();
var logger = LogManager.GetLogger(typeof(Program));

Add the AWSSDK.Extensions.Logging.ILoggerAdaptor NuGet package and call the ConfigureAWSSDKLogging extension method from the ILoggerFactory interface.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.Services.GetRequiredService<ILoggerFactory>()
    .ConfigureAWSSDKLogging();

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.Services.GetRequiredService<ILoggerFactory>()
    .ConfigureAWSSDKLogging();

V4 changes in the SDK for DynamoDB address some issues around testability, but primarily center around the high-level libraries:

For detailed information about these programming modes, see DynamoDB in this guide.

Document Model: Updated exception for mocked IAmazonDynamoDB interface

In the document model prior to V4 of the SDK, if a Table was initialized with a mocked IAmazonDynamoDB interface, it would return NullReferenceException. V4 of the SDK returns InvalidOperationException instead. Async Table methods should work with a mocked client but you might still see exceptions when calling synchronous methods from .NET/Core/Standard.

For more information about this change, see PR 3388 on GitHub.

Document Model: FromJson and ToJson methods

The FromJson and ToJson methods of the Document class now use System.Text.Json instead of LitJson for serialization, and LitJson has been removed from V4 of the SDK. A benefit of using System.Text.Json is that this parser supports using the .NET Decimal type, which supports higher precision for numeric floating point properties.

Object Persistence Model: The DynamoDBOperationConfig class

In the object persistence model, the following changes have been made to the shared DynamoDBOperationConfig class:

Object Persistence Model: Polymorphism

The DynamoDBPolymorphicTypeAttribute class was added to the object persistence model. This class enables support for serialization and deserialization of polymorphic types. For more information, see PR 3643 on GitHub.

Document Model and Object Persistence Model: Mockable operations

New operation-specific interfaces have been added that allow customers to mock DynamoDB operations. The factory methods on the IDynamoDBContext interface have been updated to return the new interfaces.

For more information about this change, see PR 3450 on GitHub.

Document Model and Object Persistence Model: Support for Native AOT

A limitation of Native AOT is support for nested .NET types. In some cases, these nested types might go unnoticed by the trimming component of the .NET compiler. In this case, you might receive an exception such as: "System.InvalidOperationException: Type <type> is unsupported, it cannot be instantiated."

You can work around this limitation by adding the DynamicDependency somewhere in the code path that informs the trimmer about the dependency on the sub-type. The constructor of the top-level .NET type being saved is a likely place. The following code example shows you how to use the DynamicDependency attribute:

[DynamoDBTable("TestTable")]
class TypeWithNestedTypeProperty
{
    [DynamicDependency(DynamicallyAccessedMemberTypes.All, typeof(SubType))]
    public TypeWithNestedTypeProperty()
    {

    }

    [DynamoDBHashKey]
    public string Id { get; set; }
    public string Name { get; set; }

    public SubType SubType { get; set; }
}

class SubType
{
    public string SubName { get; set; }
}

DynamoDBStreams

DynamoDBStreams has been removed from the AWSSDK.DynamoDB NuGet package and is available in its own package, AWSSDK.DynamoDBStreams, and has its own namespace, Amazon.DynamoDBStreams.

Allow removal of the TableNamePrefix value

You can now remove the value of the TableNamePrefix property in the DynamoDBContextConfig class on the individual operation level. For more information about this change, see PR 3476 on GitHub.

RetrieveDateTimeInUtc property

For the DynamoDBContextConfig class, the default value of the RetrieveDateTimeInUtc property has been changed to true.

DynamoDBContextTableNamePrefix property

Removed the DynamoDBContextTableNamePrefix property from AWSConfigsDynamoDB class. Users should call AWSConfigsDynamoDB.Context.TableNamePrefix instead of

[DynamoDBTable("TestTable")]
class TypeWithNestedTypeProperty
{
    [DynamicDependency(DynamicallyAccessedMemberTypes.All, typeof(SubType))]
    public TypeWithNestedTypeProperty()
    {

    }

    [DynamoDBHashKey]
    public string Id { get; set; }
    public string Name { get; set; }

    public SubType SubType { get; set; }
}

class SubType
{
    public string SubName { get; set; }
}

GetDecryptedPassword

The GetDecryptedPassword extension for Amazon EC2 has been moved to a separate extension package called AWSSDK.Extensions.EC2.DecryptPassword. This change is to support OpenSSL 3 and take a dependency on BouncyCastle.Cryptography.

The source code for this package is on GitHub at https://github.com/aws/aws-sdk-net/tree/main/extensions/src/AWSSDK.Extensions.EC2.DecryptPassword.

Support for Amazon EC2 IMDSv1

Support for Instance Metadata Service Version 1 (IMDSv1) has been removed. V4 of the SDK always uses Instance Metadata Service Version 2 (IMDSv2) when fetching credentials and other metadata from the IMDS. For more information about the IMDS, see Use the IMDS in the Amazon EC2 User Guide.

Programming elements that were changed or removed

AWS Region us-east-1

Amazon S3 service clients configured for the us-east-1 Region can no longer access buckets in other Regions. Buckets must be accessed with S3 service clients configured for the Region the bucket is in.

S3 encryption client

The Amazon S3 encryption client, which is defined in the Amazon.S3.Encryption namespace, has been removed from the AWSSDK.S3 package. This client has been moved to its own package called Amazon.Extensions.S3.Encryption, and the documentation for it is at https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.html. For information about migration, see Amazon S3 Encryption Client Migration. For more information about S3 encryption, see Supported encryption algorithms in the Amazon S3 Encryption Client Developer Guide.

S3 tagging directive for CopyObject

The TaggingDirective property has been exposed as a public property of the CopyObjectRequest class, which is used by AmazonS3Client.CopyObject methods. This property corresponds to the Amazon S3 x-amz-tagging-directive parameter, as defined in the CopyObject action.

The tagging directive is no longer automatically set to COPY. If a developer doesn't specify a tagging directive, the S3 backend automatically assumes it is COPY, but if a developer explicitly sets the property to null, then the value isn't set at all.

The UseArnRegion property for S3 configuration

The UseArnRegion property of the Amazon.S3.AmazonS3Config class has been updated such that the AWS_S3_USE_ARN_REGION environment variable takes precedence over the s3_use_arn_region setting in the shared AWS config file. For more information about these variables and settings, see Settings reference in the AWS SDKs and Tools Reference Guide.

Leading slashes for the CopyObject and CopyPart methods

Leading slashes will no longer be trimmed for the Amazon S3 CopyObject and CopyPart methods. The DisableTrimmingLeadingSlash property has been removed from the CopyObjectRequest and CopyPartRequest classes.

The DoesS3BucketExist... methods

The obsolete DoesS3BucketExist and DoesS3BucketExistAsync methods have been removed from the AmazonS3Util class, which implements the ICoreAmazonS3 interface. These methods were removed because they always use HTTP. Use DoesS3BucketExistV2 and DoesS3BucketExistV2Async instead.

SDK always uses SigV4

Version 4 of the AWS SDK for .NET always uses AWS Signature Version 4 (SigV4) for signing requests. This change results in the following related changes:

The GetACL and PutACL methods

The GetACL and PutACL methods of the AmazonS3Client class have been marked as obsolete. To access the functionality of these methods, use the following new methods instead: GetBucketACL, PutBucketACL, GetObjectACL, and PutObjectACL.

Obsolete programing elements removed

A number of programming elements of the Amazon S3 implementation were removed from V4 of the SDK, including enumeration values, types, methods, namespaces, etc. These are listed below, if not already covered previously, along with potential steps that you can take to accommodate their removal.

The Amazon.Auth.AccessControlPolicy.ActionIdentifiers namespace

The Amazon.Auth.AccessControlPolicy.ActionIdentifiers namespace has been removed. This includes IAM action identifiers, which were defined in the IdentityandAccessManagementActionIdentifiers class. Code that uses these action identifiers should be changed to use string values of the action name.

For additional information, see Creating IAM managed policies from JSON and Overview of JSON policies in the IAM User Guide.

The ClientConfig class

The Amazon.Runtime.ClientConfig class is the base class of service client configuration classes like AmazonS3Config. The following programming elements have been removed from this class.

The Amazon.Runtime namespace

The Amazon.Runtime namespace was updated as follows:

BouncyCastle

The source copy of BouncyCastle has been removed from V4 of the SDK.

The StoredProfileSAMLCredentials class

The obsolete StoredProfileSAMLCredentials class in the Amazon.SecurityToken.SAML namespace has been removed. Use the FederatedAWSCredentials class in the Amazon.Runtime namespace instead.

The AWSSDKUtils class

The following methods have been removed from the AWSSDKUtils class: ResolveResourcePath, ProtectEncodedSlashUrlEncode, and ConvertToUnixEpochMilliSeconds.

The ProfileManager class

The obsolete ProfileManager class has been removed from the Amazon.Util namespace. Use the NetSDKCredentialsFile or SharedCredentialsFile class from the Amazon.Runtime.CredentialManagement namespace instead.

The AWSConfigs class

The following obsolete properties have been removed from the AWSConfigs class: Logging, ResponseLogging, and LogMetrics. Use the LoggingConfig property instead.

The ConditionFactory class

The method with the following signature has been removed from the ConditionFactory class: NewCondition(ConditionFactory.DateComparisonType, DateTime). Use the NewConditionUtc method instead.

Amazon CloudFront utilities

The obsolete Amazon.CloudFront.Util namespace and AmazonCloudFrontUtil class have been removed.

AWS IoT

In the ListPrincipalThingsResponse class, a legacy customization for a NextToken override has been removed in favor of pagination.

AWS Lambda

The following Invoke... methods of the AmazonLambdaClient class have been removed because the names were confusing.

Amazon SageMaker Runtime

Obsolete constructors for the PayloadPart class have been removed.