Performance best practices for the Amazon SDK for .NET

How you create clients, handle responses, and configure your application has a large effect on throughput, latency, and memory use. This topic describes usage and configuration patterns that help your applications run efficiently and reliably. These patterns matter most under high load or in resource-constrained environments such as containers and serverless functions. Following these practices can improve performance and prevent common problems such as slow responses, hangs, and high memory use.

The most impactful practices are the following:

Before you begin, be sure you have set up your environment and configured your project.

Reuse a single, long-lived service client

Service clients such as AmazonS3Client and AmazonDynamoDBClient are thread-safe, relatively expensive to construct, and long-lived. Constructing a client resolves Region and endpoint information and establishes the underlying HTTP infrastructure. Create one client per service and reuse it for the lifetime of your application. If you call more than one Region, create a separate client for each Region.

In applications that use dependency injection, register the client as a singleton. The AddAWSService extension method from the AWSSDK.Extensions.NETCore.Setup NuGet package registers the client with a default lifetime of ServiceLifetime.Singleton. The client is created the first time it's requested, and the same instance is reused for the lifetime of the process. For more information about registering Amazon services with dependency injection and reading options from configuration, see AWSSDK.Extensions.NETCore.Setup and IConfiguration.

You can also register a client as a singleton manually.

builder.Services.AddSingleton<IAmazonS3>(_ => new AmazonS3Client());

Reusing the client does not mean you should stop disposing per-operation responses. Reuse the client for the life of the application, but continue to dispose the responses and streams that individual operations return, as described in Dispose responses and streams.

Dispose responses and streams to release connections

Some SDK response objects carry a live network stream. The most common example is GetObjectResponse, which implements IDisposable and exposes the object's content through its ResponseStream property. The response holds an open HTTP connection until the stream is fully read or the response is disposed. If you leak these responses (for example, by calling GetObject in a loop without disposing each result), open connections accumulate until the connection pool is exhausted, and the next call blocks. This is the cause behind reports of downloads that "hang randomly" or stall on the Nth object.

Always wrap a streaming response in a using statement and read or copy its stream promptly.

using Amazon.S3;
using Amazon.S3.Model;

// s3Client is a reused, long-lived client.
var request = new GetObjectRequest { BucketName = bucketName, Key = key };

using var response = await s3Client.GetObjectAsync(request);
await response.WriteResponseStreamToFileAsync(filePath, append: false, CancellationToken.None);

Disposing the response and disposing its ResponseStream are equivalent; either one closes the underlying network stream and returns the connection to the pool.

var metadata = await s3Client.GetObjectMetadataAsync(bucketName, key);
Console.WriteLine($"Size: {metadata.ContentLength} bytes");

Use async/await correctly

On modern .NET, the service operations in the Amazon SDK for .NET are asynchronous and return a Task. On .NET Framework, synchronous methods also exist, but asynchronous calls scale better and are recommended. Consume operations with await, and propagate async through every layer of your code up to the entry point. For more information about asynchronous programming with the SDK, see Asynchronous programming.

The following method blocks on the asynchronous call and can deadlock or starve the thread pool.

// Anti-pattern: do not do this.
public GetObjectResponse Get(GetObjectRequest request)
{
    return s3Client.GetObjectAsync(request).Result;
}

Instead, make the method async and await the call.

public async Task<GetObjectResponse> GetAsync(GetObjectRequest request)
{
    return await s3Client.GetObjectAsync(request);
}

Additional recommendations for asynchronous code:

Configure .NET garbage collection for Amazon Lambda and Amazon ECS

When a container appears to have a "memory leak," the .NET garbage collector (GC) might be retaining reclaimed memory for reuse. As a result, process memory can appear high and stable even when the managed heap is not growing. In addition, the GC doesn't automatically detect a container's memory limit (its cgroup limit). In a constrained environment, the heap might then grow toward the host's memory rather than the container's limit. This can lead to OutOfMemoryException or the container being terminated.

To help the GC work well in constrained environments:

For more information about these settings, see Runtime configuration options for garbage collection on learn.microsoft.com. For guidance specific to Amazon compute, see the Amazon Developer Tools Blog post Configuring .NET Garbage Collection for Amazon ECS and Amazon Lambda.

Manage HTTP connections and connection limits

Under high throughput, two connection-related problems are common. The first is opening too many short-lived connections. This exhausts ephemeral ports, leaves sockets in TIME_WAIT, and adds TCP and TLS handshake latency. The second is having too few connections available, which bottlenecks parallelism. Reusing a single, long-lived client (see Reuse service clients) is the foundation for healthy connection pooling, because pooling depends on the client being reused.

To tune the number of concurrent connections per endpoint, set the MaxConnectionsPerServer property on the client configuration. When this property is null (the default), the underlying HttpClientHandler default applies, which is effectively unlimited on modern .NET. Raise it only when many concurrent requests to the same endpoint are bottlenecked on connections. A good starting point is the peak number of concurrent requests you expect per endpoint. Setting it far higher than your workload needs wastes sockets without improving throughput.

using Amazon.S3;

var config = new AmazonS3Config
{
    MaxConnectionsPerServer = 50
};

var s3Client = new AmazonS3Client(config);

If you already use dependency injection, configure your clients through AWSSDK.Extensions.NETCore.Setup. This is the recommended approach when you use DI or register several service clients. It centralizes configuration and makes clients easy to inject and test. You can set configuration values from your application's configuration instead of in code. For more information, see AWSSDK.Extensions.NETCore.Setup and IConfiguration.

Finally, bound your own parallelism so that you don't start more concurrent operations than your connection limit allows. For example, gate calls with a SemaphoreSlim sized to your connection limit:

var throttle = new SemaphoreSlim(50); // match MaxConnectionsPerServer
await throttle.WaitAsync(token);
try
{
    await s3Client.GetObjectAsync(request, token);
}
finally
{
    throttle.Release();
}

Configure timeouts and retries

Timeouts and retries have a direct effect on perceived performance. A Timeout value that is too high lets a stalled request block for a long time. When a service is already returning throttling errors, an aggressive retry policy adds more requests and can make the throttling worse. Choose a retry policy that fits your application's tolerance for latency versus failure, and let genuine exceptions propagate rather than retrying in a way that masks a hang.

For more information about the retry modes, MaxErrorRetry, and the Timeout property (ReadWriteTimeout applies only to .NET Framework), along with examples of how to set them, see Retries and timeouts.

Optimize streaming and large-object transfers (Amazon S3)

To upload and download large objects, or many objects, use the TransferUtility class in the Amazon.S3.Transfer namespace. It uploads and downloads in parallel using multipart transfers, and manages streams, parts, and connections for you. This is faster than a single-stream transfer and is the recommended way to move large objects.

Diagnose performance problems

When you investigate a slowdown, hang, or apparent leak, the following signals help you find the cause quickly: