適用於 .NET 的 AWS SDK V3 已進入維護模式。 我們建議您遷移至 [適用於 .NET 的 AWS SDK V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html)。如需如何遷移的其他詳細資訊和資訊，請參閱我們的[維護模式公告](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 重試和逾時 適用於 .NET 的 AWS SDK 可讓您設定對 AWS 服務的 HTTP 請求的重試次數和逾時值。如果重試和逾時的預設不適用於您的應用程式，您可以將它們兩者適時調整以配合您的需求，但請務必了解如此一來對應用程式產生的影響程度。 若要判斷哪些值用於重試和逾時，請考慮以下資訊： + 當網路連線降級或 AWS 服務無法連線時， 適用於 .NET 的 AWS SDK 和您的應用程式應如何回應？ 您是否希望快速呼叫失敗，還是應該呼叫保持重試？ + 您的應用程式是使用者接觸應用程式，或是必須要有所回應的網站，或者是對延長的延遲時間具有更高容忍力的背景執行工作？ + 應用程式是部署在低延遲的可靠網路上，還是部署在連線不可靠的遠端位置？ ## 重試 ### 概觀 適用於 .NET 的 AWS SDK 可以重試因伺服器端限流或連線中斷而失敗的請求。服務組態類別有兩個屬性，可用來指定服務用戶端的重試行為。服務組態類別會從 [適用於 .NET 的 AWS SDK API 參考](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/)的抽象 [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html) 類別繼承這些屬性： + `RetryMode` 指定三種重試模式之一，這些模式在 [Amazon.Runtime.RequestRetryMode](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TRequestRetryMode.html) 列舉中定義。 您可以使用`AWS_RETRY_MODE`環境變數或共用組態檔案中的 *retry\$1mode* AWS 設定來控制應用程式的預設值。 + `MaxErrorRetry` 指定服務用戶端層級允許的重試次數；軟體開發套件會在失敗和擲回例外狀況之前，以指定的次數重試操作。 您可以使用`AWS_MAX_ATTEMPTS`環境變數或共用組態檔案中的 *max\$1attempts* AWS 設定來控制應用程式的預設值。 您可以在 [適用於 .NET 的 AWS SDK API 參考](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/)的摘要 [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html) 類別中找到這些屬性的詳細說明。根據預設， 的每個值都會`RetryMode`對應至 的特定值`MaxErrorRetry`，如下表所示。 | | | | | --- |--- |--- | | Legacy | 10 | 4 | | Standard | 10 | 2 | | Adaptive (experimental) | 10 | 2 | ### Behavior (行為) **您的應用程式啟動時** 當您的應用程式啟動時，軟體開發套件`MaxErrorRetry`會設定 `RetryMode`和 的預設值。除非您指定其他值，否則建立服務用戶端時會使用這些預設值。 + 如果您的環境中未設定屬性，則 的預設值`RetryMode`會設定為 *Legacy*，而 的預設值`MaxErrorRetry`會設定為上表中的對應值。 + 如果您的環境中已設定重試模式，則該值會用作 的預設值`RetryMode`。除非已在您的環境中設定最大錯誤的值 （接下來說明），否則 的預設值`MaxErrorRetry`會使用上表中的對應值進行設定。 + 如果您的環境中已設定最大錯誤的值，則該值會用作 的預設值`MaxErrorRetry`。Amazon DynamoDB 是此規則的例外狀況； 的預設 DynamoDB 值一律`MaxErrorRetry`是上表中的值。 **當您的應用程式執行時** 建立服務用戶端時，您可以使用 `RetryMode`和 的預設值`MaxErrorRetry`，如先前所述，也可以指定其他值。若要指定其他值，請在建立服務用戶端時建立並包含服務組態物件，例如 [AmazonDynamoDBConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TDynamoDBConfig.html) 或 [AmazonSQSConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSConfig.html)。 建立服務用戶端之後，就無法變更這些值。 **考量** 重試時，請求的延遲會增加。您應該設定您的重試，依據您的應用程式限制總請求延遲和錯誤率而設定。 ## 逾時 適用於 .NET 的 AWS SDK 可讓您在服務用戶端層級和每個方法呼叫設定請求逾時。設定逾時有兩種機制，涵蓋於後續章節： + 如果您使用的是[非同步呼叫](#timeouts-async)，則可以使用 方法的 `CancellationToken` 參數。 + 如果您在 [.NET Framework 中使用同步呼叫](#timeouts-sync-framework)，則可以使用抽象 [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html) 類別的 `Timeout`和 `ReadWriteTimeout` 屬性。 ### 針對逾時使用 `CancellationToken` 參數 適用於 .NET 的 AWS SDK 可讓您使用 `CancellationToken` 參數設定非同步呼叫的請求逾時。下列程式碼片段顯示範例。`System.Threading.Tasks.TaskCanceledException` 如果未在 10 秒內完成請求，程式碼會擲回。 ``` 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 可讓您在服務用戶端層級設定請求逾時和通訊端讀取/寫入逾時值。這些值是在抽象 [Amazon.Runtime.ClientConfig](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TClientConfig.html) 類別的 `Timeout`和 `ReadWriteTimeout` 屬性中指定。這些值會做為 AWS 服務用戶端物件所建立 [HttpWebRequest](https://learn.microsoft.com/en-us/dotnet/api/system.net.httpwebrequest) 物件的 `Timeout`和 `ReadWriteTimeout` 屬性傳遞。在預設情況下，`Timeout` 值為 100 秒，`ReadWriteTimeout` 值為 300 秒。 當您的網路有高延遲或存在會造成操作重試的條件，使用長逾時值和次數高的重試，會導致某些開發套件的操作看起來沒有回應。 **注意** 以可攜式類別程式庫 (PCL) 適用於 .NET 的 AWS SDK 為目標的 版本使用 [HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient) 類別而非 `HttpWebRequest`類別，並且僅支援[逾時](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout)屬性。 以下為例外狀況的預設逾時值。這些值時在您明確設定逾時值時會被覆寫。 + `Timeout` 如果呼叫的方法上傳串流，例如 [AmazonS3Client.PutObjectAsync()](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MS3PutObjectAsyncPutObjectRequestCancellationToken.html)、[AmazonS3Client.UploadPartAsync()](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MS3UploadPartAsyncUploadPartRequestCancellationToken.html)、[AmazonGlacierClient.UploadArchiveAsync()](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Glacier/MGlacierUploadArchiveAsyncUploadArchiveRequestCancellationToken.html) 等，則 和 `ReadWriteTimeout`會設定為最大值。 + 適用於 .NET 的 AWS SDK 目標為 .NET Framework 設定的 版本`ReadWriteTimeout`，`Timeout`以及所有 [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TS3Client.html) 和 [AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Glacier/TGlacierClient.html) 物件的最大值。 + 適用於 .NET 的 AWS SDK 將可攜式類別程式庫 (PCL) 和 .NET Core 設為所有 [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TS3Client.html) 和 [AmazonGlacierClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Glacier/TGlacierClient.html) 物件`Timeout`最大值的 版本。 下列範例說明如何指定*標準*重試模式、最多 3 次重試、逾時 10 秒，以及讀取/寫入逾時 10 秒 （如適用）。[AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TS3Client.html) 建構函數會獲得 [AmazonS3Config](https://docs.aws.amazon.com/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 的 AWS SDK that target .NET Core. ReadWriteTimeout = TimeSpan.FromSeconds(10), RetryMode = RequestRetryMode.Standard, MaxErrorRetry = 3 }); ```