Today we are releasing a preview of AWS.Tools, the new modular AWS Tools for PowerShell.
We expect AWS.Tools to become the preferred variant of AWS Tools for PowerShell for most use cases.
AWS.Tools has the same capabilities of AWSPowerShell.NetCore and is compatible with modern platforms:
Windows PowerShell 5.1 when .NET Framework 4.7.2 (or newer) is installed
PowerShell 6.0-6.2 on Windows, Linux and macOS.
If you encounter any problems while using the new modules, please open a GitHub issue in this repository.
Useful things to know
Import times
The main difference when using the new AWS.Tools modules is the much lower download size and import times as well as memory usage. These are all effects of installing and importing just the cmdlets you need.
It is strongly suggested to avoid installing or explicitly importing all AWS.Tools modules by running Import-Module on all of them. PowerShell (especially older PowerShell versions) is much slower to load hundreds of small modules than loading a single big one.
If you have a use case for needing to manage all (or most) AWS services, we will continue to support the monolithic AWSPowerShell.NetCore.
Cool new features will come to AWS.Tools first.
Modules
Cmdlets for each AWS service are provided by a separate module:
Common AWS cmdlets like Set-AWSCredential or Set-AWSProxy are available in the AWS.Tools.Common module which is installed automatically when installing any other AWS.Tools module from the PowerShell Gallery.
We are not providing AWS.Tools modules for cmdlets that are superseded by a newer version:
If you notice any missing feature because of this, open an issue in this repository to let us know.
Exported cmdlets and module auto-import
Because AWSPowerShell and AWSPowerShell.NetCore contain almost 6000 (and growing) cmdlets, it is not possible to explicitly export all of them through the CmdletsToExport property in the module manifest. For this reason, on some versions of PowerShell, you need to explicitly run Import-Module AWSPowerShell before cmdlets are available to be used and suggested through TAB-completion.
Because each AWS.Tools module exports a much smaller number of cmdlets (and aliases), we were able to explicitly list all of the cmdlets in the module manifest. Once you install the module on your machine, the cmdlets will be available immediately. The necessary modules will be automatically loaded by PowerShell when you first use one of their cmdlets.
If you need to use one of the AWS SDK for .NET classes in your script before running any cmdlet, you will still need to import the corresponding module in order to make the .NET types available to the PowerShell session. For example:
Each time we release a new version of AWS.Tools, we will release a new version of each module. Each module will have the same version number.
Different versions of the AWS.Tools modules are not expected to be imported at the same time. We have built a protection that will throw a descriptive error when importing an AWS.Tools module, if there is any other AWS.Tools module already imported having a different version.
We suggest that, when updating or installing a new module, you also update all existing modules to the same version. This will help to keep everything consistent and avoid unexpected errors when running scripts.
Incompatibility between variants
Different variants of AWS Tools for PowerShell (AWSPowerShell, AWSPowerShell.NetCore and AWS.Tools) are not compatible with each other and cannot be imported at the same time. This was true even before we released AWS.Tools.
To avoid any confusion, we suggest that you install only a single variant on your machine. They all contain the same cmdlets anyway.
Starting with today release (3.3.563.0), all variants of AWS Tools for PowerShell will check upon importing if there is any other variant installed and will report a warning. They will also throw a descriptive error in case there is a different variant already imported in the current session. This will avoid other, more obscure, errors that could appear later during cmdlet execution.
Mandatory parameters
The new AWS.Tools modules now declare and enforce mandatory cmdlet parameters. For backward compatibility reasons we did not extend this feature to AWSPowerShell or the AWSPowerShell.NetCore modules.
When an AWS Service declares that a parameter of an API is required, PowerShell will prompt you for the corresponding cmdlet parameter if it is missing during invocation.
Please open an issue in this repository if you encounter any parameter incorrectly marked as mandatory or any other problem with mandatory parameters.
AWS Lambda functions
If you are using AWS Tools for PowerShell in AWS Lambda, you can now switch to the new AWS.Tools modules. They will help lower cold start time and memory usage.
You will need to change the #Requires statement from AWSPowerShell.NetCore to the AWS.Tools module you wish to use (e.g. AWS.Tools.S3).
You will also need to add an extra #Requires statement to use AWS.Tools.Common. We will remove this requirement in the future by supporting automatic identification of the module dependencies.
How to keep updated on changes to the preview modules
We will keep this GitHub issue updated about new features, fixes and any other important changes coming to the modular AWS Tools for PowerShell.
How to provide feedback
Thank you for helping us making sure that the new modular AWS Tools for PowerShell is ready for prime time! Please provide feedback by opening an issue in this repository.
Today we are releasing a preview of AWS.Tools, the new modular AWS Tools for PowerShell. We expect AWS.Tools to become the preferred variant of AWS Tools for PowerShell for most use cases.
In order to manage each AWS service, install the corresponding module (e.g. AWS.Tools.EC2, AWS.Tools.S3, etc.) from the PowerShell Gallery .
AWS.Tools has the same capabilities of AWSPowerShell.NetCore and is compatible with modern platforms:
If you encounter any problems while using the new modules, please open a GitHub issue in this repository.
Useful things to know
Import times
The main difference when using the new AWS.Tools modules is the much lower download size and import times as well as memory usage. These are all effects of installing and importing just the cmdlets you need.
It is strongly suggested to avoid installing or explicitly importing all AWS.Tools modules by running Import-Module on all of them. PowerShell (especially older PowerShell versions) is much slower to load hundreds of small modules than loading a single big one.
If you have a use case for needing to manage all (or most) AWS services, we will continue to support the monolithic AWSPowerShell.NetCore.
Cool new features will come to AWS.Tools first.
Modules
Cmdlets for each AWS service are provided by a separate module:
Common AWS cmdlets like Set-AWSCredential or Set-AWSProxy are available in the AWS.Tools.Common module which is installed automatically when installing any other AWS.Tools module from the PowerShell Gallery.
We are not providing AWS.Tools modules for cmdlets that are superseded by a newer version:
If you notice any missing feature because of this, open an issue in this repository to let us know.
Exported cmdlets and module auto-import
Because AWSPowerShell and AWSPowerShell.NetCore contain almost 6000 (and growing) cmdlets, it is not possible to explicitly export all of them through the
CmdletsToExportproperty in the module manifest. For this reason, on some versions of PowerShell, you need to explicitly runImport-Module AWSPowerShellbefore cmdlets are available to be used and suggested through TAB-completion.Because each AWS.Tools module exports a much smaller number of cmdlets (and aliases), we were able to explicitly list all of the cmdlets in the module manifest. Once you install the module on your machine, the cmdlets will be available immediately. The necessary modules will be automatically loaded by PowerShell when you first use one of their cmdlets.
If you need to use one of the AWS SDK for .NET classes in your script before running any cmdlet, you will still need to import the corresponding module in order to make the .NET types available to the PowerShell session. For example:
Versioning
Each time we release a new version of AWS.Tools, we will release a new version of each module. Each module will have the same version number.
Different versions of the AWS.Tools modules are not expected to be imported at the same time. We have built a protection that will throw a descriptive error when importing an AWS.Tools module, if there is any other AWS.Tools module already imported having a different version.
We suggest that, when updating or installing a new module, you also update all existing modules to the same version. This will help to keep everything consistent and avoid unexpected errors when running scripts.
Incompatibility between variants
Different variants of AWS Tools for PowerShell (AWSPowerShell, AWSPowerShell.NetCore and AWS.Tools) are not compatible with each other and cannot be imported at the same time. This was true even before we released AWS.Tools.
To avoid any confusion, we suggest that you install only a single variant on your machine. They all contain the same cmdlets anyway.
Starting with today release (3.3.563.0), all variants of AWS Tools for PowerShell will check upon importing if there is any other variant installed and will report a warning. They will also throw a descriptive error in case there is a different variant already imported in the current session. This will avoid other, more obscure, errors that could appear later during cmdlet execution.
Mandatory parameters
The new AWS.Tools modules now declare and enforce mandatory cmdlet parameters. For backward compatibility reasons we did not extend this feature to AWSPowerShell or the AWSPowerShell.NetCore modules.
When an AWS Service declares that a parameter of an API is required, PowerShell will prompt you for the corresponding cmdlet parameter if it is missing during invocation.
Please open an issue in this repository if you encounter any parameter incorrectly marked as mandatory or any other problem with mandatory parameters.
AWS Lambda functions
If you are using AWS Tools for PowerShell in AWS Lambda, you can now switch to the new AWS.Tools modules. They will help lower cold start time and memory usage.
You will need to change the
#Requiresstatement fromAWSPowerShell.NetCoreto the AWS.Tools module you wish to use (e.g. AWS.Tools.S3).You will also need to add an extra
#Requiresstatement to use AWS.Tools.Common. We will remove this requirement in the future by supporting automatic identification of the module dependencies.So you will need to change the line
to
How to keep updated on changes to the preview modules
We will keep this GitHub issue updated about new features, fixes and any other important changes coming to the modular AWS Tools for PowerShell.
How to provide feedback
Thank you for helping us making sure that the new modular AWS Tools for PowerShell is ready for prime time! Please provide feedback by opening an issue in this repository.