C# Class Amazon.S3.Transfer.TransferUtility

Provides a high level utility for managing transfers to and from Amazon S3.

TransferUtility provides a simple API for uploading content to and downloading content from Amazon S3. It makes extensive use of Amazon S3 multipart uploads to achieve enhanced throughput, performance, and reliability.

When uploading large files by specifying file paths instead of a stream, TransferUtility uses multiple threads to upload multiple parts of a single upload at once. When dealing with large content sizes and high bandwidth, this can increase throughput significantly.

Transfers are stored in memory. If the application is restarted, previous transfers are no longer accessible. In this situation, if necessary, you should clean up any multipart uploads that are incomplete.

Inheritance: ITransferUtility

Show file Open project: aws/aws-sdk-net Class Usage Examples

Public Methods

Method	Description
AbortMultipartUploadsAsync ( string bucketName, System.DateTime initiatedDate, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Aborts the multipart uploads that were initiated before the specified date.
DownloadAsync ( TransferUtilityDownloadRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Downloads the content from Amazon S3 and writes it to the specified file. If the key is not specified in the request parameter, the file name will used as the key name.
OpenStreamAsync ( Amazon.S3.Transfer.TransferUtilityOpenStreamRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Returns a stream to read the contents from Amazon S3 as specified by the `TransferUtilityOpenStreamRequest`. The caller of this method is responsible for closing the stream.
OpenStreamAsync ( string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Returns a stream from which the caller can read the content from the specified Amazon S3 bucket and key. The caller of this method is responsible for closing the stream.
TransferUtility ( ) : System	Constructs a new TransferUtility class. If a Timeout needs to be specified, use the constructor which takes an Amazon.S3.AmazonS3Client as a paramater. Use an instance of Amazon.S3.AmazonS3Client constructed with an Amazon.S3.AmazonS3Config object with the Timeout specified.
TransferUtility ( RegionEndpoint region ) : System	Constructs a new TransferUtility class. If a Timeout needs to be specified, use the constructor which takes an Amazon.S3.AmazonS3Client as a paramater. Use an instance of Amazon.S3.AmazonS3Client constructed with an Amazon.S3.AmazonS3Config object with the Timeout specified.
TransferUtility ( TransferUtilityConfig config ) : System	Constructs a new TransferUtility class.
UploadAsync ( Stream stream, string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Uploads the contents of the specified stream. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3. If you are uploading large files, TransferUtility will use multipart upload to fulfill the request. If a multipart upload is interrupted, TransferUtility will attempt to abort the multipart upload. Under certain circumstances (network outage, power failure, etc.), TransferUtility will not be able to abort the multipart upload. In this case, in order to stop getting charged for the storage of uploaded parts, you should manually invoke TransferUtility.AbortMultipartUploadsAsync() to abort the incomplete multipart uploads.
UploadAsync ( TransferUtilityUploadRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Uploads the file or stream specified by the request. To track the progress of the upload, add an event listener to the request's `UploadProgressEvent`. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3. If you are uploading large files, TransferUtility will use multipart upload to fulfill the request. If a multipart upload is interrupted, TransferUtility will attempt to abort the multipart upload. Under certain circumstances (network outage, power failure, etc.), TransferUtility will not be able to abort the multipart upload. In this case, in order to stop getting charged for the storage of uploaded parts, you should manually invoke TransferUtility.AbortMultipartUploadsAsync() to abort the incomplete multipart uploads.
UploadAsync ( string filePath, string bucketName, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Uploads the specified file. The object key is derived from the file's name. Multiple threads are used to read the file and perform multiple uploads in parallel. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3. If you are uploading large files, TransferUtility will use multipart upload to fulfill the request. If a multipart upload is interrupted, TransferUtility will attempt to abort the multipart upload. Under certain circumstances (network outage, power failure, etc.), TransferUtility will not be able to abort the multipart upload. In this case, in order to stop getting charged for the storage of uploaded parts, you should manually invoke TransferUtility.AbortMultipartUploadsAsync() to abort the incomplete multipart uploads.
UploadAsync ( string filePath, string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task	Uploads the specified file. Multiple threads are used to read the file and perform multiple uploads in parallel. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3. If you are uploading large files, TransferUtility will use multipart upload to fulfill the request. If a multipart upload is interrupted, TransferUtility will attempt to abort the multipart upload. Under certain circumstances (network outage, power failure, etc.), TransferUtility will not be able to abort the multipart upload. In this case, in order to stop getting charged for the storage of uploaded parts, you should manually invoke TransferUtility.AbortMultipartUploadsAsync() to abort the incomplete multipart uploads.

Private Methods

Method	Description
ConstructDownloadDirectoryRequest ( string bucketName, string s3Directory, string localDirectory ) : TransferUtilityDownloadDirectoryRequest
ConstructDownloadRequest ( string filePath, string bucketName, string key ) : TransferUtilityDownloadRequest
ConstructUploadDirectoryRequest ( string directory, string bucketName ) : TransferUtilityUploadDirectoryRequest
ConstructUploadDirectoryRequest ( string directory, string bucketName, string searchPattern, SearchOption searchOption ) : TransferUtilityUploadDirectoryRequest
GetUploadCommand ( TransferUtilityUploadRequest request, SemaphoreSlim asyncThrottler ) : BaseCommand
validate ( TransferUtilityUploadDirectoryRequest request ) : void

Method Details

AbortMultipartUploadsAsync() public method

Aborts the multipart uploads that were initiated before the specified date.

public AbortMultipartUploadsAsync ( string bucketName, System.DateTime initiatedDate, CancellationToken cancellationToken = default(CancellationToken) ) : Task
bucketName	string	/// The name of the bucket containing multipart uploads. ///
initiatedDate	System.DateTime	/// The date before which the multipart uploads were initiated. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

DownloadAsync() public method

Downloads the content from Amazon S3 and writes it to the specified file. If the key is not specified in the request parameter, the file name will used as the key name.

public DownloadAsync ( TransferUtilityDownloadRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task
request	TransferUtilityDownloadRequest	/// Contains all the parameters required to download an Amazon S3 object. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

OpenStreamAsync() public method

Returns a stream to read the contents from Amazon S3 as specified by the TransferUtilityOpenStreamRequest. The caller of this method is responsible for closing the stream.

public OpenStreamAsync ( Amazon.S3.Transfer.TransferUtilityOpenStreamRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task
request	Amazon.S3.Transfer.TransferUtilityOpenStreamRequest	/// Contains all the parameters required for the OpenStream operation. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

OpenStreamAsync() public method

Returns a stream from which the caller can read the content from the specified Amazon S3 bucket and key. The caller of this method is responsible for closing the stream.

public OpenStreamAsync ( string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task
bucketName	string	/// The name of the bucket. ///
key	string	/// The object key. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

TransferUtility() public method

Constructs a new TransferUtility class.

If a Timeout needs to be specified, use the constructor which takes an Amazon.S3.AmazonS3Client as a paramater. Use an instance of Amazon.S3.AmazonS3Client constructed with an Amazon.S3.AmazonS3Config object with the Timeout specified.

public TransferUtility ( ) : System
return	System

TransferUtility() public method

Constructs a new TransferUtility class.

public TransferUtility ( RegionEndpoint region ) : System
region	RegionEndpoint	/// The region to configure the transfer utility for. ///
return	System

TransferUtility() public method

Constructs a new TransferUtility class.

public TransferUtility ( TransferUtilityConfig config ) : System
config	TransferUtilityConfig	/// Specifies advanced configuration settings for . ///
return	System

UploadAsync() public method

Uploads the contents of the specified stream. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3.

If you are uploading large files, TransferUtility will use multipart upload to fulfill the request. If a multipart upload is interrupted, TransferUtility will attempt to abort the multipart upload. Under certain circumstances (network outage, power failure, etc.), TransferUtility will not be able to abort the multipart upload. In this case, in order to stop getting charged for the storage of uploaded parts, you should manually invoke TransferUtility.AbortMultipartUploadsAsync() to abort the incomplete multipart uploads.

public UploadAsync ( Stream stream, string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task
stream	Stream	/// The stream to read to obtain the content to upload. ///
bucketName	string	/// The target Amazon S3 bucket, that is, the name of the bucket to upload the stream to. ///
key	string	/// The key under which the Amazon S3 object is stored. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

UploadAsync() public method

Uploads the file or stream specified by the request. To track the progress of the upload, add an event listener to the request's UploadProgressEvent. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3.

public UploadAsync ( TransferUtilityUploadRequest request, CancellationToken cancellationToken = default(CancellationToken) ) : Task
request	TransferUtilityUploadRequest	/// Contains all the parameters required to upload to Amazon S3. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

UploadAsync() public method

Uploads the specified file. The object key is derived from the file's name. Multiple threads are used to read the file and perform multiple uploads in parallel. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3.

public UploadAsync ( string filePath, string bucketName, CancellationToken cancellationToken = default(CancellationToken) ) : Task
filePath	string	/// The file path of the file to upload. ///
bucketName	string	/// The target Amazon S3 bucket, that is, the name of the bucket to upload the file to. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task

UploadAsync() public method

Uploads the specified file. Multiple threads are used to read the file and perform multiple uploads in parallel. For large uploads, the file will be divided and uploaded in parts using Amazon S3's multipart API. The parts will be reassembled as one object in Amazon S3.

public UploadAsync ( string filePath, string bucketName, string key, CancellationToken cancellationToken = default(CancellationToken) ) : Task
filePath	string	/// The file path of the file to upload. ///
bucketName	string	/// The target Amazon S3 bucket, that is, the name of the bucket to upload the file to. ///
key	string	/// The key under which the Amazon S3 object is stored. ///
cancellationToken	System.Threading.CancellationToken	/// A cancellation token that can be used by other objects or threads to receive notice of cancellation. ///
return	Task