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

You can use the ClientConfig parameter to set the AWS Region for the command. The Region is set through the RegionEndpoint property. The AWS 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 AWS config file

5. The environment variables

6. The Amazon EC2 instance metadata, if enabled.