AWS SDK for .NET
Developer Guide

This documentation is for version 2.0 of the AWS SDK for .NET. For the latest version, see the AWS SDK for .NET Developer Guide for version 3.

Configuration Files Reference for AWS SDK for .NET

You can use a .NET project's App.config or Web.config file to specify certain AWS settings such as AWS credentials, logging options, AWS service endopoints, and AWS regions, as well as certain settings for AWS services such as Amazon DynamoDB, Amazon EC2, and Amazon S3. The following information describes how to properly format an App.config or Web.config file to specify these types of settings.

Note

Although you can continue to use the <appSettings> element in an App.config or Web.config file to specify AWS settings, we recommend that you use the <configSections> and <aws> elements as described later in this topic. (For more information about the <appSettings> element, see the <appSettings> element examples in Configuring Your AWS SDK for .NET Application.)

Although you can continue to use the following AWSConfigs class properties in a code file to specify AWS settings, the following properties are deprecated and may not be supported in future releases:

  • DynamoDBContextTableNamePrefix
  • EC2UseSignatureVersion4
  • LoggingOptions
  • LogMetrics
  • ResponseLoggingOption
  • S3UseSignatureVersion4

In general, we recommend that instead of using AWSConfigs class properties in a code file to specify AWS settings, you should use the <configSections> and <aws> elements in an App.config or Web.config file to specify AWS settings, as described later in this topic. (For more information about the preceding properties, see the AWSConfigs code examples in Configuring Your AWS SDK for .NET Application.)

Declaring an AWS Settings Section#

You specify AWS settings in an App.config or Web.config file from within the <aws> element. Before you can begin using the <aws> element, you must create a <section> element (which is a child element of the <configSections> element) and set its name attribute to aws and its type attribute to Amazon.AWSSection, AWSSDK, as shown in the following example:

<?xml version="1.0"?>
<configuration>
  ...
  <configSections>
    <section name="aws" type="Amazon.AWSSection, AWSSDK"/>
  </configSections>
  <aws>
    <!-- Add your desired AWS settings declarations here. -->
  </aws>
  ...
</configuration>

Note that the Visual Studio Editor does not provide automatic code completion (IntelliSense) for either the <aws> element or its child elements.

To assist you in creating a correctly-formatted version of the <aws> element, call the Amazon.AWSConfigs.GenerateConfigTemplate method. This outputs a canonical version of the <aws> element as a pretty-printed string, which you can adapt to your needs. The following sections describe the <aws> element's attributes and child elements.

Allowed Elements#

The following is a list of the logical relationships among the allowed elements in an AWS settings section. You can generate the latest version of this list by calling the Amazon.AWSConfigs.GenerateConfigTemplate method, which outputs a canonical version of the <aws> element as a string that you can adapt to your needs.

...
<aws
  endpointDefinition="string value"
  region="string value"
  profileName="string value"
  profilesLocation="string value">
  <logging
    logTo="None, Log4Net, SystemDiagnostics"
    logResponses="Never | OnError | Always"
    logMetrics="true | false"
    logMetricsFormat="Standard | JSON"
    logMetricsCustomFormatter="NameSpace.Class, Assembly" />
  <dynamoDB
    conversionSchema="V1 | V2">
    <dynamoDBContext
      tableNamePrefix="string value">
      <alias
        fromTable="string value"
        toTable="string value" />
      <map
        type="NameSpace.Class, Assembly"
        targetTable="string value">
        <property
          name="string value"
          attribute="string value"
          ignore="true | false"
          version="true | false"
          converter="NameSpace.Class, Assembly" />
      </map>
    </dynamoDBContext>
  </dynamoDB>
  <s3
    useSignatureVersion4="true | false" />
  <ec2
    useSignatureVersion4="true | false" />
  <proxy
    host="string value"
    port="1234"
    username="string value"
    password="string value" />
</aws>
...

Elements Reference#

The following is a list of the elements that are allowed in an AWS settings section. For each element, its allowed attributes and parent-child elements are listed.

alias#

The <alias> element represents a single item in a collection of one or more from-table to to-table mappings that specifies a different table than one that is configured for a type. (This element maps to an instance of the Amazon.Util.TableAlias class from the Amazon.AWSConfigs.DynamoDBConfig.Context.TableAliases property in the AWS SDK for .NET.) Remapping is done before applying a table name prefix. This element can include the following attributes:

fromTable
The from-table portion of the from-table to to-table mapping. (This attribute maps to the Amazon.Util.TableAlias.FromTable property in the AWS SDK for .NET.)
toTable
The to-table portion of the from-table to to-table mapping. (This attribute maps to the Amazon.Util.TableAlias.ToTable property in the AWS SDK for .NET.)

The parent of the <alias> element is the <dynamoDBContext> element.

The <alias> element contains no child elements.

The following is an example of the <alias> element in use:

