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:

For .NET Core this operation is only available in asynchronous form. Please refer to DownloadWithResponseAsync.

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

Syntax

C# 
public virtual TransferUtilityDownloadResponse DownloadWithResponse(
         String filePath,
         String bucketName,
         String key
)

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.

Return Value


Type: TransferUtilityDownloadResponse
Response metadata including headers and version information from the download.

Remarks

This method uses parallel downloads to significantly improve throughput compared to the standard Amazon.S3.Transfer.ITransferUtility.Download(System.String,System.String,System.String) 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