Using the ClientConfig parameter in cmdlets - Amazon Tools for PowerShell
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using the ClientConfig parameter in cmdlets

The ClientConfig parameter can be used to specify certain configuration settings when you connect to a service. Most of the possible properties of this parameter are defined in the Amazon.Runtime.ClientConfig class, which is inherited into the APIs for Amazon services. For an example of simple inheritance, see the Amazon.Keyspaces.AmazonKeyspacesConfig class. In addition, some services define additional properties that are appropriate only for that service. For an example of additional properties that have been defined, see the Amazon.S3.AmazonS3Config class, specifically the ForcePathStyle property.

Using the ClientConfig parameter

To use the ClientConfig parameter, you can specify it on the command line as a ClientConfig object or use PowerShell splatting to pass a collection of parameter values to a command as a unit. These methods are shown in the following examples. The examples assume that the AWS.Tools.S3 module has been installed and imported, and that you have a [default] credentials profile with appropriate permissions.

Defining a ClientConfig object

$s3Config = New-Object -TypeName Amazon.S3.AmazonS3Config $s3Config.ForcePathStyle = $true $s3Config.Timeout = [TimeSpan]::FromMilliseconds(150000) Get-S3Object -BucketName <BUCKET_NAME> -ClientConfig $s3Config

Adding ClientConfig properties by using PowerShell splatting

$params=@{ ClientConfig=@{ ForcePathStyle=$true Timeout=[TimeSpan]::FromMilliseconds(150000) } BucketName="<BUCKET_NAME>" } Get-S3Object @params

Using an undefined property

When using PowerShell splatting, if you specify a ClientConfig property that doesn't exist, the Amazon Tools for PowerShell doesn't detect the error until runtime, at which time it returns an exception. Modifying the example from above:

$params=@{ ClientConfig=@{ ForcePathStyle=$true UndefinedProperty="Value" Timeout=[TimeSpan]::FromMilliseconds(150000) } BucketName="<BUCKET_NAME>" } Get-S3Object @params

This example produces an exception similar to the following:

Cannot bind parameter 'ClientConfig'. Cannot create object of type "Amazon.S3.AmazonS3Config". The UndefinedProperty property was not found for the Amazon.S3.AmazonS3Config object.

Specifying the Amazon Web Services Region

You can use the ClientConfig parameter to set the Amazon Web Services Region for the command. The Region is set through the RegionEndpoint property. The Amazon Tools for PowerShell calculates the Region to use according to the following precedence:

  1. The -Region parameter

  2. The Region passed in the ClientConfig parameter

  3. The PowerShell session state

  4. The shared Amazon config file

  5. The environment variables

  6. The Amazon EC2 instance metadata, if enabled.