` 元素。
例如，对于 Amazon S3，您可以在项目 `.csproj` 文件中添加以下几行。
**在 Linux 和 macOS 上：**
```
```
**在 Windows 上：**
```
```
1. 保存项目的 `.csproj` 文件。
------
#### [ Windows with Visual Studio and .NET Core ]
1. 在 Visual Studio 中，加载您的项目并打开**项目**、**添加引用**。
1. 选择对话框底部的**浏览**按钮。导航到项目的文件夹和将所需的 DLL 文件复制到的子文件夹（例如 `AwsAssemblies`）。
1. 选择所有 DLL 文件，选择**添加**，然后选择**确定**。
1. 保存您的项目。
------
# 为设置 AWS 区域 适用于 .NET 的 AWS SDK
AWS 区域允许您访问实际位于特定地理区域的 AWS 服务。它可用于保证冗余，并保证您的数据和应用程序接近您和用户访问它们的位置。
要查看每项 AWS 服务支持的所有区域和终端节点的当前列表，请参阅中的[服务终端节点和配额*AWS 一般参考*](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)。要查看现有区域端点的列表，请参阅 [AWS 服务终端节点](https://docs.aws.amazon.com/general/latest/gr/rande.html)。要查看有关区域的详细信息，请参阅[指定您的账户可以使用哪些 AWS 区域](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html)。
您可以创建转到[特定区域](#per-client)的 AWS 服务客户端。您还可以为应用程序配置一个将用于[所有 AWS 服务客户端](#globally)的区域。接下来将解释这两种情况。
## 创建具有特定区域的服务客户端
您可以为应用程序中的任何 AWS 服务客户端指定区域。以此方式设置区域优先于该特定服务客户端的任何全局设置。
### 现有区域
此示例向您展示如何在现有区域中实例化 A [mazon EC2 客户端](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/EC2/TEC2Client.html)。它使用已定义的[RegionEndpoint](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TRegionEndpoint.html)字段。
```
using (AmazonEC2Client ec2Client = new AmazonEC2Client(RegionEndpoint.USWest2))
{
// Make a request to EC2 in the us-west-2 Region using ec2Client
}
```
### 使用 RegionEndpoint 类创建新区域
此示例向您展示如何使用构造新的区域终端节点[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
}
```
### 使用服务客户端配置类的新区域
此示例向您展示如何使用服务客户端配置类的`ServiceURL`属性来指定区域；在本例中为使用 [Amazon EC2 Config](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/EC2/TEC2Config.html) 类。
即使区域端点未遵循正规区域端点模式，此技术仍适用。
```
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
}
```
## 为所有服务客户端指定区域
您可以通过多种方式为应用程序创建的所有 AWS 服务客户端指定区域。此区域用于不是通过特定区域创建的服务客户端。
按以下顺序查 适用于 .NET 的 AWS SDK 找 “区域” 值。
### 配置文件
在您的应用程序或软件开发工具包已加载的配置文件中进行设置。有关更多信息，请参阅 [凭证和配置文件解析](creds-assign.md)。
### 环境变量
在 `AWS_REGION` 环境变量中设置。
在 Linux 或 macOS 上：
```
export AWS_REGION='us-west-2'
```
在 Windows 上：
```
set AWS_REGION=us-west-2
```
**注意**
如果你为整个系统设置这个环境变量（使用`export`或`setx`），它会影响所有 SDKs 和工具包，而不仅仅是 适用于 .NET 的 AWS SDK。
### AWSConfigs 班级
设为 [AWSConfigs. AWSRegion](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)财产。
```
AWSConfigs.AWSRegion = "us-west-2";
using (var ec2Client = new AmazonEC2Client())
{
// Make request to Amazon EC2 in us-west-2 Region using ec2Client
}
```
## 区域解析
如果没有使用上述方法来指定 AWS 区域，则会 适用于 .NET 的 AWS SDK 尝试查找 AWS 服务客户端要运行的区域。
**区域解析顺序**
1. 应用程序配置文件，例如 `app.config` 和 `web.config`。
1. 环境变量（`AWS_REGION` 和 `AWS_DEFAULT_REGION`）。
1. 名称由 `AWSConfigs.AWSProfileName` 中的值指定的配置文件。
1. 名称由 `AWS_PROFILE` 环境变量指定的配置文件。
1. `[default]` 配置文件。
1. Amazon EC2 实例元数据（如果在 EC2 实例上运行）。
如果未找到区域，SDK 会抛出异常，指出 AWS 服务客户端没有配置区域。
## 有关中国（北京）区域的特殊信息
要使用中国 (北京) 区域中的服务，您必须拥有特定于中国 (北京) 区域的账户和凭证。其他 AWS 地区的账户和证书不适用于中国（北京）区域。同样，中国（北京）地区的账户和证书不适用于 AWS 其他地区。有关可在中国（北京）区域使用的端点和协议的信息，请参阅[中国（北京）区域端点](https://docs.amazonaws.cn/en_us/aws/latest/userguide/endpoints-Beijing.html)。
## 有关新 AWS 服务的特殊信息
新 AWS 服务最初可以在几个地区推出，然后在其他地区提供支持。在这些情况下，您无需安装最新的软件开发工具包来访问该服务的新区域。您可以按各个客户端或者按全球来指定新添加的区域，如之前所示。
# 凭证和配置文件解析
按特定顺序 适用于 .NET 的 AWS SDK 搜索凭证，并使用当前应用程序的第一组可用凭证。
**凭证搜索顺序**
1. 在 AWS 服务客户端上显式设置的凭证，如中所述[访问应用程序中的凭证和配置文件](creds-locate.md)。
**注意**
该主题之所以出现在[特殊注意事项](special-considerations.md)部分中，是因为它不是指定凭证的首选方法。
1. 从`AWS_ACCESS_KEY_ID``AWS_SECRET_ACCESS_KEY`、和`AWS_SESSION_TOKEN`环境变量创建的@@ [会话 AWSCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TSessionAWSCredentials.html)（如果所有三个变量都有一个值）。
1. 从`AWS_ACCESS_KEY_ID`和`AWS_SECRET_ACCESS_KEY`环境变量创建@@ [的基本AWSCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TBasicAWSCredentials.html)变量（如果两个变量都有值）。
1. [AssumeRoleWithWebIdentityCredentials](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TAssumeRoleWithWebIdentityCredentials.html)如果两个变量都有值，则由`AWS_WEB_IDENTITY_TOKEN_FILE`和`AWS_ROLE_ARN`环境变量创建。
1. 凭据配置文件，其名称由中的值指定[AWSConfigs。 AWSProfile姓名](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html#properties)。
1. 名称由 `AWS_PROFILE` 环境变量指定的凭证配置文件。
1. `[default]` 凭证配置文件。
1. [容器凭证提供商](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)。
1. Amazon EC2 实例元数据。
如果您的应用程序在 Amazon EC2 实例上运行，例如在生产环境中，请使用 IAM 角色，如中所述[使用 IAM 角色授予访问权限](net-dg-hosm.md)。否则，例如在预发行测试中，请将您的凭据存储在文件中，该文件使用您的 Web 应用程序在服务器上可以访问的 AWS 凭据文件格式。
有关环境变量和凭据配置文件的更多信息，请参阅《[AWS SDKs 和工具参考指南](https://docs.aws.amazon.com/sdkref/latest/guide/)》中的以下主题：[环境变量](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)、[环境变量列表](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#EVarSettings)以及[共享配置和凭据文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。
## 配置文件解析
由于有两种不同的凭证存储机制，因此了解如何配置 适用于 .NET 的 AWS SDK 以使用它们非常重要。的[AWSConfigs。 AWSProfiles](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)位置属性控制如何 适用于 .NET 的 AWS SDK 查找凭据配置文件。
****
| AWSProfilesLocation | 配置文件解析行为 |
| --- | --- |
| null (未设置) 或空 | 如果平台支持，请搜索 SDK Store，然后在[默认位置](creds-file.md)搜索共享 AWS 凭证文件。如果配置文件不在上述任何一个位置，请搜索 `~/.aws/config`（Linux 或 macOS）或 `%USERPROFILE%\.aws\config`（Windows）。 |
| AWS 凭证文件格式的文件的路径 | *仅* 在指定文件中搜索具有指定名称的配置文件。 |
## 使用联合用户账户凭证
使用 适用于 .NET 的 AWS SDK （[AWSSDK.Core](https://www.nuget.org/packages/AWSSDK.Core/) 版本 3.1.6.0 及更高版本）的应用程序可以通过 Active Directory 联合身份验证服务 (AD FS) 使用联合用户帐户，通过安全断言标记语言 (SAML) 访问 AWS 服务。
联合访问支持意味着用户可使用您的 Active Directory 进行身份验证。系统将自动为用户授予临时凭证。这些临时证书的有效期为一小时，将在您的应用程序调 AWS 用服务时使用。开发工具包将管理临时凭证。对于已加入域的用户账户，如果您的应用程序发出调用但凭证已过期，则将自动重新验证用户的身份并授予全新凭证。（对于未加入域的帐户，在重新进行身份验证之前，系统会提示用户输入凭据。）
要在.NET 应用程序中使用此支持，必须先使用 PowerShell cmdlet 设置角色配置文件。要了解具体信息，请参阅[AWS Tools for Windows PowerShell 文档](https://docs.aws.amazon.com/powershell/latest/userguide/saml-pst.html)。
设置角色配置文件后，请在应用程序中引用该配置文件。有多种方法可以做到这一点，其中一种是使用[AWSConfigs。 AWSProfile使用与其他凭据配置文件相同的方式命名](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)属性。
大*AWS Security Token Service*会 ([AWSSDK. SecurityToken](https://www.nuget.org/packages/AWSSDK.SecurityToken/)) 提供 SAML 支持以获取 AWS 证书。要使用联合用户账户凭证，请确保您的应用程序可以使用此程序集。
## 指定角色或临时凭证
对于在 Amazon EC2 实例上运行的应用程序，管理证书的最安全方法是使用 IAM 角色，如中所述[使用 IAM 角色授予访问权限](net-dg-hosm.md)。
对于软件可执行文件对组织外部用户可用的应用程序情景，建议您将软件设计为使用*临时安全凭证*。除了提供有限的 AWS 资源访问权限外，这些证书还具有在指定时间段后过期的好处。有关临时安全凭证的更多信息，请参阅：
+ [临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
+ [Amazon Cognito 身份池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)
## 使用代理凭证
如果您的软件 AWS 通过代理与通信，则可以使用服务`Config`类的`ProxyCredentials`属性为代理指定凭据。服务的 `Config` 类通常是该服务主命名空间的一部分。示例包括以下内容：[AmazonCloudDirectoryConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudDirectory/TCloudDirectoryConfig.html)在 [Amazon 中。 CloudDirectory](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudDirectory/NCloudDirectory.html)命名空间和[AmazonGameLiftConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/GameLift/TGameLiftConfig.html)在 [Amazon 中。 GameLift](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/GameLift/NGameLift.html)命名空间。
例如，对于 [Amazon S3](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html)，您可以使用类似于以下内容的代码，其中`SecurelyStoredUserName`和`SecurelyStoredPassword`是在[NetworkCredential](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkcredential)对象中指定的代理用户名和密码。
```
AmazonS3Config config = new AmazonS3Config();
config.ProxyCredentials = new NetworkCredential(SecurelyStoredUserName, SecurelyStoredPassword);
```
**注意**
早期版本的开发工具包使用的是 `ProxyUsername` 和 `ProxyPassword`，但这两个属性已被弃用。
# 重试和超时
适用于 .NET 的 AWS SDK 允许您为向 AWS 服务发出的 HTTP 请求配置重试次数和超时值。如果重试和超时的默认值不适用于您的应用程序，您可以针对具体要求调整这些值，但请务必了解这样做将对应用程序的行为带来什么影响。
在确定重试和超时值时，请考虑以下因素：
+ 当网络连接下降或 AWS 服务无法访问时， 适用于 .NET 的 AWS SDK 和您的应用程序应如何响应？ 您是希望调用快速失败，还是希望调用代表您不断重试？
+ 您的应用程序是必须能够及时响应的面向用户的应用程序或网站，还是更能容忍延迟增加的后台处理任务？
+ 应用程序是部署在具有低延迟的可靠网络上，还是部署在具有不可靠连接的远程位置？
## 重试
### 概述
适用于 .NET 的 AWS SDK 可以重试因服务器端限制或连接中断而失败的请求。服务配置类有两个属性可用于指定服务客户端的重试行为。服务配置类继承了抽象的 [Amazon.Runtime 中的这些属性。 ](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)ClientConfig[适用于 .NET 的 AWS SDK API 参考](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/)的类别：
+ `RetryMode`指定三种重试模式之一，这些模式[在 Amazon.Runtime 中定义。 RequestRetryMode](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TRequestRetryMode.html)枚举。
可以使用`AWS_RETRY_MODE`环境变量或共享 AWS 配置文件中的 *retry\$1mod* e 设置来控制应用程序的默认值。
+ `MaxErrorRetry` 指定服务客户端级别允许的重试次数；SDK 会在失败并引发异常之前按指定的次数重试该操作。
可以使用`AWS_MAX_ATTEMPTS`环境变量或共享 AWS 配置文件中的 *max\$1* tempts 设置来控制应用程序的默认值。
这些属性的详细描述可以在摘要的 [Amazon.Runtime 中找到。 ](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)ClientConfig[适用于 .NET 的 AWS SDK API 参考](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/)的类别。默认情况下，`RetryMode` 的每个值对应一个特定的 `MaxErrorRetry` 值，如下表所示。
| | | |
| --- |--- |--- |
| Legacy | 10 | 4 |
| 标准 | 10 | 2 |
| 自适应（实验性） | 10 | 2 |
### 行为
**当应用程序启动时**
应用程序启动时，`RetryMode` 和 `MaxErrorRetry` 的默认值由 SDK 配置。除非您指定其它值，否则在创建服务客户端时将使用这些默认值。
+ 如果您的环境中未设置这些属性，则 `RetryMode` 的默认值将配置为 *Legacy*，而 `MaxErrorRetry` 的默认值将配置为上表中的相应值。
+ 如果您的环境中设置了重试模式，则该值将用作 `RetryMode` 的默认值。`MaxErrorRetry` 的默认值将配置为上表中的相应值，除非您的环境中也设置了最大错误的值（下文将介绍）。
+ 如果您的环境中设置了最大错误的值，则该值将用作 `MaxErrorRetry` 的默认值。Amazon DynamoDB 是该规则的例外；`MaxErrorRetry` 的默认 DynamoDB 值始终是上表中的值。
**当您的应用程序运行时**
创建服务客户端时，可以使用 `RetryMode` 和 `MaxErrorRetry` 的默认值（如前所述），也可以指定其它值。要指定其他值，请在创建服务客户端SQSConfig时创建并包含服务配置对象，例如[AmazonDynamoDBConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/DynamoDBv2/TDynamoDBConfig.html)或 [Amazon](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/SQS/TSQSConfig.html)。
一旦为服务客户端创建这些值，便不可更改。
**注意事项**
在进行重试时，会增加请求的延迟。您应根据应用程序对请求总延迟和错误率的限制来配置重试次数。
## 超时
适用于 .NET 的 AWS SDK 使您能够在服务客户端级别和每个方法调用配置请求超时。有两种配置超时的机制，后续章节将介绍这些机制：
+ 如果您使用的是[异步调用](#timeouts-async)，则可以使用该方法的 `CancellationToken` 参数。
+ 如果您[在.NET 框架中使用同步调用](#timeouts-sync-framework)，则可以使用抽象 [Amazon.Runtime 的`Timeout`和`ReadWriteTimeout`属性。 ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)班级。
### 使用 `CancellationToken` 参数配置超时
适用于 .NET 的 AWS SDK 允许您使用`CancellationToken`参数配置异步调用的请求超时。下面的代码片段展示了一个示例。如果请求未在 10 秒内完成，则代码会引发 `System.Threading.Tasks.TaskCanceledException`。
```
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);
}
```
### 使用 `Timeout` 和 `ReadWriteTimeout` 属性配置超时
**注意**
`Timeout` 属性不会影响异步调用。如果您使用的是异步调用，请参阅[使用 `CancellationToken` 参数配置超时](#timeouts-async)。
适用于 .NET 的 AWS SDK 使您能够在服务客户端级别配置请求超时和套接字 read/write 超时值。这些值是在抽象 [Amazon.Runtime 的`Timeout`和`ReadWriteTimeout`属性中指定的。 ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)班级。这些值作为 AWS 服务客户端[HttpWebRequest](https://learn.microsoft.com/en-us/dotnet/api/system.net.httpwebrequest)对象创建的对象的`Timeout`和`ReadWriteTimeout`属性传递。默认情况下，`Timeout` 值为 100 秒，`ReadWriteTimeout` 值为 300 秒。
当您的网络具有高延迟或存在导致操作重试的情况时，使用较长的超时值和较高的重试次数会导致一些开发工具包操作看上去没有响应。
**注意**
以便携式类库 (PCL) 为目标的版本使用该[HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient)类而不是`HttpWebRequest`类，并且仅支持 [Timeout](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout) 属性。 适用于 .NET 的 AWS SDK
以下是默认超时值的例外情况。明确设置超时值时将覆盖这些值。
+ `Timeout`如果被调用的方法上传直播（例如 [Amazons3Client），则设置为最大值。`ReadWriteTimeout` 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)，依此类推。
+ 适用于 .NET 的 AWS SDK 该目标.NET 框架的版本设置为所有 [Amazons3Clien](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) t `Timeout` 和`ReadWriteTimeout`对象的最大值。[AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Glacier/TGlacierClient.html)
+ 针对便携式类库 (PCL) 和.NET Core 的版本设置`Timeout`为所有 [Amazons3](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) Client 和对象的最大值。 适用于 .NET 的 AWS SDK [AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Glacier/TGlacierClient.html)
以下示例说明如何指定*标准*重试模式、最多 3 次重试、10 秒超时和 10 秒 read/write 超时（如果适用）。[Amazons3Client](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Client.html) 构造函数被赋予一个 [AmazonS3Config](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html) 对象。
```
var s3Client = new AmazonS3Client(
new AmazonS3Config
{
Timeout = TimeSpan.FromSeconds(10),
// NOTE: The following property is obsolete for
// versions of the 适用于 .NET 的 AWS SDK that target .NET Core.
ReadWriteTimeout = TimeSpan.FromSeconds(10),
RetryMode = RequestRetryMode.Standard,
MaxErrorRetry = 3
});
```
# 可观测性
可观测性是指可以根据系统发出的数据推断出其当前状态的程度。发出的数据通常称为遥测。
适用于 .NET 的 AWS SDK 可以提供两种常见的遥测信号、指标和轨迹以及日志记录。您可以连接[TelemetryProvider](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html)以将遥测数据发送到可观测性后端（例如或 [AWS X-Ray](https://docs.aws.amazon.com/xray/?icmpid=docs_homepage_devtools)A [ma](https://docs.aws.amazon.com/cloudwatch/?icmpid=docs_homepage_mgmtgov) zon CloudWatch），然后对其进行操作。
默认情况下，SDK 中的遥测信号处于禁用状态。本主题介绍如何启用和配置遥测输出。
## 其他资源
有关启用和使用可观测性的更多信息，请参阅以下资源：
+ [OpenTelemetry](https://opentelemetry.io/)
+ 博客文章《[增强可观察性 适用于 .NET 的 AWS SDK 》 OpenTelemetry](https://aws.amazon.com/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/)
+ 博客文章[宣布 AWS .NET OpenTelemetry 库正式上市](https://aws.amazon.com/blogs/dotnet/announcing-the-general-availability-of-aws-net-opentelemetry-libraries/)。
+ [的出口商 OpenTelemetry](https://opentelemetry.io/docs/languages/net/exporters/)
+ 有关可观测性的示例 AWS Tools for PowerShell，请参阅《[ PowerShell 用户工具](https://docs.aws.amazon.com/powershell/latest/userguide/)指南》中的[可观察性](https://docs.aws.amazon.com/powershell/latest/userguide/observability.html)。
## 配置 `TelemetryProvider`
您可以在应用程序中为所有服务客户端或单个客户端全局配置 `TelemetryProvider`，如以下示例所示。[遥测提供商](observability-telemetry-providers.md)一节提供了有关遥测实现的信息，包括有关随 SDK 提供的实现的信息。
### 配置默认的全局遥测提供程序
默认情况下，每个服务客户端都尝试使用全局可用的遥测提供程序。这样，您只需设置一次提供程序，所有客户端都会使用它。此操作只需执行一次，且必须在创建任何服务客户端之前进行。
以下代码片段展示了如何设置全局遥测提供程序。然后，它会创建一个 Amazon S3 服务客户端，并尝试执行失败的操作。该代码向应用程序添加追踪记录和指标。此代码使用以下 NuGet 软件包：`OpenTelemetry.Exporter.Console`和`OpenTelemetry.Instrumentation.AWS`。
**注意**
如果您使用身份 AWS IAM Identity Center 验证，请务必同时添加`AWSSDK.SSO`和`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();
```
### 为特定服务客户端配置遥测提供程序
您可以为单个服务客户端配置特定的遥测提供程序（而不是全局遥测提供程序）。为此，请使用服务客户端构造函数的 Config 对象的 `TelemetryProvider` 类。例如，请参阅 [AmazonS3Config](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/S3/TS3Config.html) 并找到 `TelemetryProvider` 属性。有关自定义遥测实现的信息，请参阅[遥测提供商](observability-telemetry-providers.md)。
**Topics**
+ [其他资源](#observability-resources)
+ [配置 `TelemetryProvider`](#observability-conf-telemetry-provider)
+ [Metrics](observability-metrics.md)
+ [遥测提供商](observability-telemetry-providers.md)
# Metrics
下表列出了 SDK 发出的遥测指标。[配置遥测提供程序](observability.md#observability-conf-telemetry-provider)以使指标可观察。
**发布了哪些指标？**
| 指标名称 | 单位 | 类型 | Attributes | 描述 |
| --- | --- | --- | --- | --- |
| client.call.持续时间 | s | 直方图 | rpc.service，rpc.m | 总体呼叫时长（包括重试次数、发送或接收请求和响应正文的时间） |
| 客户机正常运行时间 | s | 直方图 | rpc. 服务 | 自创建客户机以来的时间长度 |
| client.call.tept | \$1尝试\$1 | MonotonicCounter | rpc.service，rpc.m | 单个操作的尝试次数 |
| client.call.errors | \$1错误\$1 | MonotonicCounter | rpc.service、rpc.method、excep | 某项操作的错误数 |
| client.call.tempt\$1duration | s | 直方图 | rpc.service，rpc.m | 连接到服务、发送请求以及取回 HTTP 状态码和标头所花费的时间（包括等待发送的排队时间） |
| client.call.resolve\$1endpoint\$1持续时间 | s | 直方图 | rpc.service，rpc.m | 为请求解析终端节点（终端节点解析器，不是 DNS）所花费的时间 |
| client.call.serialization\$1dur | s | 直方图 | rpc.service，rpc.m | 序列化消息正文所花费的时间 |
| client.call.derization\$1duration\$1 | s | 直方图 | rpc.service，rpc.m | 反序列化消息正文所花费的时间 |
| client.col.auth.signing\$1duration | s | 直方图 | rpc.service，rpc.m | 签署请求所花费的时间 |
| client.col.auth.resolve\$1identity\$1duration | s | 直方图 | rpc.service，rpc.m | 从身份提供商处获取身份（例如 AWS 凭证或持有者令牌）所花费的时间 |
| client.http.bytes\$1sent | 方式 | MonotonicCounter | 服务器地址 | HTTP 客户端发送的总字节数 |
| client.http.bytes\$1receiv | 方式 | MonotonicCounter | 服务器地址 | HTTP 客户端接收的总字节数 |
以下是各列的描述：
+ **指标名称**-发出的指标的名称。
+ **单位**-指标的计量单位。单位以 UC [UM](https://unitsofmeasure.org/ucum) 区分大小写 (“c/s”) 表示法给出。
+ **类型**-用于捕获指标的仪器类型。
+ **属性**-与指标一起发出的一组属性（维度）。
+ **描述**-对指标所衡量内容的描述。
# 遥测提供商
SDK 提供了[OpenTelemetry](https://opentelemetry.io/)作为遥测提供商的实现，[下一节](observability-telemetry-providers-otel.md)将对此进行介绍。
如果您有特定的遥测要求，已经在考虑遥测解决方案，或者需要精细控制遥测数据的捕获和处理方式，则也可以实现自己的遥测提供程序。
在[TelemetryProvider](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TTelemetryProvider.html)课堂上注册你自己的实现。以下是如何注册自己的`TracerProvider`和的简单示例`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)
# 配置 OpenTelemetry基于遥测的提供商
适用于 .NET 的 AWS SDK 包括 OpenTelemetry基于遥测提供程序的实现。有关如何将此提供程序设置为全局遥测提供程序的详细信息，请参阅[配置 `TelemetryProvider`](observability.md#observability-conf-telemetry-provider)。要使用此遥测提供程序，您需要以下项目资源：
+ .Instrum [OpenTelemetryentation.aws](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AWS) NuGet 软件包。
+ 遥测导出器，例如 OTLP 或控制台。有关更多信息，请参阅 OpenTelemetry文档[中的](https://opentelemetry.io/docs/languages/net/exporters/)导出器。
可以对 SDK 中包含的 OpenTelemetry 实现进行配置，以减少对 HTTPS 请求、凭证和压缩的跟踪量。为此，请将 `SuppressDownstreamInstrumentation` 选项设置为 `true`，类似于以下内容：
```
Sdk.CreateTracerProviderBuilder()
.ConfigureResource(e => e.AddService("DemoOtel"))
.AddAWSInstrumentation(options => options.SuppressDownstreamInstrumentation = true)
.AddConsoleExporter()
.Build();
```
有关此提供商的更多信息，请参阅 with [中的博客文章 “ 适用于 .NET 的 AWS SDK 增强可观察性](https://aws.amazon.com/blogs/developer/enhancing-observability-in-the-aws-sdk-for-net-with-opentelemetry/)”。 OpenTelemetry
# 有关用户和角色的其它信息
要在.NET 上进行.NET 开发 AWS 或在上 AWS运行.NET 应用程序，需要有适合这些任务的用户、权限集和服务角色的某种组合。
您创建的特定用户、权限集和服务角色以及使用它们的方式，将取决于您应用程序的要求。下面的一些附加信息介绍了可能使用它们的原因以及如何创建它们。
## 用户和权限集
尽管可以使用具有长期凭证的 IAM 用户账户来访问 AWS 服务，但这已不再是最佳实践，应予以避免。即使在开发过程中，最佳做法也是在中创建用户和权限集 AWS IAM Identity Center 并使用身份源提供的临时证书。
对于开发，您可以使用自己创建的或在[使用进行身份验证 AWS](creds-idc.md)中提供的用户。如果您拥有适当的 AWS 管理控制台 权限，还可以为该用户创建权限最低的不同权限集，或者创建专门用于开发项目的新用户，提供权限最小的权限集。您选择的行动方案（如果有）取决于您的情况。
有关这些用户和权限集以及如何创建它们的更多信息，请参阅*工具参考指南中的[身份验证AWS SDKs 和访问](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)权限以及*AWS IAM Identity Center 用户指南**中的[入门](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html)。
## 服务角色
您可以设置 AWS 服务角色来代表用户访问 AWS 服务。如果有多人远程运行您的应用程序，则这种访问方式是合适的；例如，在您为此目的创建的 Amazon EC2 实例上。
创建服务角色的过程因情况而异，但基本上如下所示。
1. 登录 AWS 管理控制台 并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 选择 **角色**，然后选择 **创建角色**。
1. 选择**AWS 服务**，查找并选择 **EC2**（例如），然后选择**EC2**用例（例如）。
1. 选择 “**下一步：权限**”，然后为应用程序将使用的 AWS 服务选择[相应的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)。
**警告**
请***勿***选择该**AdministratorAccess**策略，因为该策略允许您账户中几乎所有内容的读取和写入权限。
1. 选择**下一步: 标签**，然后输入所需的任何标签。
您可以在 [IAM 用户指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)中[使用 AWS 资源标签控制访问权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html)中找到有关标签的信息。
1. 选择**下一步: 查看**，并提供**角色名称**和**角色描述**。然后选择**创建角色**。
在 [IAM 用户指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)中的[身份（用户、用户组和角色）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)中，您可以找到有关 IAM 角色的高级信息。在 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)主题中查找有关角色的详细信息。
**有关角色的其它信息**
+ 对于 Amazon Elastic Container Service (Amazon ECS)，使用[适用于任务的 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)。
+ 对[在 Amazon EC2 实例上运行的应用程序使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。
# 适用于 .NET 的 AWS SDK 项目的高级配置
本部分中的主题包含有关您可能感兴趣的其它配置任务和方法的信息。
**Topics**
+ [AWSSDK. 扩展。 NETCore.Setup 和 IConfiguration](net-dg-config-netcore.md)
+ [配置其他应用程序参数](net-dg-config-other.md)
+ [的配置文件参考 适用于 .NET 的 AWS SDK](net-dg-config-ref.md)
# 使用 AWSSDK .Extions。 NETCore.Setup 和界面 IConfiguration
（本主题之前的标题是 “ 适用于 .NET 的 AWS SDK 使用.NET 核心配置”）
.NET Core 中最大的改变之一是删除了以前在 .NET Framework 和 ASP.NET 应用程序中使用的 `ConfigurationManager` 以及标准 `app.config` 和 `web.config` 文件。
.NET Core 中的配置基于配置提供商建立的键/值对。配置提供商将配置数据从各种配置源读取为键/值对，包括命令行参数、目录文件、环境变量和设置文件。
**注意**
有关更多信息，请参阅 [ASP.NET Core 中的配置](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration)。
为了便于在.NET Core 中 适用于 .NET 的 AWS SDK 使用，你可以使用.E [AWSSDKxtensions。 NETCore.安装](https://www.nuget.org/packages/AWSSDK.Extensions.NETCore.Setup/) NuGet 包。与许多.NET Core 库一样，它向`IConfiguration`接口添加了扩展方法，以实现无缝 AWS 配置。
该软件包的源代码 GitHub 位于[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)。
## 使用 AWSSDK .Extions。 NETCore.Setup
假设你创建了一个 ASP.NET Core Model-View-Controller (MVC) 应用程序，可以使用 Visual Studio 中的 **ASP.NET Core Web 应用程序**模板或在.NET Core CLI `dotnet new mvc ...` 中运行来完成。创建此类应用程序时，`Startup.cs` 的构造函数通过从配置提供商读取各种输入源来处理配置，例如读取 `appsettings.json`。
```
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
```
要使用`Configuration`对象获取*AWS*选项，请先添加`AWSSDK.Extensions.NETCore.Setup` NuGet 软件包。然后，将选项添加到下面所述的配置文件中。
请注意，添加到您项目中的其中一个文件是 `appsettings.Development.json`。这就代表 `EnvironmentName` 设置为 **Development**。在开发过程中，将配置放入此文件中，该文件只能在本地测试期间读取。当您部署已`EnvironmentName`设置为**生产**的 Amazon EC2 实例时，该文件将被忽略，并回退到为 Amazon EC2 实例配置的 IAM 证书和区域。 适用于 .NET 的 AWS SDK
以下配置设置显示您可以添加到您项目的 `appsettings.Development.json` 文件中用于提供 AWS 设置的值的示例。
```
{
"AWS": {
"Profile": "local-test-profile",
"Region": "us-west-2"
},
"SupportEmail": "TechSupport@example.com"
}
```
要访问 *CSHTML* 文件中的设置，请使用 `Configuration` 指令：
```
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
Contact
Support: @Configuration["SupportEmail"]
```
要从代码访问文件中设置的 AWS 选项，请调用添加到的`GetAWSOptions`扩展方法`IConfiguration`。
要从这些选项构造服务客户端，请调用 `CreateServiceClient`。以下示例代码说明了如何创建 Amazon S3 服务客户端。（请务必将 [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3) NuGet 包添加到您的项目中。）
```
var options = Configuration.GetAWSOptions();
IAmazonS3 client = options.CreateServiceClient();
```
您还可以使用 `appsettings.Development.json` 文件中的多个条目创建具有不兼容设置的多个服务客户端，如以下示例所示，其中 `service1` 的配置包括 `us-west-2` 区域，`service2` 的配置包括特殊端点 *URL*。
```
{
"service1": {
"Profile": "default",
"Region": "us-west-2"
},
"service2": {
"Profile": "default",
"ServiceURL": "URL"
}
}
```
然后，您可以使用 JSON 文件中的条目获取特定服务的选项。例如，要获取 `service1` 的设置，请使用以下项目。
```
var options = Configuration.GetAWSOptions("service1");
```
### appsettings 文件中允许的值
以下应用程序配置值可以在 `appsettings.Development.json` 文件中设置。字段名必须使用所示的大小写。有关这些设置的详细信息，请参阅 `[AWS.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Runtime/TClientConfig.html)` 类。
+ Region
+ 配置文件
+ ProfilesLocation
+ SignatureVersion
+ RegionEndpoint
+ UseHttp
+ ServiceURL
+ AuthenticationRegion
+ AuthenticationServiceName
+ MaxErrorRetry
+ LogResponse
+ BufferSize
+ ProgressUpdateInterval
+ ResignRetries
+ AllowAutoRedirect
+ LogMetrics
+ DisableLogging
+ UseDualstackEndpoint
## ASP.NET Core 依赖关系注入
*AWSSDK.Extensions NETCore.Setup* NuGet 包还与 ASP.NET Core 中的新依赖注入系统集成。应用程序的 `Startup` 类中的 `ConfigureServices` 方法是添加 MVC 服务的位置。如果应用程序正在使用实体框架，则这也是进行初始化的位置。
```
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
}
```
**注意**
有关 .NET Core 中依赖关系注入的背景信息在 [.NET Core 文档网站](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection)上提供。
该`AWSSDK.Extensions.NETCore.Setup` NuGet 软件包添加了新的扩展方法`IServiceCollection`，您可以使用这些方法向依赖注入中添加 AWS 服务。以下代码向您展示了如何添加从中读取的 AWS 选项，`IConfiguration`以便将 Amazon S3 和 DynamoDB 添加到服务列表中。（请务必将 [AWSSDK.S3 和AWSSDK.](https://www.nuget.org/packages/AWSSDK.S3) [Dynamo DBv2](https://www.nuget.org/packages/AWSSDK.DynamoDBv2) NuGet 包添加到您的项目中。）
```
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
services.AddAWSService();
services.AddAWSService();
}
```
现在，如果您的 MVC 控制器使用 `IAmazonS3` 或 `IAmazonDynamoDB` 作为其构造函数中的参数，则依赖关系注入系统会传入这些服务。
```
public class HomeController : Controller
{
IAmazonS3 S3Client { get; set; }
public HomeController(IAmazonS3 s3Client)
{
this.S3Client = s3Client;
}
...
}
```
# 配置其他应用程序参数
**注意**
本主题中的信息特定于基于 .NET Framework 的项目。默认情况下，`App.config` 和 `Web.config` 文件不存在于基于 .NET Core 的项目中。
## 打开查看 .NET Framework 内容
可配置多种应用程序参数：
+ `AWSLogging`
+ `AWSLogMetrics`
+ `AWSRegion`
+ `AWSResponseLogging`
+ `AWS.DynamoDBContext.TableNamePrefix`
+ `AWS.S3.UseSignatureVersion4`
+ `AWSEndpointDefinition`
+ [AWS 服务生成的终端节点](#config-setting-service-generated-awsendpointdefinition)
这些参数可以在应用程序的 `App.config` 或 `Web.config` 文件中配置。尽管您也可以使用 适用于 .NET 的 AWS SDK API 对其进行配置，但我们建议您使用应用程序的`.config`文件。此处介绍了这两种方法。
有关本主题后文中所述的使用 `` 元素的更多信息，请参阅[适用于 .NET 的 AWS SDK配置文件参考](net-dg-config-ref.md)。
### AWSLogging
配置开发工具包应如何记录事件 (如果记录)。例如，建议的方法是使用 `` 元素，该元素是 `` 元素的子元素：
```
```
或者：
```
```
可能的值包括：
** `None` **
禁用 事件日志记录。这是默认值。
** `log4net` **
使用 log4net 记录。
** `SystemDiagnostics` **
使用 `System.Diagnostics` 类记录。
您可以为 `logTo` 属性设置多个值，以逗号分隔。以下示例在 `.config` 文件中设置 `log4net` 和 `System.Diagnostics` 日志记录：
```
```
或者：
```
```
或者，使用 适用于 .NET 的 AWS SDK API 合并[LoggingOptions](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TLoggingOptions.html)枚举值并设置 [AWSConfigs.Logging](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) 属性：
```
AWSConfigs.Logging = LoggingOptions.Log4Net | LoggingOptions.SystemDiagnostics;
```
对此设置的更改仅对新的 AWS 客户端实例生效。
### AWSLog指标
指定开发工具包是否应记录性能指标。要在 `.config` 文件中设置指标日志记录配置，请在 `` 元素中设置 `logMetrics` 属性值，该元素是 `` 元素的子元素：
```
```
此外，在 `` 部分中设置 `AWSLogMetrics` 关键字：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置指标日志记录，请设置[AWSConfigs。 LogMetrics](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)财产:
```
AWSConfigs.LogMetrics = true;
```
对于所有客户端/配置，此设置用于配置默认 `LogMetrics` 属性。对此设置的更改仅对新的 AWS 客户端实例生效。
### AWSRegion
为未明确指定 AWS 区域的客户端配置默认区域。要在 `.config` 文件中设置区域，建议的方法是在 `aws` 元素中设置 `region` 属性值：
```
```
此外，在 `` 部分中设置 *AWSRegion* 关键字：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置区域，请设置[AWSConfigs。 AWSRegion](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)财产:
```
AWSConfigs.AWSRegion = "us-west-2";
```
有关为特定区域创建 AWS 客户端的更多信息，请参阅[AWS 区域选择](net-dg-region-selection.md)。对此设置的更改仅对新的 AWS 客户端实例生效。
### AWSResponse正在记录
配置开发工具包在什么情况下记录服务响应。可能的值包括：
** `Never` **
从不记录服务响应。这是默认值。
** `Always` **
始终记录服务响应。
** `OnError` **
仅在出错时记录服务响应。
要在 `.config` 文件中设置服务日志记录配置，推荐的方法是在 `` 元素中设置 `logResponses` 属性值，该元素是 `` 元素的子元素：
```
```
或者，在以下``部分中*AWSResponse设置 Logging* 密钥：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置服务日志记录，请设置[AWSConfigs。 ResponseLogging](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)将属性设置为[ResponseLoggingOption](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TResponseLoggingOption.html)枚举的其中一个值：
```
AWSConfigs.ResponseLogging = ResponseLoggingOption.OnError;
```
对此设置的更改会立即生效。
### `AWS.DynamoDBContext.TableNamePrefix`
配置 `TableNamePrefix` 将使用的默认 `DynamoDBContext` (在未手动配置的情况下)。
要在 `.config` 文件中设置表名前缀，建议的方法是在 `` 元素中设置 `tableNamePrefix` 属性值，该元素是 `` 元素 (这又是 `` 的子元素) 的子元素：
```
```
此外，在 `` 部分中设置 `AWS.DynamoDBContext.TableNamePrefix` 关键字：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置表名前缀，请设置 [AWSConfigs.Dynamo 属性 DBContext TableNamePrefix](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)：
```
AWSConfigs.DynamoDBContextTableNamePrefix = "Test-";
```
对此设置的更改仅在新构建的 `DynamoDBContextConfig` 和 `DynamoDBContext` 实例中生效。
### `AWS.S3.UseSignatureVersion4`
配置 Amazon S3 客户端是否应使用签名版本 4 对请求签名。
要在 `.config` 文件中为 Amazon S3 设置签名版本 4 的签名，推荐的方法是在 `` 元素中设置 `useSignatureVersion4` 属性，该元素是 `` 元素的子元素：
```
```
此外，在 `` 部分中将 `AWS.S3.UseSignatureVersion4` 密钥设置为 `true`：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置签名版本 4 签名，请将 [AWSConfigs.S3 UseSignatureVersion 4](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html) 属性设置为：`true`
```
AWSConfigs.S3UseSignatureVersion4 = true;
```
默认情况下，此设置是 `false`，但在某些情况下或者在某些区域中，默认会使用签名版本 4。当设置为 `true` 时，签名版本 4 将用于所有请求。对此设置的更改仅对新 Amazon S3 客户端实例生效。
### AWSEndpoint定义
配置开发工具包是否应使用自定义配置文件，该文件定义区域和终端节点。
要在 `.config` 文件中设置终端节点定义文件，建议在 `` 元素中设置 `endpointDefinition` 属性值。
```
```
或者，你可以在以下``部分中设置*AWSEndpoint定义*密钥：
```
```
或者，要使用 适用于 .NET 的 AWS SDK API 设置端点定义文件，请设置[AWSConfigs。 EndpointDefinition](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)财产:
```
AWSConfigs.EndpointDefinition = @"c:\config\endpoints.json";
```
如果没有提供文件名，则不使用自定义配置文件。对此设置的更改仅对新的 AWS 客户端实例生效。该`endpoints.json`文件可从中获得[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 服务生成的终端节点
有些 AWS 服务会生成自己的终端节点，而不是使用区域终端节点。这些服务的客户端使用特定于该服务的服务 URL 以及您的资源。这些服务的两个例子是 Amazon CloudSearch 和 AWS IoT。以下示例演示如何获取这些服务的终端节点。
#### Amazon CloudSearch 终端节点示例
亚马逊 CloudSearch 客户端用于访问亚马逊 CloudSearch 配置服务。您可以使用 Amazon CloudSearch 配置服务创建、配置和管理搜索域。要创建搜索域，请创建一个[CreateDomainRequest](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCreateDomainRequest.html)对象并提供该`DomainName`属性。使用请求[AmazonCloudSearchClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCloudSearchClient.html)对象创建对象。调用 [CreateDomain](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/MCloudSearchCreateDomainCreateDomainRequest.html) 方法。调用返回的[CreateDomainResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearch/TCreateDomainResponse.html)对象包含一个同时具有`DocService`和`SearchService`端点的`DomainStatus`属性。创建一个[AmazonCloudSearchDomainConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearchDomain/TCloudSearchDomainConfig.html)对象并使用它来初始化该[AmazonCloudSearchDomainClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/CloudSearchDomain/TCloudSearchDomainClient.html)类的`SearchService`实例`DocService`和实例。
```
// 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 端点示例
要获取的终端节点 AWS IoT，请创建一个[AmazonIoTClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/TIoTClient.html)对象并调用[DescribeEndPoint](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/MIoTDescribeEndpointDescribeEndpointRequest.html)方法。返回的[DescribeEndPointResponse](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IoT/TDescribeEndpointResponse.html)对象包含`EndpointAddress`。创建[AmazonIotDataConfig](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IotData/TIotDataConfig.html)对象，设置`ServiceURL`属性，然后使用该对象实例化该类。[AmazonIotDataClient](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/IotData/TIotDataClient.html)
```
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");
}
```
# 的配置文件参考 适用于 .NET 的 AWS SDK
**注意**
本主题中的信息特定于基于 .NET Framework 的项目。默认情况下，`App.config` 和 `Web.config` 文件不存在于基于 .NET Core 的项目中。
## 打开查看 .NET Framework 内容
您可以使用.NET 项目`App.config`或`Web.config`文件来指定 AWS 设置，例如 AWS 证书、日志选项、 AWS 服务终端节点和 AWS 区域，以及一些 AWS 服务的设置，例如亚马逊 DynamoDB、Amazon 和 Ama EC2 zon S3。以下信息介绍了如何正确设置 `App.config` 或 `Web.config` 文件的格式，以指定这些设置类型。
**注意**
尽管您可以继续使用`App.config`或`Web.config`文件中的``元素来指定 AWS 设置，但我们建议您按照本主题后面的说明使用``和``元素。有关该``元素的更多信息，请参阅[配置 适用于 .NET 的 AWS SDK 应用程序中的``](net-dg-config.md)元素示例。
**注意**
尽管您可以继续在代码文件中使用以下[https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html](https://docs.aws.amazon.com/sdkfornet/v4/apidocs/items/Amazon/TAWSConfigs.html)类属性来指定 AWS 设置，但以下属性已过时，将来的版本可能不支持这些属性：
`DynamoDBContextTableNamePrefix`
`EC2UseSignatureVersion4`
`LoggingOptions`
`LogMetrics`
`ResponseLoggingOption`
`S3UseSignatureVersion4`
通常，我们建议您不要在代码文件中使用`AWSConfigs`类属性来指定 AWS 设置，而应使用`App.config`或`Web.config`文件中的``和``元素来指定 AWS 设置，如本主题后面所述。有关上述属性的更多信息，请参阅[配置 适用于 .NET 的 AWS SDK 应用程序](net-dg-config.md)中的`AWSConfigs`代码示例。
**Topics**
+ [声明 AWS 设置部分](#net-dg-config-ref-declaring)
+ [允许的元素](#net-dg-config-ref-elements)
+ [元素参考](#net-dg-config-ref-elements-ref)
### 声明 AWS 设置部分
您可以从``元素内部在`App.config`或`Web.config`文件中指定 AWS 设置。在开始使用 `` 元素之前，您必须先创建一个 `` 元素 (`` 元素的子元素) 并将其 `name` 属性和 `aws` 属性分别设置为 `type` 和 `Amazon.AWSSection, AWSSDK.Core` (如以下示例所示)：
```
...
...
```
Visual Studio 编辑器不为``元素或其子元素提供自动代码完成功能 (IntelliSense)。
调用 `` 方法可帮助您创建 `Amazon.AWSConfigs.GenerateConfigTemplate` 元素格式正确的版本。这将以美观打印字符串形式输出 `` 元素的规范版本，可调整该字符串以满足您的需求。以下部分介绍 `` 元素的属性和子元素。
### 允许的元素
以下是 AWS 设置部分中允许的元素之间的逻辑关系列表。要生成此列表的最新版本，您可以调用 `Amazon.AWSConfigs.GenerateConfigTemplate` 方法，这将以字符串形式输出 `` 元素的规范版本，可调整该字符串以满足您的需求。
```
```
### 元素参考
以下是 AWS 设置部分中允许使用的元素的列表。对于每个元素，将列出其允许的属性和父-子元素。
**Topics**
+ [别名](#net-dg-config-ref-elements-alias)
+ [`aws`](#net-dg-config-ref-elements-aws)
+ [dynamoDB](#net-dg-config-ref-elements-dynamodb)
+ [发电机 DBContext](#net-dg-config-ref-elements-ddbcontext)
+ [ec2](#net-dg-config-ref-elements-ec2)
+ [logging](#net-dg-config-ref-elements-logging)
+ [映射](#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)
#### 别名
`` 元素表示集合中的一个项，该集合包含一个或多个源表到目标表的映射，用于指定与为某一类型配置的表不同的表。此元素将从 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.DynamoDBConfig.Context.TableAliases` 属性映射到 `Amazon.Util.TableAlias` 类的实例。在应用表名称前缀之前，将执行重新映射。
此元素可以包含以下属性：
** `fromTable` **
源表到目标表的映射的源表部分。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.Util.TableAlias.FromTable` 属性。
** `toTable` **
源表到目标表的映射的目标表部分。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.Util.TableAlias.ToTable` 属性。
`` 元素的父级为 `` 元素。
`` 元素不包含子元素。
以下是使用中的 `` 元素的示例：
```
```
#### `aws`
该``元素代表 AWS 设置部分中最上面的元素。此元素可以包含以下属性：
** `endpointDefinition` **
定义要使用的 AWS 区域和端点的自定义配置文件的绝对路径。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.EndpointDefinition` 属性。
** `profileName` **
用于进行服务调用的存储 AWS 凭据的配置文件名称。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.AWSProfileName` 属性。
** `profilesLocation` **
指向与其他人共享的凭据文件位置的绝对路径 AWS SDKs。默认情况下，凭证文件存储在当前用户主目录的 `.aws` 目录中。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.AWSProfilesLocation` 属性。
** `region` **
未明确指定 AWS 区域的客户端的默认区域 ID。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.AWSRegion` 属性。
`` 元素没有父元素。
`` 元素可包含以下子元素：
+ ``
+ ``
+ ``
+ ``
+ ``
以下是使用中的 `` 元素的示例：
```
```
#### dynamoDB
`` 元素表示一组 Amazon DynamoDB 设置。此元素可以包含 *conversionSchema* 属性，该属性表示在 .NET 和 DynamoDB 对象之间进行转换所用的版本。允许的值包括 V1 和 V2。此属性映射到 适用于 .NET 的 AWS SDK中的 `Amazon.DynamoDBv2.DynamoDBEntryConversion` 类。有关更多信息，请参阅 [DynamoDB 系列 - 转换架构](http://blogs.aws.amazon.com/net/post/Tx2TCOGWG7ARUH5/DynamoDB-Series-Conversion-Schemas)。
`` 元素的父级为 `` 元素。
`` 元素可以包含 `` 子元素。
以下是使用中的 `` 元素的示例：
```
```
#### 发电机 DBContext
`` 元素表示一组 Amazon DynamoDB 上下文特定的设置。此元素可以包含*tableNamePrefix*属性，该属性表示 DynamoDB 上下文在未手动配置的情况下将使用的默认表名前缀。此属性从 适用于 .NET 的 AWS SDK中的 `Amazon.AWSConfigs.DynamoDBConfig.Context.TableNamePrefix` 属性映射到 `Amazon.Util.DynamoDBContextConfig.TableNamePrefix` 属性。有关更多信息，请参阅 [DynamoDB 开发工具包的增强功能](http://blogs.aws.amazon.com/net/post/Tx2C4MHH2H0SA5W/Enhancements-to-the-DynamoDB-SDK)。
`` 元素的父级为 `` 元素。
`` 元素可包含以下子元素：
+ `` (一个或多个实例)
+ `