static void Main(string[] args) {
...
Task<ListBucketsResponse> response = ListBucketsAsync();
Console.WriteLine($"Number of buckets: {response.Result.Buckets.Count}");
...
}
// Async method to get a list of Amazon S3 buckets.
private static async Task<ListBucketsResponse> ListBucketsAsync() { ...
var response = await s3Client.ListBucketsAsync();
return response;
}
Notice the special Task<> syntax that's needed in Main when you use this pattern. In addition, you must use the Result member of the response to get the data.
You can see full examples of asynchronous calls to AWS service clients in the Quick tour (p. 4) section (Simple cross-platform app (p. 4) and Simple Windows-based app (p. 8)) and in Code examples with guidance (p. 63).
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 class of the AWS SDK for .NET API Reference:
• RetryMode specifies one of three retry modes, which are defined in the Amazon.Runtime.RequestRetryMode enumeration.
The default value for your application can be controlled by using the AWS_RETRY_MODE environment variable or the retry_mode setting in the shared AWS config file.
Timeouts
• 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_attempts setting in the shared AWS config file.
Detailed descriptions for these properties can be found in the abstract Amazon.Runtime.ClientConfig class of the AWS SDK for .NET API Reference. Each value of RetryMode corresponds by default to a particular value of MaxErrorRetry, as shown in the following table.
RetryMode Corresponding MaxErrorRetry
(Amazon DynamoDB) Corresponding MaxErrorRetry (all others)
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 or AmazonSQSConfig 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 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 class. These values are passed on as the
Example
Timeout and ReadWriteTimeout properties of the 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 class instead of the HttpWebRequest class, and supports the 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(), AmazonS3Client.UploadPartAsync(), AmazonGlacierClient.UploadArchiveAsync(), 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 and AmazonGlacierClient 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 and AmazonGlacierClient objects.
Example
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 constructor is given an AmazonS3Config 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
});
Paginators
Some AWS services collect and store a large amount of data, which you can retrieve by using the API calls of the AWS SDK for .NET. If the amount of data you want to retrieve becomes too large for a single API call, you can break the results into more manageable pieces through the use of pagination.
To enable you to perform pagination, the request and response objects for many service clients in the SDK provide a continuation token (typically named NextToken). Some of these service clients also provide paginators.
Paginators enable you to avoid the overhead of the continuation token, which might involve loops, state variables, multiple API calls, and so on. When you use a paginator, you can retrieve data from an AWS service through a single line of code, a foreach loop's declaration. If multiple API calls are needed to retrieve the data, the paginator handles this for you.