Migrating from Amazon Tools for PowerShell version 4 to version 5

Amazon Tools for PowerShell version 5 (V5) has breaking changes, which could cause your existing scripts to stop working. This topic describes the breaking changes in V5 and possible work that you might need to do to migrate your environment or code from V4.

For additional information about noteworthy changes in the Amazon Tools for PowerShell, and how to install and test the new version, see the blog post Preview 1 of Amazon Tools for PowerShell V5 and the V5 Development Tracker issue in GitHub. In the V5 Development Tracker issue, in addition to the list of breaking changes, be sure to look at the details of each preview.

Minimum PowerShell version

For the legacy Windows-specific, single, large-module version of the Amazon Tools for PowerShell, AWSPowerShell, the module's minimum supported PowerShell version has been updated to 5.1. This is to match the Amazon SDK for .NET new minimum version of .NET Framework 4.7.2.

For more information about the AWSPowerShell module, see Installing on Windows.

Nullable value types

The types adopted from the Amazon SDK for .NET have been updated to use the SDK's new nullable changes. For example, properties of type int have been changed to Nullable[int]. This change doesn't affect how input parameter values are specified for AWS cmdlets because those value type parameters were already modeled as nullable. However, 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 demonstrates the behavior in V4 of the Tools for PowerShell. In this example, the MissingMeta property is set to 0 because that is the default value of type int.

# In V4
PS > 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 demonstrates the behavior in V5 of the Tools for PowerShell. In this example, the MissingMeta property is set to $null.

# In V5
PS > 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 because 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.

For some of these types, the following examples show how to update code written for V4 that checks if nothing was returned:

#Type int:
# In V4, if you were checking whether an int is 0...
if($s3Metadata.MissingMeta -eq 0){}

# In V5, check if the int is null instead:
if($s3Metadata.MissingMeta -eq $null) {}

# Type datetime:
# In V4, if you were checking whether a datetime is '0001-01-01'...
if($s3Metadata.ObjectLockRetainUntilDate -eq '0001-01-01'){}

# In V5, check if the datetime is null instead:
if($s3Metadata.ObjectLockRetainUntilDate -eq $null){}

# Type boolean:
# In V4, if you were checking whether a boolean is $false...
if($s3Metadata.BucketKeyEnabled -eq $false){}

# In V5, check if the boolean is null instead:
if($s3Metadata.BucketKeyEnabled -eq $null)

Since the Amazon Tools for PowerShell rely on the Amazon SDK for .NET, it might be useful to examine how similar changes affected version 4 of the SDK. To find this information, see the Value types migration content in the Amazon SDK for .NET Developer Guide.

Collections

Some cmdlet output has been changed to return $null instead of empty collections of type List or Dictionary. For additional information, including how to revert to legacy behavior, see the migration content for Collections in the Amazon SDK for .NET Developer Guide.

DateTime versus UTC DateTime

Some V4 cmdlets define DateTime parameters that are obsolete, as well as alternative UTC DateTime parameters. These obsolete DateTime parameters have been removed from the V5 cmdlets, and the name of the UTC DateTime parameters have been changed to the original name of the non-UTC DateTime parameters.

The following are some examples of cmdlets for which this change has been implemented.

The following is a complete list of the cmdlets that are affected by this change.

Pipelining and $AWSHistory

In versions of the Amazon Tools for PowerShell prior to V4, a session variable called $AWSHistory was introduced that maintains a record of Amazon cmdlet invocations and the service responses that were received for each invocation.

In V4 of the Tools for PowerShell, this session variable was deprecated in favor of the -Select * parameter and argument, which can be used to return the entire service response. The -Select * parameter is described in Pipelining, output, and iteration.

In V5 of the Tools for PowerShell, the $AWSHistory session variable has been removed completely. As a consequence, the Clear-AWSHistory and Set-AWSHistoryConfiguration cmdlets have also been removed.

The -PassThru parameter

The -PassThru parameter has been removed. When a cmdlet doesn't return any output by default, users can request a returned parameter value by using -Select ^ParameterName. For additional details and examples, see the blog post Preview 1 of Amazon Tools for PowerShell V5.

Some DynamoDB cmdlets moved and renamed

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

Logging of sensitive information

Logging behavior has been changed so that potentially sensitive information is less likely to be included in cmdlet output, especially in CI/CD situations. For more information and instructions about how to revert to V4 behavior, see Logging of sensitive information.

Credential and profile resolution

The Amazon Tools for PowerShell have been updated to use certain environment variables when resolving credentials for a cmdlet: AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. In addition, there have been some changes in the resolution order for credentials and profiles. For more information, see Credential and profile resolution.

Consistent Auto-Iteration

All paginated cmdlets have been updated to auto-iterate all data by default. You can revert this behavior by using the Set-AWSAutoIterationMode cmdlet. If you run Set-AWSAutoIterationMode -IterationMode v4, operations that auto-iterated in v4 will still auto-iterate, but the rest will revert to manual iteration. To determine what mode auto-iteration is set to, use the Get-AWSAutoIterationMode cmdlet.

S3 cmdlets deprecated and replaced

For Amazon S3, the Get-S3ACL and Set-S3ACL cmdlets have been deprecated. Use the following new cmdlets instead: Get-S3BucketACL, Set-S3BucketACL, Get-S3ObjectACL, Set-S3ObjectACL.

Cleaning and trimming S3 key parameters

Certain Amazon S3 cmdlets accept parameters named Key and KeyPrefix. V4 of the Amazon Tools for PowerShell would clean and trim these parameters in the following ways: remove leading spaces, forward slashes ("/"), and backslashes ("\"), convert all other backslashes to forward slashes, and remove trailing spaces. In V5 of the Tools for PowerShell, this is no longer the default behavior. You can revert to this behavior by specifying the -EnableLegacyKeyCleaning parameter.

This information applies to the following cmdlets:

Interactive session capabilities

Interactive session capabilities have been added to the Start-SSMSession cmdlet, which aligns with the Amazon CLI behavior. If you need legacy behavior, include the -DisablePluginInvocation parameter in the Start-SSMSession command. For example:

Start-SSMSession -Target 'i-1234567890abcdef0' -DisablePluginInvocation

CloudWatch alarms

The Get-CWAlarm cmdlet has been updated to return both metric and composite Amazon CloudWatch alarms by default. To limit the output to either metric or composite alarms, you must specify the -AlarmType parameter: Get-CWAlarm -AlarmType 'MetricAlarms' or Get-CWAlarm -AlarmType 'CompositeAlarms', respectively.

LitJson

The Amazon Tools for PowerShell have been updated to use System.Text.Json instead of LitJson for serialization. LitJson has been removed from V5 of the tools.

Programming elements that were removed

A number of programming elements have been removed from V5 of the Tools for PowerShell. These are listed below, if not already covered previously, along with potential steps that you can take to accommodate their removal, if any.