General Availability of AWS SDK for .NET V4.0

Version 4.0 of the AWS SDK for .NET has been released for general availability (GA). V4 has been in development for a little over a year in our SDK’s public GitHub repository with 13 previews being released. This new version contains performance improvements, consistency with other AWS SDKs, and bug and usability fixes that required a major version change. As part of being a GA AWS SDK, the V4 version of the AWS SDK for .NET will now have the same release cadence as the other GA AWS SDKs.

Updating to V4

The AWS SDK for .NET is the collection of NuGet packages with names that start with AWSSDK. For example AWSSDK.Core and AWSSDK.S3. Before updating to V4, check out the migration guide here. V4 was designed to be an evolutionary major version update with most applications not having to make any significant changes after recompiling.

It’s not possible to use both V3 and V4 packages within an application. Conflicts between the AWSSDK.Core package and service packages like AWSSDK.SQS will occur if you attempt to mix V3 and V4 packages. When updating to V4, ensure that all references to AWSSDK.* packages are updated to 4.0.0 or greater.

Prepare for null collection properties

As described in the migration guide, collection properties for types used for requests and responses to AWS services default to null instead of an empty collection as was done in V3. This change was implemented for performance and to allow the SDK and consumers of the SDK to distinguish between the state of a property not being set versus the property being set to an empty collection. The preview 1 blog post dives more deeply into the performance benefits of this change.

This change will likely be the most challenging one when updating to V4 because it’s a change in the runtime behavior. For example, in the code shown below, which lists Amazon EC2 security groups, a NullReferenceException might occur if there are no security groups. When using V4 of the SDK, a null check should be added before looping through the security groups.

var response = await client.DescribeSecurityGroupsAsync(request);

// This could cause a NullReferenceException if there are no security groups
foreach(var group in response.SecurityGroups)
{
    Console.WriteLine(group.GroupId);
}

When updating to V4, if you are unsure whether your application is compatible with this runtime behavior change, the static property called Amazon.AWSConfigs.InitializeCollections can be set to true. This changes the runtime behavior to be the same as in V3, which initializes collection properties to an empty collection. Setting this property to true can be a good first stage when updating to V4, but doing so will negate the performance improvements and your ability to determine if a collection property is set or empty by default.

Support timeframe for V3

We will continue to support V3 with the same release cadence for AWS service updates for a period of time. The major factor for how much time is the AWS Tools for PowerShell, which is built on the AWS SDK for .NET. A new major version of the AWS Tools for PowerShell that uses the V4 AWS SDK for .NET is currently in development with preview 3 released. Once the new major version of AWS Tools for PowerShell is released, both V3 of the AWS SDK for .NET and the previous AWS Tools for PowerShell major version will start a 6-month window of support. After the 6 months has passed, the V3 SDK will enter maintenance mode where only critical bugs and security issues will be addressed. A maintenance mode announcement will be made once the AWS Tools for PowerShell major version reaches GA and the 6-month window begins.

Conclusion

We encourage our AWS .NET community to update to V4 as soon as possible to get the performance improvements of the V4 SDK and to continue to get support for the SDK. For any questions or issues that arise while updating to the V4 SDK, please utilize the GitHub repository’s issue tracker or discussion forums to reach out to us. For other AWS .NET packages that depend on the AWS SDK for .NET, we are working to update those package to V4 of the SDK, which should help unblock anyone who is updating to V4. If you find dependencies that are preventing you from updating to V4, please let us know to see if we can help.

.NET