适用于 .NET 的 Amazon SDK V3 已进入维护模式。

我们建议您迁移到 [适用于 .NET 的 Amazon SDK V4](https://docs.amazonaws.cn/sdk-for-net/v4/developer-guide/welcome.html)。有关如何迁移的更多详细信息和信息，请参阅我们的[维护模式公告](https://www.amazonaws.cn/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 重试和超时
重试和超时

包含了有关使用 `CancellationToken` 进行异步方法调用时每种方法超时的信息。重试和超时

添加了有关重试模式的信息。

 适用于 .NET 的 Amazon SDK 允许您为向 Amazon 服务发出的 HTTP 请求配置重试次数和超时值。如果重试和超时的默认值不适用于您的应用程序，您可以针对具体要求调整这些值，但请务必了解这样做将对应用程序的行为带来什么影响。

在确定重试和超时值时，请考虑以下因素：
+ 当网络连接下降或 Amazon 服务无法访问时， 适用于 .NET 的 Amazon SDK 和您的应用程序应如何响应？ 您是希望调用快速失败，还是希望调用代表您不断重试？
+ 您的应用程序是必须能够及时响应的面向用户的应用程序或网站，还是更能容忍延迟增加的后台处理任务？
+ 应用程序是部署在具有低延迟的可靠网络上，还是部署在具有不可靠连接的远程位置？

## 重试


### 概述


 适用于 .NET 的 Amazon SDK 可以重试因服务器端限制或连接中断而失败的请求。服务配置类有两个属性可用于指定服务客户端的重试行为。服务配置类继承了抽象的 [Amazon.Runtime 中的这些属性。 ](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html)ClientConfig[适用于 .NET 的 Amazon SDK API 参考](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/)的类别：
+ `RetryMode`指定三种重试模式之一，这些模式[在 Amazon.Runtime 中定义。 RequestRetryMode](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TRequestRetryMode.html)枚举。

  可以使用`AWS_RETRY_MODE`环境变量或共享 Amazon 配置文件中的 *retry\$1mod* e 设置来控制应用程序的默认值。
+ `MaxErrorRetry` 指定服务客户端级别允许的重试次数；SDK 会在失败并引发异常之前按指定的次数重试该操作。

  可以使用`AWS_MAX_ATTEMPTS`环境变量或共享 Amazon 配置文件中的 *max\$1* tempts 设置来控制应用程序的默认值。

这些属性的详细描述可以在摘要的 [Amazon.Runtime 中找到。 ](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html)ClientConfig[适用于 .NET 的 Amazon SDK API 参考](https://docs.amazonaws.cn/sdkfornet/v3/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.amazonaws.cn/sdkfornet/v3/apidocs/items/DynamoDBv2/TDynamoDBConfig.html)或 [Amazon](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/SQS/TSQSConfig.html)。

一旦为服务客户端创建这些值，便不可更改。

**注意事项**

在进行重试时，会增加请求的延迟。您应根据应用程序对请求总延迟和错误率的限制来配置重试次数。

## 超时


 适用于 .NET 的 Amazon SDK 使您能够在服务客户端级别和每个方法调用配置请求超时。有两种配置超时的机制，后续章节将介绍这些机制：
+ 如果您使用的是[异步调用](#timeouts-async)，则可以使用该方法的 `CancellationToken` 参数。
+ 如果您[在.NET 框架中使用同步调用](#timeouts-sync-framework)，则可以使用抽象 [Amazon.Runtime 的`Timeout`和`ReadWriteTimeout`属性。 ClientConfig](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html)班级。

### 使用 `CancellationToken` 参数配置超时


 适用于 .NET 的 Amazon 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 的 Amazon SDK 使您能够在服务客户端级别配置请求超时和套接字 read/write 超时值。这些值是在抽象的 [Amazon.Runtime 的`Timeout`和`ReadWriteTimeout`属性中指定的。 ClientConfig](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html)班级。这些值作为 Amazon 服务客户端[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 的 Amazon SDK 

以下是默认超时值的例外情况。明确设置超时值时将覆盖这些值。
+ `Timeout`如果被调用的方法上传直播（例如 [Amazons3Client），则设置为最大值。`ReadWriteTimeout` PutObjectAsync()](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/S3/MS3PutObjectAsyncPutObjectRequestCancellationToken.html)，[Amazons3Client。 UploadPartAsync()](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/S3/MS3UploadPartAsyncUploadPartRequestCancellationToken.html)，[AmazonGlacierClient。 UploadArchiveAsync()](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Glacier/MGlacierUploadArchiveAsyncUploadArchiveRequestCancellationToken.html)，依此类推。
+  适用于 .NET 的 Amazon SDK 该目标.NET 框架的版本设置为所有 [Amazons3Clien](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/S3/TS3Client.html) t `Timeout` 和`ReadWriteTimeout`对象的最大值。[AmazonGlacierClient](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Glacier/TGlacierClient.html)
+ 针对便携式类库 (PCL) 和.NET Core 的版本设置`Timeout`为所有 [Amazons3](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/S3/TS3Client.html) Client 和对象的最大值。 适用于 .NET 的 Amazon SDK [AmazonGlacierClient](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/Glacier/TGlacierClient.html)

以下示例说明如何指定*标准*重试模式、最多 3 次重试、10 秒超时和 10 秒 read/write 超时（如果适用）。[Amazons3Client](https://docs.amazonaws.cn/sdkfornet/v3/apidocs/items/S3/TS3Client.html) 构造函数被赋予一个 [AmazonS3Config](https://docs.amazonaws.cn/sdkfornet/v3/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 的 Amazon SDK that target .NET Core.
    ReadWriteTimeout = TimeSpan.FromSeconds(10),
    RetryMode = RequestRetryMode.Standard,
    MaxErrorRetry = 3
  });
```