The AWS Tools for PowerShell version 5 (V5) is in preview, therefore this content is subject to change. For information about breaking changes, installation, and migration, see the migration topic. For released content, see the version 4 user guide instead.

Migrating from AWS Tools for PowerShell version 4 to version 5

AWS 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 AWS Tools for PowerShell, and how to install and test the new version, see the blog post Preview 1 of AWS 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 AWS Tools for PowerShell, AWSPowerShell, the module's minimum supported PowerShell version has been updated to 5.1. This is to match the AWS 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 AWS SDK for .NET have been updated to use that SDK's new nullable changes. For example, properties of type int have been changed to Nullable[int]. For additional information including examples, see the blog post Preview 1 of AWS Tools for PowerShell V5 and the migration content for Value types in the AWS 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 AWS SDK for .NET Developer Guide.

Pipelining and $AWSHistory

In versions of the AWS Tools for PowerShell prior to V4, a session variable called $AWSHistory was introduced that maintains a record of AWS 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.

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 AWS 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 AWS 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 AWS 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 AWS 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 AWS 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

The following programming elements have been removed from V5 of the Tools for PowerShell: