Preview 1 of AWS Tools for PowerShell V5

This blog was co-authored by Afroz Mohammed and Jonathan Nunn, Software Developers on the AWS PowerShell team.

In August 2024, the AWS Tools for PowerShell team announced the upcoming release of the AWS Tools for PowerShell V5. The first preview release of V5 is now available.

Preview 1 of the AWS Tools for PowerShell V5 uses preview 4 of the AWS SDK for .NET V4.

Breaking Changes

Nullable Value Types

Version 4 of the AWS SDK for .NET changes properties on request and response classes that use value types like int, bool, and DateTime to use the nullable version of each type. For example, the AWS SDK for .NET V4 changes the type Int to Nullable[int].

The prior version of the AWS Tools for PowerShell, which was V4, modeled value type parameters as nullable; therefore, introducing nullable value types will not affect how parameter values are specified for AWS cmdlets. However, introducing nullable types for cmdlet output is a breaking change because properties within the cmdlet output will contain $null instead of the various default values for types.

The following example shows the behavior in V4 where the MissingMeta property is set to 0 because this is the default value of type int.

# In V4
➜ Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket  -Key 'test' |
> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled

LastModified          MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled
------------          ----------- ------------------------- ----------------
8/29/2023 10:20:44 PM           0 1/1/0001 12:00:00 AM  

The following example shows the behavior in V5 where the MissingMeta property is set to $null.

# In V5
➜ Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' |
> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled

LastModified          MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled
------------          ----------- ------------------------- ----------------
8/29/2023 10:20:44 PM

In most cases, no code change is necessary since PowerShell has implicit conversion from nullable value types to non-nullable value types. However, this is a breaking change for comparison-logic code that checks explicitly for a default value of a nullable value type. Comparison logic that checks for the default value of a non-nullable type must be modified to check for $null.

The following example shows how to update code written for V4 that checks if nothing was returned for an int.

# (V4) Instead of checking if an int is 0,
if($s3Metadata.MissingMeta -eq 0){}

# (V5) Code should check if an int is null.
if($s3Metadata.MissingMeta -eq $null) {}

The following example shows how to adjust code written for V4 that checks if nothing was returned for a DateTime.

# (V4) Instead of checking if a datetime is '0001-01-01',
if($s3Metadata.ObjectLockRetainUntilDate -eq '0001-01-01'){}

# (V5) Code should check if a datetime is null.
if($s3Metadata.ObjectLockRetainUntilDate -eq $null){}

The following example shows how to adjust code written for V4 that checks if nothing was returned for a boolean.

# (V4) Instead of checking if a boolean is $false,
if($s3Metadata.BucketKeyEnabled -eq $false){}
# (V5) Code should check if a boolean is null.
if($s3Metadata.BucketKeyEnabled -eq $null)

Returning $null instead of empty collections

By default, the AWS SDK for .NET V4 returns null instead of initializing collections of type List or Dictionary to empty collections. Preview 1 of the AWS Tools for PowerShell V5 was also changed to return $null instead of empty collections.

The $AWSHistory session variable and related cmdlets have been removed

Previously, the AWS Tools for PowerShell offered a session variable named $AWSHistory to retroactively retrieve a service response in its entirety. The session variable $AWSHistory as well as the related cmdlets Clear-AWSHistory and Set-AWSHistoryConfiguration have been removed in V5. Instead, customers can invoke cmdlets using -Select * to return entire service responses. For more information, see Pipelining, output, and iteration in the AWS Tools for PowerShell in the user guide.

The -PassThru switch parameter has been removed

The -PassThru switch parameter has been removed. When a cmdlet does not return any output by default, users can opt-in to return a parameter value using -Select ^ParameterName.

The following example shows the behavior in V4 where the -PassThru parameter is specified.

New-KINStream -StreamName "mystream" -ShardCount 1 -PassThru

The following example shows the behavior in V5 where the -Select parameter is specified to return the StreamName parameter value.

New-KINStream -StreamName "mystream" -ShardCount 1 -Select ^StreamName

Revised Cmdlets

DynamoDB Cmdlets

The Get-DDBStream and Get-DDBStreamList cmdlets have been moved from the DynamoDBV2 module to a new module called DynamoDBStreams and have been renamed to Get-DDBSStream and Get-DDBSStreamList.

S3 Cmdlets

New S3 cmdlets have been created including Get-S3BucketACL, Set-S3BucketACL, Get-S3ObjectACL, Set-S3ObjectACL, and the cmdlets Get-S3ACL and Set-S3ACL have been deprecated.

Conclusion

The AWS Tools for PowerShell V5 won’t be released with the same cadence as V4 until we get closer to GA. There will be some period of dual support of V4 and V5 after V5 reaches GA, which will be based on how we see the adoption of V5 go. Our hope is that the upgrade from V4 to V5 is easy enough for users to do quickly so that we can focus on more improvements to V5.

We ask customers of the AWS Tools for PowerShell to try out the preview of V5 and let us know what you think. You can monitor our progress, including upcoming features, by following the pinned GitHub issue on our repository. Please provide feedback by opening issues and discussions on the AWS Tools for PowerShell GitHub repository.