Class R2Client

Namespace

Cloudflare.NET.R2

Assembly

Cloudflare.NET.R2.dll

Implements the client that interacts with Cloudflare R2's S3-compatible API.

public class R2Client : IR2Client, IDisposable

Inheritance

object

R2Client

Implements

IR2Client

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

R2Client(ILoggerFactory, IAmazonS3)

Initializes a new instance of the R2Client class. This is the designated constructor for dependency injection.

public R2Client(ILoggerFactory loggerFactory, IAmazonS3 s3Client)

Parameters

loggerFactory ILoggerFactory

The logger factory used to create a typed logger.

s3Client IAmazonS3

The underlying S3-compatible client.

Methods

AbortMultipartUploadAsync(string, string, string, CancellationToken)

Aborts a multipart upload, deleting any parts that have already been uploaded. This is a free operation.

public Task<R2Result> AbortMultipartUploadAsync(string bucketName, string objectKey, string uploadId, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object.

uploadId string

The ID of the multipart upload to abort.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the abort operation (should be zero).

Exceptions

CloudflareR2OperationException

Thrown if the operation fails.

ClearBucketAsync(string, bool, bool, CancellationToken)

Clears all objects from an R2 bucket by repeatedly listing and deleting them in batches.

public Task<R2Result> ClearBucketAsync(string bucketName, bool continueOnError = true, bool abortIncompleteMultipartUploads = true, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to clear.

continueOnError bool

If true, the operation will continue even if some delete batches fail.

abortIncompleteMultipartUploads bool

When true (the default), the method finds every multipart upload left open in the bucket and aborts each one after the objects are deleted, at the cost of one extra billable Class A operation for the discovery call. Aborting an upload is itself free. Set this to false to delete only objects.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the total metrics of all list, delete, and abort operations.

Remarks

Deleting every object does not by itself leave the bucket deletable. A multipart upload that was started and never completed or aborted keeps holding storage that object listing never reports, and Cloudflare then refuses to delete the bucket, reporting that it is not empty even though no object is visible. abortIncompleteMultipartUploads controls whether this method also finds those uploads and aborts them.

Exceptions

CloudflareR2BatchException<T>

Thrown if some objects could not be deleted.

CloudflareR2ListException<T>

Thrown if listing objects or open multipart uploads fails.

CompleteMultipartUploadAsync(string, string, string, IEnumerable<PartETag>, CancellationToken)

Completes a multipart upload after all parts are uploaded.

public Task<R2Result> CompleteMultipartUploadAsync(string bucketName, string objectKey, string uploadId, IEnumerable<PartETag> parts, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object.

uploadId string

The ID of the multipart upload.

parts IEnumerable<PartETag>

A list of the part numbers and their corresponding ETags.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the finalization operation.

Exceptions

CloudflareR2OperationException

Thrown if the operation fails.

CreatePresignedGetUrl(string, PresignedGetRequest)

Creates a presigned GET URL that allows for downloading an object directly from R2, optionally enforcing response header overrides via the signed query string.

public string CreatePresignedGetUrl(string bucketName, PresignedGetRequest request)

Parameters

bucketName string

The name of the bucket holding the object.

request PresignedGetRequest

A request object defining the key, validity window, and response header overrides.

Returns

string

A string containing the generated presigned URL.

Exceptions

CloudflareR2OperationException

Thrown if URL generation fails.

CreatePresignedPutUrl(string, PresignedPutRequest)

Creates a presigned PUT URL that allows for uploading a file directly to R2, enforcing constraints via signed headers.

public string CreatePresignedPutUrl(string bucketName, PresignedPutRequest request)

Parameters

bucketName string

The name of the bucket where the upload will occur.

request PresignedPutRequest

A request object defining the key and headers to enforce.

Returns

string

A string containing the generated presigned URL.

Exceptions

CloudflareR2OperationException

Thrown if URL generation fails.

CreatePresignedUploadPartUrl(string, PresignedUploadPartRequest)

Creates a presigned URL for uploading a single part of a multipart upload.

public string CreatePresignedUploadPartUrl(string bucketName, PresignedUploadPartRequest request)

Parameters

bucketName string

The name of the target bucket.

request PresignedUploadPartRequest

The parameters for the presigned part URL.

Returns

string

A string containing the generated presigned URL for the part.

Exceptions

CloudflareR2OperationException

Thrown if URL generation fails.

CreatePresignedUploadPartsUrls(string, PresignedUploadPartsRequest)

Creates a batch of presigned URLs for uploading multiple parts of a multipart upload.

public IReadOnlyDictionary<int, string> CreatePresignedUploadPartsUrls(string bucketName, PresignedUploadPartsRequest request)

Parameters

bucketName string

The name of the target bucket.

request PresignedUploadPartsRequest

The parameters for the presigned part URLs.

Returns

IReadOnlyDictionary<int, string>

A dictionary mapping each part number to its generated presigned URL.

Exceptions

CloudflareR2OperationException

Thrown if URL generation fails for any part.

DeleteObjectAsync(string, string, CancellationToken)

Deletes a single object from an R2 bucket. This is a free operation.

public Task<R2Result> DeleteObjectAsync(string bucketName, string objectKey, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object to delete.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the delete operation (should be zero).

Exceptions

CloudflareR2OperationException

Thrown if the delete fails.

DeleteObjectsAsync(string, IEnumerable<string>, bool, CancellationToken)

Deletes multiple objects from an R2 bucket in batches. This is a free operation.

public Task<R2Result> DeleteObjectsAsync(string bucketName, IEnumerable<string> objectKeys, bool continueOnError = true, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKeys IEnumerable<string>

An enumeration of object keys to delete.

continueOnError bool

If true, the operation will continue even if some batches fail, throwing an exception only at the end. If false, it will stop on the first error.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the total metrics of all attempted operations (should be zero).

Exceptions

CloudflareR2BatchException<T>

Thrown if one or more objects could not be deleted. Contains a list of the failed keys.

Dispose()

Disposes the underlying S3 client.

public void Dispose()

DownloadFileAsync(string, string, Stream, CancellationToken)

Downloads a file from an R2 bucket to a stream.

public Task<R2Result> DownloadFileAsync(string bucketName, string objectKey, Stream outputStream, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object to download.

outputStream Stream

The stream to write the downloaded data to.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics, including egress bytes.

Exceptions

CloudflareR2OperationException

Thrown if the download fails.

DownloadFileAsync(string, string, string, CancellationToken)

Downloads a file from an R2 bucket to a local file path.

public Task<R2Result> DownloadFileAsync(string bucketName, string objectKey, string downloadPath, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object to download.

downloadPath string

The local path to save the downloaded file to.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics, including egress bytes.

Exceptions

CloudflareR2OperationException

Thrown if the download fails.

GeneratePresignedUrl(GetPreSignedUrlRequest)

Generates a presigned URL using the underlying S3 client.

protected virtual string GeneratePresignedUrl(GetPreSignedUrlRequest request)

Parameters

request GetPreSignedUrlRequest

The request for the presigned URL.

Returns

string

The generated presigned URL.

Remarks

This method is virtual to allow for mocking in unit tests.

InitiateMultipartUploadAsync(string, string, string?, string?, CancellationToken)

Initiates a new multipart upload and records the content type the assembled object will carry.

public Task<R2Result<string>> InitiateMultipartUploadAsync(string bucketName, string objectKey, string? contentType, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key for the object in the bucket.

contentType string

The MIME type to record for the assembled object, for example application/pdf.

cacheControl string

An optional Cache-Control value to store on the assembled object; R2 serves it on every GET, which drives edge and browser caching. Like the content type, it can only be supplied here: the individual parts cannot carry it, so a flow uploading parts through presigned URLs must state it when the upload starts. null or a blank string leaves the header unset.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<string>>

A result object containing the UploadId and operation metrics.

Remarks

S3 reads the finished object's Content-Type from this request and never from the individual parts. A caller that hands out presigned part URLs therefore has no later opportunity to set it: the content type must be supplied here, when the upload starts.

Passing null or a blank string leaves the property unset, so R2 applies its own default and this method behaves exactly like InitiateMultipartUploadAsync(string, string, CancellationToken).

Exceptions

CloudflareR2OperationException

Thrown if the operation fails.

InitiateMultipartUploadAsync(string, string, CancellationToken)

Initiates a new multipart upload, letting R2 choose the assembled object's content type.

public Task<R2Result<string>> InitiateMultipartUploadAsync(string bucketName, string objectKey, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key for the object in the bucket.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<string>>

A result object containing the UploadId and operation metrics.

Exceptions

CloudflareR2OperationException

Thrown if the operation fails.

ListMultipartUploadsAsync(string, string?, CancellationToken)

Lists every multipart upload initiated under a prefix that has neither completed nor been aborted, handling pagination internally.

public Task<R2Result<IReadOnlyList<MultipartUpload>>> ListMultipartUploadsAsync(string bucketName, string? prefix, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

prefix string

The key prefix to restrict discovery to, or null for the whole bucket.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<IReadOnlyList<MultipartUpload>>>

A result object containing every open multipart upload under the prefix and the aggregated metrics.

Remarks

An open multipart upload's parts are invisible to ListObjectsAsync(string, string?, CancellationToken) until the upload completes, so draining the objects under a prefix can never end one. A teardown that must leave the prefix genuinely empty discovers the open uploads here and aborts each one.

Pass the UploadId from each returned MultipartUpload to AbortMultipartUploadAsync(string, string, string, CancellationToken). R2 has been observed to report an upload identifier here that differs from the one it returned when the upload was started, so the value from this listing is the one to use for the abort.

ClearBucketAsync(string, bool, bool, CancellationToken) performs this discovery and abort itself unless the caller opts out.

Exceptions

CloudflareR2ListException<T>

Thrown if listing fails mid-stream, containing any uploads fetched successfully.

ListObjectsAsync(string, string?, CancellationToken)

Lists all objects in an R2 bucket, optionally filtered by a prefix, handling pagination automatically.

public Task<R2Result<IReadOnlyList<S3Object>>> ListObjectsAsync(string bucketName, string? prefix, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

prefix string

The prefix to filter the object listing by.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<IReadOnlyList<S3Object>>>

A result object containing a read-only list of all S3Object items found and aggregated metrics.

Exceptions

CloudflareR2ListException<T>

Thrown if listing fails mid-stream, containing any objects fetched successfully.

ListObjectsPageAsync(string, string?, int, string?, CancellationToken)

Lists ONE page of objects under a prefix and returns the token that fetches the next page, leaving the walk across pages to the caller.

public Task<R2Result<R2ObjectPage>> ListObjectsPageAsync(string bucketName, string? prefix, int maxKeys, string? continuationToken, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

prefix string

The prefix to filter the object listing by.

maxKeys int

The maximum number of keys to return in this page (clamped to 1000).

continuationToken string

The token returned by the previous page, or null to start from the beginning of the prefix.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<R2ObjectPage>>

A result object containing one R2ObjectPage and the metrics of the single list call.

Remarks

ListObjectsAsync(string, string?, CancellationToken) pages internally and returns the whole prefix. A caller that must bound how many pages it reads in one run, and resume the walk on a later run, needs the page and the token instead.

maxKeys is clamped to the S3 page ceiling of 1000; a value at or below zero requests 1000.

Exceptions

CloudflareR2ListException<T>

Thrown if listing fails.

ListPartsAsync(string, string, string, CancellationToken)

Lists the parts that have been uploaded for a specific multipart upload, transparently handling pagination.

public Task<R2Result<IReadOnlyList<ListedPart>>> ListPartsAsync(string bucketName, string objectKey, string uploadId, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key of the object.

uploadId string

The ID of the multipart upload.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result<IReadOnlyList<ListedPart>>>

A result object containing the full list of parts and the aggregated metrics.

Exceptions

CloudflareR2ListException<T>

Thrown if listing fails mid-stream, containing any parts fetched successfully.

UploadAsync(string, string, Stream, long?, string?, UploadChecksum?, string?, CancellationToken)

Uploads a file from a stream, automatically choosing between a single PUT request or a multipart upload, and records the object's content type. If the stream is seekable, the choice is based on its length. If it is not seekable, it will always attempt a multipart upload.

public Task<R2Result> UploadAsync(string bucketName, string objectKey, Stream fileStream, long? partSize, string? contentType, UploadChecksum? checksum = null, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

fileStream Stream

The stream to upload.

partSize long?

The desired size in bytes for each part in a multipart upload. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

contentType string

The MIME type to record for the object, for example image/webp.

checksum UploadChecksum

An optional digest of the whole object's bytes for R2 to verify on a single-part upload.

cacheControl string

An optional Cache-Control value to store on the object; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset. On the multipart path the value is recorded on the initiate request, alongside the content type.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Remarks

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadAsync(string, string, Stream, long?, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the stream contents or the object key. When the stream goes multipart, the type is recorded on the initiate request, the only place S3 reads the assembled object's Content-Type from.

A checksum binds the upload to a digest of the whole object: R2 hashes the arriving bytes and fails the upload with BadDigest, storing nothing, when they do not hash to the stated digest. Because the digest covers the whole object while a multipart upload is verified per part, a checksum is only accepted when the stream takes the single PUT path; a stream that would go multipart (too large, or not seekable) with a checksum throws before anything is sent.

Exceptions

ArgumentException

Thrown if the stream is seekable and its length exceeds R2's 5 TiB limit, or if a checksum accompanies a stream that would go multipart.

CloudflareR2OperationException

Thrown if the upload fails.

NotSupportedException

Thrown if a multipart upload is attempted but the stream is not seekable.

UploadAsync(string, string, Stream, long?, CancellationToken)

Uploads a file from a stream, automatically choosing between a single PUT request or a multipart upload. If the stream is seekable, the choice is based on its length. If it is not seekable, it will always attempt a multipart upload.

public Task<R2Result> UploadAsync(string bucketName, string objectKey, Stream fileStream, long? partSize = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

fileStream Stream

The stream to upload.

partSize long?

The desired size in bytes for each part in a multipart upload. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Exceptions

ArgumentException

Thrown if the stream is seekable and its length exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if the upload fails.

NotSupportedException

Thrown if a multipart upload is attempted but the stream is not seekable.

UploadAsync(string, string, string, long?, string?, UploadChecksum?, string?, CancellationToken)

Uploads a file from a local path, automatically choosing between a single PUT request or a multipart upload based on the file size, and records the object's content type.

public Task<R2Result> UploadAsync(string bucketName, string objectKey, string filePath, long? partSize, string? contentType, UploadChecksum? checksum = null, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

partSize long?

The desired size in bytes for each part in a multipart upload. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

contentType string

The MIME type to record for the object, for example image/webp.

checksum UploadChecksum

An optional digest of the whole object's bytes for R2 to verify on a single-part upload.

cacheControl string

An optional Cache-Control value to store on the object; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset. On the multipart path the value is recorded on the initiate request, alongside the content type.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Remarks

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadAsync(string, string, string, long?, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the file extension, the bytes, or the object key. When the file is large enough to go multipart, the type is recorded on the initiate request, the only place S3 reads the assembled object's Content-Type from.

A checksum binds the upload to a digest of the whole object: R2 hashes the arriving bytes and fails the upload with BadDigest, storing nothing, when they do not hash to the stated digest. Because the digest covers the whole object while a multipart upload is verified per part, a checksum is only accepted for files small enough for a single PUT; a multipart-sized file with a checksum throws before anything is sent.

Exceptions

ArgumentException

Thrown if the file size exceeds R2's 5 TiB limit, or if a checksum accompanies a file large enough to go multipart.

CloudflareR2OperationException

Thrown if the upload fails.

FileNotFoundException

Thrown if the specified filePath does not exist.

UploadAsync(string, string, string, long?, CancellationToken)

Uploads a file from a local path, automatically choosing between a single PUT request or a multipart upload based on the file size.

public Task<R2Result> UploadAsync(string bucketName, string objectKey, string filePath, long? partSize = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

partSize long?

The desired size in bytes for each part in a multipart upload. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Exceptions

ArgumentException

Thrown if the file size exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if the upload fails.

FileNotFoundException

Thrown if the specified filePath does not exist.

UploadMultipartAsync(string, string, Stream, long?, string?, string?, CancellationToken)

Uploads a file from a stream using a multipart upload, recording the content type the assembled object will carry. The stream must be seekable.

public Task<R2Result> UploadMultipartAsync(string bucketName, string objectKey, Stream inputStream, long? partSize, string? contentType, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

inputStream Stream

The stream to upload. Must be seekable.

partSize long?

The desired size in bytes for each part. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

contentType string

The MIME type to record for the assembled object, for example image/webp.

cacheControl string

An optional Cache-Control value to store on the assembled object, recorded on the initiate request like the content type; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the aggregate metrics of the operation.

Remarks

The type is recorded on the initiate request, because S3 reads the assembled object's Content-Type from the initiate call and never from the individual parts.

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadMultipartAsync(string, string, Stream, long?, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the stream contents or the object key.

Exceptions

ArgumentException

Thrown if the stream length exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if any part of the upload fails.

NotSupportedException

Thrown if the provided stream is not seekable.

UploadMultipartAsync(string, string, Stream, long?, CancellationToken)

Uploads a file from a stream using a multipart upload. The stream must be seekable. This method provides direct control over multipart uploads.

public Task<R2Result> UploadMultipartAsync(string bucketName, string objectKey, Stream inputStream, long? partSize = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

inputStream Stream

The stream to upload. Must be seekable.

partSize long?

The desired size in bytes for each part. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the aggregate metrics of the operation.

Exceptions

ArgumentException

Thrown if the stream length exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if any part of the upload fails.

NotSupportedException

Thrown if the provided stream is not seekable.

UploadMultipartAsync(string, string, string, long?, string?, string?, CancellationToken)

Uploads a file using a multipart upload, recording the content type the assembled object will carry.

public Task<R2Result> UploadMultipartAsync(string bucketName, string objectKey, string filePath, long? partSize, string? contentType, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

partSize long?

The desired size in bytes for each part. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

contentType string

The MIME type to record for the assembled object, for example image/webp.

cacheControl string

An optional Cache-Control value to store on the assembled object, recorded on the initiate request like the content type; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the aggregate metrics of the operation.

Remarks

The type is recorded on the initiate request, because S3 reads the assembled object's Content-Type from the initiate call and never from the individual parts.

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadMultipartAsync(string, string, string, long?, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the file extension, the bytes, or the object key.

Exceptions

ArgumentException

Thrown if the file size exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if any part of the upload fails.

UploadMultipartAsync(string, string, string, long?, CancellationToken)

Uploads a file using a multipart upload. This method provides direct control over multipart uploads.

public Task<R2Result> UploadMultipartAsync(string bucketName, string objectKey, string filePath, long? partSize = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

partSize long?

The desired size in bytes for each part. If null, a sensible default is used. The value is clamped between 5MiB and 5GiB.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the aggregate metrics of the operation.

Exceptions

ArgumentException

Thrown if the file size exceeds R2's 5 TiB limit.

CloudflareR2OperationException

Thrown if any part of the upload fails.

UploadSinglePartAsync(string, string, Stream, string?, UploadChecksum?, string?, CancellationToken)

Uploads a file from a stream using a single PUT request, recording the object's content type and optionally binding the upload to a checksum.

public Task<R2Result> UploadSinglePartAsync(string bucketName, string objectKey, Stream inputStream, string? contentType, UploadChecksum? checksum = null, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

inputStream Stream

The stream to upload.

contentType string

The MIME type to record for the object, for example image/webp.

checksum UploadChecksum

An optional digest of the object's bytes for R2 to verify.

cacheControl string

An optional Cache-Control value to store on the object; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Remarks

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadSinglePartAsync(string, string, Stream, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the stream contents or the object key.

A checksum binds the upload to a digest of the object's bytes. R2 hashes what actually arrives and fails the upload with BadDigest, storing nothing, when the bytes do not hash to the stated digest (verified against live R2 for every R2ChecksumAlgorithm on single-part uploads).

Exceptions

ArgumentException

Thrown if the stream is seekable and its length exceeds the 5 GiB single-part upload limit.

CloudflareR2OperationException

Thrown if the upload fails.

UploadSinglePartAsync(string, string, Stream, CancellationToken)

Uploads a file from a stream using a single PUT request. This method provides direct control and should be used when the automatic selection in UploadAsync(string, string, Stream, long?, CancellationToken) is not desired.

public Task<R2Result> UploadSinglePartAsync(string bucketName, string objectKey, Stream inputStream, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

inputStream Stream

The stream to upload.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Exceptions

ArgumentException

Thrown if the stream is seekable and its length exceeds the 5 GiB single-part upload limit.

CloudflareR2OperationException

Thrown if the upload fails.

UploadSinglePartAsync(string, string, string, string?, UploadChecksum?, string?, CancellationToken)

Uploads a file using a single PUT request, recording the object's content type and optionally binding the upload to a checksum.

public Task<R2Result> UploadSinglePartAsync(string bucketName, string objectKey, string filePath, string? contentType, UploadChecksum? checksum = null, string? cacheControl = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

contentType string

The MIME type to record for the object, for example image/webp.

checksum UploadChecksum

An optional digest of the object's bytes for R2 to verify.

cacheControl string

An optional Cache-Control value to store on the object; R2 serves it on every GET, which drives edge and browser caching. null or a blank string leaves the header unset.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Remarks

Passing null or a blank contentType leaves the property unset, so R2 applies its own default and this method behaves exactly like UploadSinglePartAsync(string, string, string, CancellationToken). A non-blank value is applied verbatim; the type is never inferred from the file extension, the bytes, or the object key.

A checksum binds the upload to a digest of the object's bytes. R2 hashes what actually arrives and fails the upload with BadDigest, storing nothing, when the bytes do not hash to the stated digest (verified against live R2 for every R2ChecksumAlgorithm on single-part uploads).

Exceptions

ArgumentException

Thrown if the file size exceeds the 5 GiB single-part upload limit.

CloudflareR2OperationException

Thrown if the upload fails.

UploadSinglePartAsync(string, string, string, CancellationToken)

Uploads a file using a single PUT request. This method provides direct control and should be used when the automatic selection in UploadAsync(string, string, string, long?, CancellationToken) is not desired.

public Task<R2Result> UploadSinglePartAsync(string bucketName, string objectKey, string filePath, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the target bucket.

objectKey string

The key (path) for the object in the bucket.

filePath string

The path to the local file to upload.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Result>

An R2Result detailing the metrics of the operation.

Exceptions

ArgumentException

Thrown if the file size exceeds the 5 GiB single-part upload limit.

CloudflareR2OperationException

Thrown if the upload fails.