` element with an `Include` attribute for each required assembly.
For Amazon S3, for example, you would add the following lines to your project's `.csproj` file.
**On Linux and macOS:**
```
```
**On Windows:**
```
```
1. Save you project's `.csproj` file.
------
#### [ Windows with Visual Studio and .NET Core ]
1. In Visual Studio, load your project and open **Project**, **Add Reference**.
1. Choose the **Browse** button on the bottom of the dialog box. Navigate to your project's folder and the subfolder that you copied the required DLL files to (`AwsAssemblies`, for example).
1. Select all the DLL files, choose **Add**, and choose **OK**.
1. Save your project.
------
# Setting the AWS Region for the AWS SDK for .NET
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](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*. To view a list of existing Regional endpoints, see [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). To see detailed information about Regions, see [Specify which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html).
You can create an AWS service client that goes to a [particular Region](#per-client). You can also configure your application with a Region that will be used for [all AWS service clients](#globally). 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](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/EC2/TEC2Client.html) in an existing Region. It uses defined [RegionEndpoint](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TRegionEndpoint.html) 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](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/MRegionEndpointGetBySystemNameString.html).
```
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](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/EC2/TEC2Config.html) 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](creds-assign.md).
### 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](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) 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`.
1. Environment variables (`AWS_REGION` and `AWS_DEFAULT_REGION`).
1. A profile with the name specified by a value in `AWSConfigs.AWSProfileName`.
1. A profile with the name specified by the `AWS_PROFILE` environment variable.
1. The `[default]` profile.
1. 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](https://docs.amazonaws.cn/en_us/aws/latest/userguide/endpoints-Beijing.html).
## 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.
# Credential and profile resolution
The AWS SDK for .NET searches for credentials in a certain order and uses the first available set for the current application.
**Credential search order**
1. Credentials that are explicitly set on the AWS service client, as described in [Accessing credentials and profiles in an application](creds-locate.md).
**Note**
That topic is in the [Special considerations](special-considerations.md) section because it isn't the preferred method for specifying credentials.
1. [SessionAWSCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TSessionAWSCredentials.html) that are created from the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables, if all three variables have a value.
1. [BasicAWSCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TBasicAWSCredentials.html) that are created from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, if both variables have a value.
1. [AssumeRoleWithWebIdentityCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TAssumeRoleWithWebIdentityCredentials.html) that are created from the `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN` environment variables, if both variables have a value.
1. A credentials profile with the name specified by a value in [AWSConfigs.AWSProfileName](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html#properties).
1. A credentials profile with the name specified by the `AWS_PROFILE` environment variable.
1. The `[default]` credentials profile.
1. The [container credential provider](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html).
1. Amazon EC2 instance metadata.
If your application is running on an Amazon EC2 instance, such as in a production environment, use an IAM role as described in [Granting access by using an IAM role](net-dg-hosm.md). Otherwise, such as in prerelease testing, store your credentials in a file that uses the AWS credentials file format that your web application has access to on the server.
For additional information about environment variables and credentials profiles, see the following topics in the [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/): [Environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html), [Environment variables list](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#EVarSettings), and [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html).
## Profile resolution
With two different storage mechanisms for credentials, it's important to understand how to configure the AWS SDK for .NET to use them. The [AWSConfigs.AWSProfilesLocation](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property controls how the AWS SDK for .NET finds credential profiles.
****
| AWSProfilesLocation | Profile resolution behavior |
| --- | --- |
| null (not set) or empty | Search the SDK Store if the platform supports it, and then search the shared AWS credentials file in the [default location](creds-file.md). If the profile isn't in either of those locations, search `~/.aws/config` (Linux or macOS) or `%USERPROFILE%\.aws\config` (Windows). |
| The path to a file in the AWS credentials file format | Search *only* the specified file for a profile with the specified name. |
## Using federated user account credentials
Applications that use the AWS SDK for .NET ([AWSSDK.Core](https://www.nuget.org/packages/AWSSDK.Core/) version 3.1.6.0 and later) can use federated user accounts through Active Directory Federation Services (AD FS) to access AWS services by using Security Assertion Markup Language (SAML).
Federated access support means users can authenticate using your Active Directory. Temporary credentials are granted to the user automatically. These temporary credentials, which are valid for one hour, are used when your application invokes AWS services. The SDK handles management of the temporary credentials. For domain-joined user accounts, if your application makes a call but the credentials have expired, the user is reauthenticated automatically and fresh credentials are granted. (For accounts that are not joined to a domain, the user is prompted to enter credentials before reauthentication.)
To use this support in your .NET application, you must first set up the role profile by using a PowerShell cmdlet. To learn how, see the [AWS Tools for Windows PowerShell documentation](https://docs.aws.amazon.com/powershell/latest/userguide/saml-pst.html).
After you set up the role profile, reference the profile in your application. There are a number of ways to do this, one of which is by using the [AWSConfigs.AWSProfileName](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property in the same way you would with other credential profiles.
The *AWS Security Token Service* assembly ([AWSSDK.SecurityToken](https://www.nuget.org/packages/AWSSDK.SecurityToken/)) provides the SAML support to obtain AWS credentials. To use federated user account credentials, be sure this assembly is available to your application.
## Specifying roles or temporary credentials
For applications that run on Amazon EC2 instances, the most secure way to manage credentials is to use IAM roles, as described in [Granting access by using an IAM role](net-dg-hosm.md).
For application scenarios in which the software executable is available to users outside your organization, we recommend that you design the software to use *temporary security credentials*. In addition to providing restricted access to AWS resources, these credentials have the benefit of expiring after a specified period of time. For more information about temporary security credentials, see the following:
+ [Temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
+ [Amazon Cognito identity pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)
## Using proxy credentials
If your software communicates with AWS through a proxy, you can specify credentials for the proxy by using the `ProxyCredentials` property of the `Config` class of a service. The `Config` class of a service is typically part of the primary namespace for the service. Examples include the following: [AmazonCloudDirectoryConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudDirectory/TCloudDirectoryConfig.html) in the [Amazon.CloudDirectory](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudDirectory/NCloudDirectory.html) namespace and [AmazonGameLiftConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/GameLift/TGameLiftConfig.html) in the [Amazon.GameLift](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/GameLift/NGameLift.html) namespace.
For [Amazon S3](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html), for example, you could use code similar to the following, where `SecurelyStoredUserName` and `SecurelyStoredPassword` are the proxy user name and password specified in a [NetworkCredential](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkcredential) object.
```
AmazonS3Config config = new AmazonS3Config();
config.ProxyCredentials = new NetworkCredential(SecurelyStoredUserName, SecurelyStoredPassword);
```
**Note**
Earlier versions of the SDK used `ProxyUsername` and `ProxyPassword`, but these properties are deprecated.
# Retries and timeouts
The AWS SDK for .NET enables you to configure the number of retries and the timeout values for HTTP requests to AWS services. If the default values for retries and timeouts are not appropriate for your application, you can adjust them for your specific requirements, but it is important to understand how doing so will affect the behavior of your application.
To determine which values to use for retries and timeouts, consider the following:
+ How should the AWS SDK for .NET and your application respond when network connectivity degrades or an AWS service is unreachable? Do you want the call to fail fast, or is it appropriate for the call to keep retrying on your behalf?
+ Is your application a user-facing application or website that must be responsive, or is it a background processing job that has more tolerance for increased latencies?
+ Is the application deployed on a reliable network with low latency, or is it deployed at a remote location with unreliable connectivity?
## Retries
### Overview
The AWS SDK for .NET can retry requests that fail due to server-side throttling or dropped connections. There are two properties of service configuration classes that you can use to specify the retry behavior of a service client. Service configuration classes inherit these properties from the abstract [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html) class of the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/):
+ `RetryMode` specifies one of three retry modes, which are defined in the [Amazon.Runtime.RequestRetryMode](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TRequestRetryMode.html) enumeration.
The default value for your application can be controlled by using the `AWS_RETRY_MODE` environment variable or the *retry\$1mode* setting in the shared AWS config file.
+ `MaxErrorRetry` specifies the number of retries allowed at the service client level; the SDK retries the operation the specified number of times before failing and throwing an exception.
The default value for your application can be controlled by using the `AWS_MAX_ATTEMPTS` environment variable or the *max\$1attempts* setting in the shared AWS config file.
Detailed descriptions for these properties can be found in the abstract [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html) class of the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/). Each value of `RetryMode` corresponds by default to a particular value of `MaxErrorRetry`, as shown in the following table.
| | | |
| --- |--- |--- |
| Legacy | 10 | 4 |
| Standard | 10 | 2 |
| Adaptive (experimental) | 10 | 2 |
### Behavior
**When your application starts**
When your application starts, default values for `RetryMode` and `MaxErrorRetry` are configured by the SDK. These default values are used when you create a service client unless you specify other values.
+ If the properties aren't set in your environment, the default for `RetryMode` is configured as *Legacy* and the default for `MaxErrorRetry` is configured with the corresponding value from the preceding table.
+ If the retry mode has been set in your environment, that value is used as the default for `RetryMode`. The default for `MaxErrorRetry` is configured with the corresponding value from the preceding table unless the value for maximum errors has also been set in your environment (described next).
+ If the value for maximum errors has been set in your environment, that value is used as the default for `MaxErrorRetry`. Amazon DynamoDB is the exception to this rule; the default DynamoDB value for `MaxErrorRetry` is always the value from the preceding table.
**As your application runs**
When you create a service client, you can use the default values for `RetryMode` and `MaxErrorRetry`, as described earlier, or you can specify other values. To specify other values, create and include a service configuration object such as [AmazonDynamoDBConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/DynamoDBv2/TDynamoDBConfig.html) or [AmazonSQSConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/SQS/TSQSConfig.html) when you create the service client.
These values can't be changed for a service client after it has been created.
**Considerations**
When a retry occurs, the latency of your request is increased. You should configure your retries based on your application limits for total request latency and error rates.
## Timeouts
The AWS SDK for .NET enables you to configure request timeouts at the service client level and per method call. There are two mechanisms for configuring timeouts, which are covered in subsequent sections:
+ If you are using [asynchronous calls](#timeouts-async), you can use the `CancellationToken` parameter of the method.
+ If you are using [synchronous calls in .NET Framework](#timeouts-sync-framework), you can use the `Timeout` and `ReadWriteTimeout` properties of the abstract [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html) class.
### Using the `CancellationToken` parameter for timeouts
The AWS SDK for .NET enables you to configure request timeouts on asynchronous calls by using the `CancellationToken` parameter. The following code snippet shows an example. The code throws `System.Threading.Tasks.TaskCanceledException` if the request isn't completed within 10 seconds.
```
string bucketName = "amzn-s3-demo-bucket";
string path = "pathToBucket";
using (var amazonS3Client = new AmazonS3Client(new AmazonS3Config()))
{
// Cancel request after 10 seconds
CancellationTokenSource cancellationTokenSource = new CancellationTokenSource(TimeSpan.FromMilliseconds(10000));
CancellationToken cancellationToken = cancellationTokenSource.Token;
ListObjectsV2Request listRequestV2 = new()
{
BucketName = bucketName,
Prefix = path,
};
ListObjectsV2Response listResponseV2 = await amazonS3Client.ListObjectsV2Async(listRequestV2, cancellationToken);
}
```
### Using the `Timeout` and `ReadWriteTimeout` properties for timeouts
**Note**
The `Timeout` property doesn't impact asynchronous calls. If you are using asynchronous calls see [Using the `CancellationToken` parameter for timeouts](#timeouts-async) instead.
The AWS SDK for .NET enables you to configure the request timeout and socket read/write timeout values at the service client level. These values are specified in the `Timeout` and the `ReadWriteTimeout` properties of the abstract [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html) class. These values are passed on as the `Timeout` and `ReadWriteTimeout` properties of the [HttpWebRequest](https://learn.microsoft.com/en-us/dotnet/api/system.net.httpwebrequest) objects created by the AWS service client object. By default, the `Timeout` value is 100 seconds and the `ReadWriteTimeout` value is 300 seconds.
When your network has high latency, or conditions exist that cause an operation to be retried, using long timeout values and a high number of retries can cause some SDK operations to seem unresponsive.
**Note**
The version of the AWS SDK for .NET that targets the portable class library (PCL) uses the [HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient) class instead of the `HttpWebRequest` class, and supports the [Timeout](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout) property only.
The following are the exceptions to the default timeout values. These values are overridden when you explicitly set the timeout values.
+ `Timeout` and `ReadWriteTimeout` are set to the maximum values if the method being called uploads a stream, such as [AmazonS3Client.PutObjectAsync()](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/MS3PutObjectAsyncPutObjectRequestCancellationToken.html), [AmazonS3Client.UploadPartAsync()](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/MS3UploadPartAsyncUploadPartRequestCancellationToken.html), [AmazonGlacierClient.UploadArchiveAsync()](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Glacier/MGlacierUploadArchiveAsyncUploadArchiveRequestCancellationToken.html), and so on.
+ The versions of the AWS SDK for .NET that target .NET Framework set `Timeout` and `ReadWriteTimeout` to the maximum values for all [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) and [AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Glacier/TGlacierClient.html) objects.
+ The versions of the AWS SDK for .NET that target the portable class library (PCL) and .NET Core set `Timeout` to the maximum value for all [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) and [AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Glacier/TGlacierClient.html) objects.
The following example shows you how to specify *Standard* retry mode, a maximum of 3 retries, a timeout of 10 seconds, and a read/write timeout of 10 seconds (if applicable). The [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) constructor is given an [AmazonS3Config](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html) object.
```
var s3Client = new AmazonS3Client(
new AmazonS3Config
{
Timeout = TimeSpan.FromSeconds(10),
// NOTE: The following property is obsolete for
// versions of the AWS SDK for .NET that target .NET Core.
ReadWriteTimeout = TimeSpan.FromSeconds(10),
RetryMode = RequestRetryMode.Standard,
MaxErrorRetry = 3
});
```
# Observability
Observability is the extent to which a system's current state can be inferred from the data it emits. The data emitted is commonly referred to as telemetry.
The AWS SDK for .NET can provide two common telemetry signals, metrics and traces, as well as logging. You can wire up a [TelemetryProvider](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html) to send telemetry data to an observability backend (such as [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools) or [Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov)) and then act on it.
By default, telemetry signals are disabled in the SDK. This topic explains how to enable and configure telemetry output.
## Additional resources
For more information about enabling and using observability, see the following resources:
+ [OpenTelemetry](https://opentelemetry.io/)
+ The blog post [Enhancing Observability in the AWS SDK for .NET with OpenTelemetry](https://aws.amazon.com/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/).
+ The blog post [Announcing the general availability of AWS .NET OpenTelemetry libraries](https://aws.amazon.com/blogs/dotnet/announcing-the-general-availability-of-aws-net-opentelemetry-libraries/).
+ [Exporters for OpenTelemetry](https://opentelemetry.io/docs/languages/net/exporters/)
+ For examples of observability in the AWS Tools for PowerShell, see [Observability](https://docs.aws.amazon.com/powershell/latest/userguide/observability.html) in the [Tools for PowerShell User Guide](https://docs.aws.amazon.com/powershell/latest/userguide/).
## Configure a `TelemetryProvider`
You can configure a `TelemetryProvider` in your application globally for all service clients or for individual clients, as shown in the following examples. The [Telemetry providers](observability-telemetry-providers.md) section contains information about telemetry implementations, including information about implementations that are provided with the SDK.
### Configure the default global telemetry provider
By default, every service client attempts to use the globally available telemetry provider. This way, you can set the provider once, and all clients will use it. This should be done only once, before you create any service clients.
The following code snippet shows you how to set the global telemetry provider. It then creates an Amazon S3 service client and tries to perform an operation that fails. The code adds both tracing and metrics to the application. This code uses the following NuGet packages: `OpenTelemetry.Exporter.Console` and `OpenTelemetry.Instrumentation.AWS`.
**Note**
If you're using AWS IAM Identity Center for authentication, be sure to also add `AWSSDK.SSO` and `AWSSDK.SSOOIDC`.
```
using Amazon.S3;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
Sdk.CreateTracerProviderBuilder()
.ConfigureResource(e => e.AddService("DemoOtel"))
.AddAWSInstrumentation()
.AddConsoleExporter()
.Build();
Sdk.CreateMeterProviderBuilder()
.ConfigureResource(e => e.AddService("DemoOtel"))
.AddAWSInstrumentation()
.AddConsoleExporter()
.Build();
var s3Client = new AmazonS3Client();
try
{
var listBucketsResponse = await s3Client.ListBucketsAsync();
// Attempt to delete a bucket that doesn't exist.
var deleteBucketResponse = await s3Client.DeleteBucketAsync("amzn-s3-demo-bucket");
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
Console.Read();
```
### Configure a telemetry provider for a specific service client
You can configure an individual service client with a specific telemetry provider (other than the global one). To do so, use the `TelemetryProvider` class of the Config object of a service client constructor. For example, see [AmazonS3Config](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html) and look for the `TelemetryProvider` property. See [Telemetry providers](observability-telemetry-providers.md) for information about custom telemetry implementations.
**Topics**
+ [Additional resources](#observability-resources)
+ [Configure a `TelemetryProvider`](#observability-conf-telemetry-provider)
+ [Metrics](observability-metrics.md)
+ [Telemetry providers](observability-telemetry-providers.md)
# Metrics
The following table lists the telemetry metrics that the SDK emits. [Configure a telemetry provider](observability.md#observability-conf-telemetry-provider) to make the metrics observable.
**What metrics are emitted?**
| Metric name | Units | Type | Attributes | Description |
| --- | --- | --- | --- | --- |
| client.call.duration | s | Histogram | rpc.service, rpc.method | Overall call duration (including retries and time to send or receive request and response body) |
| client.uptime | s | Histogram | rpc.service | The amount of time since a client was created |
| client.call.attempts | \$1attempt\$1 | MonotonicCounter | rpc.service, rpc.method | The number of attempts for an individual operation |
| client.call.errors | \$1error\$1 | MonotonicCounter | rpc.service, rpc.method, exception.type | The number of errors for an operation |
| client.call.attempt\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to connect to the service, send the request, and get back HTTP status code and headers (including time queued waiting to be sent) |
| client.call.resolve\$1endpoint\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to resolve an endpoint (endpoint resolver, not DNS) for the request |
| client.call.serialization\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to serialize a message body |
| client.call.deserialization\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to deserialize a message body |
| client.call.auth.signing\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to sign a request |
| client.call.auth.resolve\$1identity\$1duration | s | Histogram | rpc.service, rpc.method | The time it takes to acquire an identity (such as AWS credentials or a bearer token) from an Identity Provider |
| client.http.bytes\$1sent | By | MonotonicCounter | server.address | The total number of bytes sent by the HTTP client |
| client.http.bytes\$1received | By | MonotonicCounter | server.address | The total number of bytes received by the HTTP client |
Following are the column descriptions:
+ **Metric name**–The name of the emitted metric.
+ **Units**–The unit of measure for the metric. Units are given in the [UCUM](https://unitsofmeasure.org/ucum) case sensitive ("c/s") notation.
+ **Type**–The type of instrument used to capture the metric.
+ **Attributes**–The set of attributes (dimensions) emitted with the metric.
+ **Description**–A description of what the metric is measuring.
# Telemetry providers
The SDK provides an implementation of [OpenTelemetry](https://opentelemetry.io/) as a telemetry provider, which is described in the [next section](observability-telemetry-providers-otel.md).
If you have specific telemetry requirements, already have a telemetry solution in mind, or need fine-grained control over how telemetry data is captured and processed, you can also implement your own telemetry provider.
Register your own implementation with the [TelemetryProvider](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html) class. The following is a simple example of how to register your own `TracerProvider` and `MeterProvider`.
```
using Amazon;
using Amazon.Runtime.Telemetry;
using Amazon.Runtime.Telemetry.Metrics;
using Amazon.Runtime.Telemetry.Tracing;
public class CustomTracerProvider : TracerProvider
{
// Implement custom tracing logic here
}
public class CustomMeterProvider : MeterProvider
{
// Implement custom metrics logic here
}
// Register custom implementations
AWSConfigs.TelemetryProvider.RegisterTracerProvider(new CustomTracerProvider());
AWSConfigs.TelemetryProvider.RegisterMeterProvider(new CustomMeterProvider());
```
**Topics**
+ [OpenTelemetry](observability-telemetry-providers-otel.md)
# Configure the OpenTelemetry-based telemetry provider
The AWS SDK for .NET includes an implementation of an OpenTelemetry-based telemetry provider. For details about how to set this provider as the global telemetry provider, see [Configure a `TelemetryProvider`](observability.md#observability-conf-telemetry-provider). To use this telemetry provider, you need the following resources in your project:
+ The [OpenTelemetry.Instrumentation.AWS](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AWS) NuGet package.
+ A telemetry exporter such as OTLP or Console. For more information, see [Exporters](https://opentelemetry.io/docs/languages/net/exporters/) in the OpenTelemetry documentation.
The OpenTelemetry implementation included with the SDK can be configured to reduce the amount of tracing for HTTPS requests, credentials, and compression. To do so, set the `SuppressDownstreamInstrumentation` option to `true`, similar to the following:
```
Sdk.CreateTracerProviderBuilder()
.ConfigureResource(e => e.AddService("DemoOtel"))
.AddAWSInstrumentation(options => options.SuppressDownstreamInstrumentation = true)
.AddConsoleExporter()
.Build();
```
For additional information about this provider, see the blog post [Enhancing Observability in the AWS SDK for .NET with OpenTelemetry](https://aws.amazon.com/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/).
# Additional information about users and roles
For doing .NET development on AWS or for running .NET applications on AWS, you need to have some combination of users, permission sets, and service roles that are appropriate for these tasks.
The specific users, permission sets, and service roles that you create, and the way in which you use them, will depend on the requirements of your applications. The following is some additional information about why they might be used and how to create them.
## Users and permission sets
Although it's possible to use an IAM user account with long-term credentials to access AWS services, this is no longer a best practice and should be avoided. Even during development, it is a best practice to create users and permission sets in AWS IAM Identity Center and use temporary credentials provided by an identity source.
For development, you can use the user that you created or were given in [Authenticating with AWS](creds-idc.md). If you have appropriate AWS Management Console permissions, you can also create different permission sets with least privilege for that user or create new users specifically for development projects, providing permission sets with least privilege. The course of action you choose, if any, depends on your circumstances.
For more information about these users and permissions sets and how to create them, see [Authentication and access](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) in the *AWS SDKs and Tools Reference Guide* and [Getting started](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) in the *AWS IAM Identity Center User Guide*.
## Service roles
You can set up an AWS service role to access AWS services on behalf of users. This type of access is appropriate if multiple people will be running your application remotely; for example, on an Amazon EC2 instance that you have created for this purpose.
The process for creating a service role varies depending on the situation, but is essentially the following.
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Choose **Roles**, and then choose **Create role**.
1. Choose **AWS service**, find and select **EC2** (for example), and then choose the **EC2** use case (for example).
1. Choose **Next: Permissions**, and select the [appropriate policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) for the AWS services that your application will use.
**Warning**
Do ***NOT*** choose the **AdministratorAccess** policy because that policy enables read and write permissions to almost everything in your account.
1. Choose **Next: Tags** and enter any tags you want.
You can find information about tags in [Control access using AWS resource tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/).
1. Choose **Next: Review** and provide a **Role name** and **Role description**. Then choose **Create role**.
You can find high-level information about IAM roles in [Identities (users, groups, and roles)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) in the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/). Find detailed information about roles in that guide's [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) topic.
**Additional information about roles**
+ Use [IAM roles for tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) for Amazon Elastic Container Service (Amazon ECS) tasks.
+ Use [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) for applications that are running on Amazon EC2 instances.
# Advanced configuration for your AWS SDK for .NET project
The topics in this section contain information about additional configuration tasks and methods that might be of interest to you.
**Topics**
+ [AWSSDK.Extensions.NETCore.Setup and IConfiguration](net-dg-config-netcore.md)
+ [Configuring Other Application Parameters](net-dg-config-other.md)
+ [Configuration Files Reference for AWS SDK for .NET](net-dg-config-ref.md)
# Using AWSSDK.Extensions.NETCore.Setup and the IConfiguration interface
(This topic was formerly titled, "Configuring the AWS SDK for .NET with .NET Core")
One of the biggest changes in .NET Core is the removal of `ConfigurationManager` and the standard `app.config` and `web.config` files that were used with .NET Framework and ASP.NET applications.
Configuration in .NET Core is based on key-value pairs established by configuration providers. Configuration providers read configuration data into key-value pairs from a variety of configuration sources, including command-line arguments, directory files, environment variables, and settings files.
**Note**
For further information, see [Configuration in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration).
To make it easy to use the AWS SDK for .NET with .NET Core, you can use the [AWSSDK.Extensions.NETCore.Setup](https://www.nuget.org/packages/AWSSDK.Extensions.NETCore.Setup/) NuGet package. Like many .NET Core libraries, it adds extension methods to the `IConfiguration` interface to make getting the AWS configuration seamless.
The source code for this package is on GitHub at [https://github.com/aws/aws-sdk-net/tree/main/extensions/src/AWSSDK.Extensions.NETCore.Setup](https://github.com/aws/aws-sdk-net/tree/main/extensions/src/AWSSDK.Extensions.NETCore.Setup).
## Using AWSSDK.Extensions.NETCore.Setup
Suppose that you create an ASP.NET Core Model-View-Controller (MVC) application, which can be accomplished with the **ASP.NET Core Web Application** template in Visual Studio or by running `dotnet new mvc ...` in the .NET Core CLI. When you create such an application, the constructor for `Startup.cs` handles configuration by reading in various input sources from configuration providers such as `appsettings.json`.
```
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
```
To use the `Configuration` object to get the *AWS* options, first add the `AWSSDK.Extensions.NETCore.Setup` NuGet package. Then, add your options to the configuration file as described next.
Notice that one of the files added to your project is `appsettings.Development.json`. This corresponds to an `EnvironmentName` set to **Development**. During development, you put your configuration in this file, which is only read during local testing. When you deploy an Amazon EC2 instance that has `EnvironmentName` set to **Production**, this file is ignored and the AWS SDK for .NET falls back to the IAM credentials and Region that are configured for the Amazon EC2 instance.
The following configuration settings show examples of the values you can add in the `appsettings.Development.json` file in your project to supply AWS settings.
```
{
"AWS": {
"Profile": "local-test-profile",
"Region": "us-west-2"
},
"SupportEmail": "TechSupport@example.com"
}
```
To access a setting in a *CSHTML* file, use the `Configuration` directive.
```
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Contact
Support: @Configuration["SupportEmail"]
```
To access the AWS options set in the file from code, call the `GetAWSOptions` extension method added to `IConfiguration`.
To construct a service client from these options, call `CreateServiceClient`. The following example shows how to create an Amazon S3 service client. (Be sure to add the [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3) NuGet package to your project.)
```
var options = Configuration.GetAWSOptions();
IAmazonS3 client = options.CreateServiceClient();
```
You can also create multiple service clients with incompatible settings by using multiple entries in the `appsettings.Development.json` file, as shown in the following examples where the configuration for `service1` includes the `us-west-2` Region and the configuration for `service2` includes the special endpoint *URL*.
```
{
"service1": {
"Profile": "default",
"Region": "us-west-2"
},
"service2": {
"Profile": "default",
"ServiceURL": "URL"
}
}
```
You can then get the options for a specific service by using the entry in the JSON file. For example, to get the settings for `service1` use the following.
```
var options = Configuration.GetAWSOptions("service1");
```
### Allowed values in appsettings file
The following app configuration values can be set in the `appsettings.Development.json` file. The field names must use the casing shown. For details on these settings, see the `[AWS.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)` class.
+ Region
+ Profile
+ ProfilesLocation
+ SignatureVersion
+ RegionEndpoint
+ UseHttp
+ ServiceURL
+ AuthenticationRegion
+ AuthenticationServiceName
+ MaxErrorRetry
+ LogResponse
+ BufferSize
+ ProgressUpdateInterval
+ ResignRetries
+ AllowAutoRedirect
+ LogMetrics
+ DisableLogging
+ UseDualstackEndpoint
## ASP.NET Core dependency injection
The *AWSSDK.Extensions.NETCore.Setup* NuGet package also integrates with a new dependency injection system in ASP.NET Core. The `ConfigureServices` method in your application's `Startup` class is where the MVC services are added. If the application is using Entity Framework, this is also where that is initialized.
```
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
}
```
**Note**
Background on dependency injection in .NET Core is available on the [.NET Core documentation site](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection).
The `AWSSDK.Extensions.NETCore.Setup` NuGet package adds new extension methods to `IServiceCollection` that you can use to add AWS services to the dependency injection. The following code shows you how to add the AWS options that are read from `IConfiguration` to add Amazon S3 and DynamoDB to the list of services. (Be sure to add the [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3) and [AWSSDK.DynamoDBv2](https://www.nuget.org/packages/AWSSDK.DynamoDBv2) NuGet packages to your project.)
```
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
services.AddAWSService();
services.AddAWSService();
}
```
Now, if your MVC controllers use either `IAmazonS3` or `IAmazonDynamoDB` as parameters in their constructors, the dependency injection system passes in those services.
```
public class HomeController : Controller
{
IAmazonS3 S3Client { get; set; }
public HomeController(IAmazonS3 s3Client)
{
this.S3Client = s3Client;
}
...
}
```
# Configuring Other Application Parameters
**Note**
The information in this topic is specific to projects based on .NET Framework. The `App.config` and `Web.config` files are not present by default in projects based on .NET Core.
## Open to view .NET Framework content
There are a number of application parameters that you can configure:
+ `AWSLogging`
+ `AWSLogMetrics`
+ `AWSRegion`
+ `AWSResponseLogging`
+ `AWS.DynamoDBContext.TableNamePrefix`
+ `AWS.S3.UseSignatureVersion4`
+ `AWSEndpointDefinition`
+ [AWS Service-Generated Endpoints](#config-setting-service-generated-awsendpointdefinition)
These parameters can be configured in the application’s `App.config` or `Web.config` file. Although you can also configure these with the AWS SDK for .NET API, we recommend you use the application’s `.config` file. Both approaches are described here.
For more information about use of the `` element as described later in this topic, see [Configuration Files Reference for AWS SDK for .NET](net-dg-config-ref.md).
### AWSLogging
Configures how the SDK should log events, if at all. For example, the recommended approach is to use the `` element, which is a child element of the `` element:
```
```
Alternatively:
```
```
The possible values are:
** `None` **
Turn off event logging. This is the default.
** `log4net` **
Log using log4net.
** `SystemDiagnostics` **
Log using the `System.Diagnostics` class.
You can set multiple values for the `logTo` attribute, separated by commas. The following example sets both `log4net` and `System.Diagnostics` logging in the `.config` file:
```
```
Alternatively:
```
```
Alternatively, using the AWS SDK for .NET API, combine the values of the [LoggingOptions](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TLoggingOptions.html) enumeration and set the [AWSConfigs.Logging](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property:
```
AWSConfigs.Logging = LoggingOptions.Log4Net | LoggingOptions.SystemDiagnostics;
```
Changes to this setting take effect only for new AWS client instances.
### AWSLogMetrics
Specifies whether or not the SDK should log performance metrics. To set the metrics logging configuration in the `.config` file, set the `logMetrics` attribute value in the `` element, which is a child element of the `` element:
```
```
Alternatively, set the `AWSLogMetrics` key in the `` section:
```
```
Alternatively, to set metrics logging with the AWS SDK for .NET API, set the [AWSConfigs.LogMetrics](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property:
```
AWSConfigs.LogMetrics = true;
```
This setting configures the default `LogMetrics` property for all clients/configs. Changes to this setting take effect only for new AWS client instances.
### AWSRegion
Configures the default AWS region for clients that have not explicitly specified a region. To set the region in the `.config` file, the recommended approach is to set the `region` attribute value in the `aws` element:
```
```
Alternatively, set the *AWSRegion* key in the `` section:
```
```
Alternatively, to set the region with the AWS SDK for .NET API, set the [AWSConfigs.AWSRegion](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property:
```
AWSConfigs.AWSRegion = "us-west-2";
```
For more information about creating an AWS client for a specific region, see [AWS Region Selection](net-dg-region-selection.md). Changes to this setting take effect only for new AWS client instances.
### AWSResponseLogging
Configures when the SDK should log service responses. The possible values are:
** `Never` **
Never log service responses. This is the default.
** `Always` **
Always log service responses.
** `OnError` **
Only log service responses when an error occurs.
To set the service logging configuration in the `.config` file, the recommended approach is to set the `logResponses` attribute value in the `` element, which is a child element of the `` element:
```
```
Alternatively, set the *AWSResponseLogging* key in the `` section:
```
```
Alternatively, to set service logging with the AWS SDK for .NET API, set the [AWSConfigs.ResponseLogging](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property to one of the values of the [ResponseLoggingOption](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TResponseLoggingOption.html) enumeration:
```
AWSConfigs.ResponseLogging = ResponseLoggingOption.OnError;
```
Changes to this setting take effect immediately.
### `AWS.DynamoDBContext.TableNamePrefix`
Configures the default `TableNamePrefix` the `DynamoDBContext` will use if not manually configured.
To set the table name prefix in the `.config` file, the recommended approach is to set the `tableNamePrefix` attribute value in the `` element, which is a child element of the `` element, which itself is a child element of the `` element:
```
```
Alternatively, set the `AWS.DynamoDBContext.TableNamePrefix` key in the `` section:
```
```
Alternatively, to set the table name prefix with the AWS SDK for .NET API, set the [AWSConfigs.DynamoDBContextTableNamePrefix](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property:
```
AWSConfigs.DynamoDBContextTableNamePrefix = "Test-";
```
Changes to this setting will take effect only in newly constructed instances of `DynamoDBContextConfig` and `DynamoDBContext`.
### `AWS.S3.UseSignatureVersion4`
Configures whether or not the Amazon S3 client should use signature version 4 signing with requests.
To set signature version 4 signing for Amazon S3 in the `.config` file, the recommended approach is to set the `useSignatureVersion4` attribute of the `` element, which is a child element of the `` element:
```
```
Alternatively, set the `AWS.S3.UseSignatureVersion4` key to `true` in the `` section:
```
```
Alternatively, to set signature version 4 signing with the AWS SDK for .NET API, set the [AWSConfigs.S3UseSignatureVersion4](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property to `true`:
```
AWSConfigs.S3UseSignatureVersion4 = true;
```
By default, this setting is `false`, but signature version 4 may be used by default in some cases or with some regions. When the setting is `true`, signature version 4 will be used for all requests. Changes to this setting take effect only for new Amazon S3 client instances.
### AWSEndpointDefinition
Configures whether the SDK should use a custom configuration file that defines the regions and endpoints.
To set the endpoint definition file in the `.config` file, we recommend setting the `endpointDefinition` attribute value in the `` element.
```
```
Alternatively, you can set the *AWSEndpointDefinition* key in the `` section:
```
```
Alternatively, to set the endpoint definition file with the AWS SDK for .NET API, set the [AWSConfigs.EndpointDefinition](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) property:
```
AWSConfigs.EndpointDefinition = @"c:\config\endpoints.json";
```
If no file name is provided, then a custom configuration file will not be used. Changes to this setting take effect only for new AWS client instances. The `endpoints.json` file is available from [https://github.com/aws/aws-sdk-net/blob/main/sdk/src/Core/endpoints.json](https://github.com/aws/aws-sdk-net/blob/main/sdk/src/Core/endpoints.json).
### AWS Service-Generated Endpoints
Some AWS services generate their own endpoints instead of consuming a region endpoint. Clients for these services consume a service Url that is specific to that service and your resources. Two examples of these services are Amazon CloudSearch and AWS IoT. The following examples show how you can obtain the endpoints for those services.
#### Amazon CloudSearch Endpoints Example
The Amazon CloudSearch client is used for accessing the Amazon CloudSearch configuration service. You use the Amazon CloudSearch configuration service to create, configure, and manage search domains. To create a search domain, create a [CreateDomainRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCreateDomainRequest.html) object and provide the `DomainName` property. Create an [AmazonCloudSearchClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCloudSearchClient.html) object by using the request object. Call the [CreateDomain](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/MCloudSearchCreateDomainCreateDomainRequest.html) method. The [CreateDomainResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCreateDomainResponse.html) object returned from the call contains a `DomainStatus` property that has both the `DocService` and `SearchService` endpoints. Create an [AmazonCloudSearchDomainConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearchDomain/TCloudSearchDomainConfig.html) object and use it to initialize `DocService` and `SearchService` instances of the [AmazonCloudSearchDomainClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearchDomain/TCloudSearchDomainClient.html) class.
```
// Create domain and retrieve DocService and SearchService endpoints
DomainStatus domainStatus;
using (var searchClient = new AmazonCloudSearchClient())
{
var request = new CreateDomainRequest
{
DomainName = "testdomain"
};
domainStatus = searchClient.CreateDomain(request).DomainStatus;
Console.WriteLine(domainStatus.DomainName + " created");
}
// Test the DocService endpoint
var docServiceConfig = new AmazonCloudSearchDomainConfig
{
ServiceURL = "https://" + domainStatus.DocService.Endpoint
};
using (var domainDocService = new AmazonCloudSearchDomainClient(docServiceConfig))
{
Console.WriteLine("Amazon CloudSearchDomain DocService client instantiated using the DocService endpoint");
Console.WriteLine("DocService endpoint = " + domainStatus.DocService.Endpoint);
using (var docStream = new FileStream(@"C:\doc_source\XMLFile4.xml", FileMode.Open))
{
var upload = new UploadDocumentsRequest
{
ContentType = ContentType.ApplicationXml,
Documents = docStream
};
domainDocService.UploadDocuments(upload);
}
}
// Test the SearchService endpoint
var searchServiceConfig = new AmazonCloudSearchDomainConfig
{
ServiceURL = "https://" + domainStatus.SearchService.Endpoint
};
using (var domainSearchService = new AmazonCloudSearchDomainClient(searchServiceConfig))
{
Console.WriteLine("Amazon CloudSearchDomain SearchService client instantiated using the SearchService endpoint");
Console.WriteLine("SearchService endpoint = " + domainStatus.SearchService.Endpoint);
var searchReq = new SearchRequest
{
Query = "Gambardella",
Sort = "_score desc",
QueryParser = QueryParser.Simple
};
var searchResp = domainSearchService.Search(searchReq);
}
```
#### AWS IoT Endpoints Example
To obtain the endpoint for AWS IoT, create an [AmazonIoTClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/TIoTClient.html) object and call the [DescribeEndPoint](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/MIoTDescribeEndpointDescribeEndpointRequest.html) method. The returned [DescribeEndPointResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/TDescribeEndpointResponse.html) object contains the `EndpointAddress`. Create an [AmazonIotDataConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IotData/TIotDataConfig.html) object, set the `ServiceURL` property, and use the object to instantiate the [AmazonIotDataClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IotData/TIotDataClient.html) class.
```
string iotEndpointAddress;
using (var iotClient = new AmazonIoTClient())
{
var endPointResponse = iotClient.DescribeEndpoint();
iotEndpointAddress = endPointResponse.EndpointAddress;
}
var ioTdocServiceConfig = new AmazonIotDataConfig
{
ServiceURL = "https://" + iotEndpointAddress
};
using (var dataClient = new AmazonIotDataClient(ioTdocServiceConfig))
{
Console.WriteLine("AWS IoTData client instantiated using the endpoint from the IotClient");
}
```
# Configuration Files Reference for AWS SDK for .NET
**Note**
The information in this topic is specific to projects based on .NET Framework. The `App.config` and `Web.config` files are not present by default in projects based on .NET Core.
## Open to view .NET Framework content
You can use a .NET project's `App.config` or `Web.config` file to specify AWS settings, such as AWS credentials, logging options, AWS service endpoints, and AWS regions, as well as some 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 `` element in an `App.config` or `Web.config` file to specify AWS settings, we recommend you use the `` and `` elements as described later in this topic. For more information about the `` element, see the `` element examples in [Configuring Your AWS SDK for .NET Application](net-dg-config.md).
**Note**
Although you can continue to use the following [https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) 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 `` and `` 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](net-dg-config.md).
**Topics**
+ [Declaring an AWS Settings Section](#net-dg-config-ref-declaring)
+ [Allowed Elements](#net-dg-config-ref-elements)
+ [Elements Reference](#net-dg-config-ref-elements-ref)
### Declaring an AWS Settings Section
You specify AWS settings in an `App.config` or `Web.config` file from within the `` element. Before you can begin using the `` element, you must create a `` element (which is a child element of the `` element) and set its `name` attribute to `aws` and its `type` attribute to `Amazon.AWSSection, AWSSDK.Core`, as shown in the following example:
```
...
...
```
The Visual Studio Editor does not provide automatic code completion (IntelliSense) for the `` element or its child elements.
To assist you in creating a correctly formatted version of the `` element, call the `Amazon.AWSConfigs.GenerateConfigTemplate` method. This outputs a canonical version of the `` element as a pretty-printed string, which you can adapt to your needs. The following sections describe the `` 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 `` element as a string you can adapt to your needs.
```
```
### 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.
**Topics**
+ [alias](#net-dg-config-ref-elements-alias)
+ [`aws`](#net-dg-config-ref-elements-aws)
+ [dynamoDB](#net-dg-config-ref-elements-dynamodb)
+ [dynamoDBContext](#net-dg-config-ref-elements-ddbcontext)
+ [ec2](#net-dg-config-ref-elements-ec2)
+ [logging](#net-dg-config-ref-elements-logging)
+ [map](#net-dg-config-ref-elements-map)
+ [property](#net-dg-config-ref-elements-property)
+ [proxy](#net-dg-config-ref-elements-proxy)
+ [s3](#net-dg-config-ref-elements-s3)
#### alias
The `` 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 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 `` element is the `` element.
The `` element contains no child elements.
The following is an example of the `` element in use:
```
```
#### `aws`
The `` 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 AWS regions and endpoints to use. This attribute maps to the `Amazon.AWSConfigs.EndpointDefinition` property in the AWS SDK for .NET.
** `profileName` **
The 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 `` element has no parent element.
The `` element can include the following child elements:
+ ``
+ ``
+ ``
+ ``
+ ``
The following is an example of the `` element in use:
```
```
#### dynamoDB
The `` 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](http://blogs.aws.amazon.com/net/post/Tx2TCOGWG7ARUH5/DynamoDB-Series-Conversion-Schemas).
The parent of the `` element is the `` element.
The `` element can include the `` child element.
The following is an example of the `` element in use:
```
```
#### dynamoDBContext
The `` element represents a collection of Amazon DynamoDB context-specific settings. This element can include the *tableNamePrefix* attribute, which represents the default table name prefix 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](http://blogs.aws.amazon.com/net/post/Tx2C4MHH2H0SA5W/Enhancements-to-the-DynamoDB-SDK).
The parent of the `` element is the `` element.
The `` element can include the following child elements:
+ `` (one or more instances)
+ `