Configure the AWS Region

AWS Regions allow you to access AWS services that physically reside in a specific geographic region. This can be useful for redundancy and to keep your data and applications running close to where you and your users will access them.

To view the current list of all supported Regions and endpoints for each AWS service, see Service endpoints and quotas in the AWS General Reference. To view a list of existing Regional endpoints, see AWS service endpoints. To see detailed information about Regions, see Specify which AWS Regions your account can use.

You can create an AWS service client that goes to a particular Region. You can also configure your application with a Region that will be used for all AWS service clients. These two cases are explained next.

Create a service client with a particular Region

You can specify the Region for any of the AWS service clients in your application. Setting the Region in this way takes precedence over any global setting for that particular service client.

Existing Region

This example shows you how to instantiate an Amazon EC2 client in an existing Region. It uses defined RegionEndpoint fields.

using (AmazonEC2Client ec2Client = new AmazonEC2Client(RegionEndpoint.USWest2))
{
  // Make a request to EC2 in the us-west-2 Region using ec2Client
}

New Region using RegionEndpoint class

This example shows you how to construct a new Region endpoint by using RegionEndpoint.GetBySystemName.

var newRegion = RegionEndpoint.GetBySystemName("us-west-new");
using (var ec2Client = new AmazonEC2Client(newRegion))
{
  // Make a request to EC2 in the new Region using ec2Client
}

New Region using the service client configuration class

This example shows you how to use the ServiceURL property of the service client configuration class to specify the Region; in this case, using the AmazonEC2Config class.

This technique works even if the Region endpoint doesn't follow the regular Region endpoint pattern.

var ec2ClientConfig = new AmazonEC2Config
{
    // Specify the endpoint explicitly
    ServiceURL = "https://ec2.us-west-new.amazonaws.com"
};

using (var ec2Client = new AmazonEC2Client(ec2ClientConfig))
{
  // Make a request to EC2 in the new Region using ec2Client
}

Specify a Region for all service clients

There are several ways you can specify a Region for all of the AWS service clients that your application creates. This Region is used for service clients that aren't created with a particular Region.

The AWS SDK for .NET looks for a Region value in the following order.

Profiles

Set in a profile that your application or the SDK has loaded. For more information, see Credential and profile resolution.

Environment variables

Set in the AWS_REGION environment variable.

On Linux or macOS:

export AWS_REGION='us-west-2'

On Windows:

set AWS_REGION=us-west-2

Note

If you set this environment variable for the whole system (using export or setx), it affects all SDKs and toolkits, not just the AWS SDK for .NET.

AWSConfigs class

Set as an AWSConfigs.AWSRegion property.

AWSConfigs.AWSRegion = "us-west-2";
using (var ec2Client = new AmazonEC2Client())
{
  // Make request to Amazon EC2 in us-west-2 Region using ec2Client
}

Region resolution

If none of the methods described above are used to specify an AWS Region, the AWS SDK for .NET attempts to find a Region for the AWS service client to operate in.

Region resolution order

1. Application configuration files such as app.config and web.config.

2. Environment variables (AWS_REGION and AWS_DEFAULT_REGION).

3. A profile with the name specified by a value in AWSConfigs.AWSProfileName.

4. A profile with the name specified by the AWS_PROFILE environment variable.

5. The [default] profile.

6. Amazon EC2 instance metadata (if running on an EC2 instance).

If no Region is found, the SDK throws an exception stating that the AWS service client has no configured Region.

Special information about the China (Beijing) Region

To use services in the China (Beijing) Region, you must have an account and credentials that are specific to the China (Beijing) Region. Accounts and credentials for other AWS Regions won't work for the China (Beijing) Region. Likewise, accounts and credentials for the China (Beijing) Region won't work for other AWS Regions. For information about endpoints and protocols that are available in the China (Beijing) Region, see Beijing Region Endpoints.

Special information about new AWS services

New AWS services can be launched initially in a few Regions and then supported in other Regions. In these cases you don't need to install the latest SDK to access the new Regions for that service. You can specify newly added Regions on a per-client basis or globally, as shown earlier.