...
<alias
  fromTable="Studio"
  toTable="Studios" />
...

aws#

The <aws> element represents the top-most element in an AWS settings section. This element can include the following attributes:

endpointDefinition
The absolute path to a custom configuration file that defines the desired AWS regions and endpoints to use. (This attribute maps to the Amazon.AWSConfigs.EndpointDefinition property in the AWS SDK for .NET.)
profileName
The desired profile name for stored AWS credentials that will be used to make service calls. (This attribute maps to the Amazon.AWSConfigs.AWSProfileName property in the AWS SDK for .NET.)
profilesLocation
The absolute path to the location of the credentials file shared with other AWS SDKs. By default, the credentials file is stored in the .aws directory in the current user's home directory. (This attribute maps to the Amazon.AWSConfigs.AWSProfilesLocation property in the AWS SDK for .NET.)
region
The default AWS region ID for clients that have not explicitly specified a region. (This attribute maps to the Amazon.AWSConfigs.AWSRegion property in the AWS SDK for .NET.)

The <aws> element has no parent element.

The <aws> element can include the following child elements:

  • <dynamoDB>
  • <ec2>
  • <logging>
  • <proxy>
  • <s3>

The following is an example of the <aws> element in use:

...
<aws
  endpointDefinition="C:\Configs\endpoints.xml"
  region="us-west-2"
  profileName="development"
  profilesLocation="C:\Configs">
  ...
</aws>
...

dynamoDB#

The <dynamoDB> element represents a collection of settings for Amazon DynamoDB. This element can include the conversionSchema attribute, which represents the version to use for converting between .NET and DynamoDB objects. Allowed values include V1 and V2. (This attribute maps to the Amazon.DynamoDBv2.DynamoDBEntryConversion class in the AWS SDK for .NET.) For more information, see DynamoDB Series - Conversion Schemas.

The parent of the <dynamoDB> element is the element.

The <dynamoDB> element can include the child element.

The following is an example of the <dynamoDB> element in use:

...
<dynamoDB
  conversionSchema="V2">
  ...
</dynamoDB>
...

dynamoDBContext#

The <dynamoDBContext> element represents a collection of Amazon DynamoDB context-specific settings. This element can include the tableNamePrefix attribute, which represents the default table name prefix that the DynamoDB context will use if it is not manually configured. (This attribute maps to the Amazon.Util.DynamoDBContextConfig.TableNamePrefix property from the Amazon.AWSConfigs.DynamoDBConfig.Context.TableNamePrefix property in the AWS SDK for .NET.) For more information, see Enhancements to the DynamoDB SDK.

The parent of the <dynamoDBContext> element is the element.

The <dynamoDBContext> element can include the following child elements:

  • <alias> (one or more instances)
  • <map> (one or more instances)

The following is an example of the <dynamoDBContext> element in use:

...
<dynamoDBContext
  tableNamePrefix="Test-">
  ...
</dynamoDBContext>
...

ec2#

The <ec2> element represents a collection of Amazon EC2 settings. This element can include the useSignatureVersion4 attribute, which specifies whether Signature Version 4 signing will be used for all requests (true) or whether Signature Version 4 signing will not be used for all requests (false, the default). (This attribute maps to the Amazon.Util.EC2Config.UseSignatureVersion4 property from the Amazon.AWSConfigs.EC2Config.UseSignatureVersion4 property in the AWS SDK for .NET.)

The parent of the <ec2> element is the element.

The <ec2> element contains no child elements.

The following is an example of the <ec2> element in use:

...
<ec2
  useSignatureVersion4="true" />
...

logging#

The <logging> element represents a collection of settings for response logging and performance metrics logging. This element can include the following attributes:

logMetrics
Whether performance metrics will be logged for all clients and configurations (true); otherwise, false. (This attribute maps to the Amazon.Util.LoggingConfig.LogMetrics property from the Amazon.AWSConfigs.LoggingConfig.LogMetrics property in the AWS SDK for .NET.)
logMetricsCustomFormatter
The data type and assembly name of a custom formatter for logging metrics. (This attribute maps to the Amazon.Util.LoggingConfig.LogMetricsCustomFormatter property from the Amazon.AWSConfigs.LoggingConfig.LogMetricsCustomFormatter property in the AWS SDK for .NET.)
logMetricsFormat

The format in which the logging metrics are presented. (This attribute maps to the Amazon.Util.LoggingConfig.LogMetricsFormat property from the Amazon.AWSConfigs.LoggingConfig.LogMetricsFormat property in the AWS SDK for .NET.) Allowed values include

JSON
Use JSON format.
Standard
Use the default format.
logResponses

When to log service responses. (This attribute maps to the Amazon.Util.LoggingConfig.LogResponses property from the Amazon.AWSConfigs.LoggingConfig.LogResponses property in the AWS SDK for .NET.) Allowed values include:

Always
Always log service responses.
Never
Never log service responses.
OnError
Log service responses only when there are errors.
logTo

Where to log to. (This attribute maps to the A:code:mazon.Util.LoggingConfig.LogTo property from the Amazon.AWSConfigs.LoggingConfig.LogTo property in the AWS SDK for .NET.)

Allowed values include:

Log4Net
Log to log4net.
None
Completely disable logging.
SystemDiagnostics
Log to System.Diagnostics.

The parent of the <logging> element is the element.

The <logging> element contains no child elements.

The following is an example of the <logging> element in use:

...
<logging
  logTo="SystemDiagnostics"
  logResponses="OnError"
  logMetrics="true"
  logMetricsFormat="JSON"
  logMetricsCustomFormatter="MyLib.Util.MyMetricsFormatter, MyLib" />
...

map#

The <map> element represents a single item in a collection of type-to-table mappings from .NET types to DynamoDB tables. (This element maps to an instance of the Amazon.Util.TypeMapping class from the Amazon.AWSConfigs.DynamoDBConfig.Context.TypeMappings property in the AWS SDK for .NET.) For more information, see Enhancements to the DynamoDB SDK. This element can include the following attributes:

targetTable
The DynamoDB table to which the mapping applies. (This attribute maps to the Amazon.Util.TypeMapping.TargetTable property in the AWS SDK for .NET.)
type
The type and assembly name to which the mapping applies. (This attribute maps to the Amazon.Util.TypeMapping.Type property in the AWS SDK for .NET.)

The parent of the <map> element is the element.

The <map> element can include one or more instances of the child element.

The following is an example of the <map> element in use:

...
<map
  type="SampleApp.Models.Movie, SampleDLL"
  targetTable="Movies">
  ...
</map>
...

property#

The <property> element represents a DynamoDB property. (This element maps to an instance of the Amazon.Util.PropertyConfig class from the Amazon.Util.TypeMapping.AddProperty method in the AWS SDK for .NET.) For more information, see Enhancements to the DynamoDB SDK and DynamoDB Attributes. This element can include the following attributes:

attribute
The name of an attribute for the property, such as the name of a range key. (This attribute maps to the Amazon.Util.PropertyConfig.Attribute property in the AWS SDK for .NET.)
converter
The type of converter that should be used for this property. (This attribute maps to the Amazon.Util.PropertyConfig.Converter property in the AWS SDK for .NET.)
ignore
Whether the associated property should be ignored (true); otherwise, false. (This attribute maps to the Amazon.Util.PropertyConfig.Ignore property in the AWS SDK for .NET.)
name
The name of the property. (This attribute maps to the Amazon.Util.PropertyConfig.Name property in the AWS SDK for .NET.)
version
Whether this property should store the item version number ( true ); otherwise, false. (This attribute maps to the Amazon.Util.PropertyConfig.Version property in the AWS SDK for .NET.)

The parent of the <property> element is the element.

The <property> element contains no child elements.

The following is an example of the <property> element in use:

...
<property
  name="Rating"
  converter="SampleApp.Models.RatingConverter, SampleDLL" />
...

proxy#

The <proxy> element represents settings for configuring a proxy for the the SDK to use. This element can include the following attributes:

host
The host name or IP address of the proxy server. (This attributes maps to the Amazon.Util.ProxyConfig.Host property from the Amazon.AWSConfigs.ProxyConfig.Host property in the AWS SDK for .NET.)
password
The password to authenticate with the proxy server. (This attributes maps to the Amazon.Util.ProxyConfig.Password property from the Amazon.AWSConfigs.ProxyConfig.Password property in the AWS SDK for .NET.)
port
The port number of the proxy. (This attributes maps to the Amazon.Util.ProxyConfig.Port property from the Amazon.AWSConfigs.ProxyConfig.Port property in the AWS SDK for .NET.)
username
The username to authenticate with the proxy server. (This attributes maps to the Amazon.Util.ProxyConfig.Username property from the mazon.AWSConfigs.ProxyConfig.Username property in the AWS SDK for .NET.)

The parent of the <proxy> element is the element.

The <proxy> element contains no child elements.

The following is an example of the <proxy> element in use:

...
<proxy
  host="192.0.2.0"
  port="1234"
  username="My-Username-Here"
  password="My-Password-Here" />
...

s3#

The <s3> element represents a collection of Amazon S3 settings. This element can include the useSignatureVersion4 attribute, which specifies whether Signature Version 4 signing will be used for all requests (true) or whether Signature Version 4 signing will not be used for all requests (false, the default). (This attribute maps to the Amazon.AWSConfigs.S3Config.UseSignatureVersion4 property in the AWS SDK for .NET.)

The parent of the <s3> element is the element.

The <s3> element contains no child elements.

The following is an example of the <s3> element in use:

...
<s3
  useSignatureVersion4="true" />
...