AWS SDK Version 4 for .NET
API Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Downloads the content from Amazon S3 and writes it to the specified file, returning response metadata.

Note:

This is an asynchronous operation using the standard naming convention for .NET 4.7.2 or higher.

Namespace: Amazon.S3.Transfer
Assembly: AWSSDK.S3.dll
Version: 3.x.y.z

Syntax

C# 
public virtual Task<TransferUtilityDownloadResponse> DownloadWithResponseAsync(
         String filePath,
         String bucketName,
         String key,
         CancellationToken cancellationToken
)

Parameters

filePath
Type: System.String

The file path where the downloaded content will be written.

bucketName
Type: System.String

The name of the bucket containing the Amazon S3 object to download.

key
Type: System.String

The key under which the Amazon S3 object is stored.

cancellationToken
Type: System.Threading.CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Return Value


Type: Task<TransferUtilityDownloadResponse>
The task object representing the asynchronous operation with download response metadata.

Remarks

This method uses parallel downloads to significantly improve throughput compared to the standard Amazon.S3.Transfer.ITransferUtility.DownloadAsync(Amazon.S3.Transfer.TransferUtilityDownloadRequest,System.Threading.CancellationToken) method.

How it works:

For large objects, the download is automatically split into parts (default 8MB per part)Multiple parts are downloaded concurrently using parallel requests to S3Downloaded parts are written directly to the file as they arrive

Multipart Download Strategy:

The Amazon.S3.Transfer.BaseDownloadRequest.MultipartDownloadType property controls how parts are downloaded (default: MultipartDownloadType.PART):

PART (default): Uses the original part boundaries from when the object was uploaded with multipart upload. This is more efficient as it aligns with S3's internal part structure, but requires that the object was uploaded using multipart upload. The Amazon.S3.Transfer.BaseDownloadRequest.PartSize property is ignored in this mode.RANGE: Uses range-based downloads with configurable part sizes via the Amazon.S3.Transfer.BaseDownloadRequest.PartSize property. This works with any object (whether uploaded as single-part or multipart) and provides more flexibility in controlling download part sizes.

When to use PART vs RANGE:

Use PART mode (default) when you know the object was uploaded using multipart upload and want optimal performance.Use RANGE mode when the object's upload method is unknown, when you need specific part sizes, or when downloading objects that were uploaded as a single part.

Configuration Options:

You can customize the download behavior using Amazon.S3.Transfer.TransferUtilityConfig: 

var config = new TransferUtilityConfig
{
    // Control how many parts download in parallel (default: 10)
    ConcurrentServiceRequests = 20
};
var transferUtility = new TransferUtility(s3Client, config);

Use Amazon.S3.Transfer.TransferUtilityConfig.ConcurrentServiceRequests to control parallel download threads.

Additional Performance Settings:

You can also tune the S3 client's Amazon.Runtime.ClientConfig.BufferSize property to control the buffer size used when reading from S3 response streams and writing to the local file. The default buffer size is 8KB. Increasing this value may improve throughput for large downloads at the cost of increased memory usage. 

var s3Config = new AmazonS3Config
{
    BufferSize = 64 * 1024  // Use 64KB buffer instead of default 8KB
};
var s3Client = new AmazonS3Client(s3Config);
var transferUtility = new TransferUtility(s3Client);

Version Information

.NET:
Supported in: 8.0 and newer, Core 3.1

.NET Standard:
Supported in: 2.0

.NET Framework:
Supported in: 4.7.2 and newer