Interface IR2Client

Namespace

Cloudflare.NET.R2

Assembly

Cloudflare.NET.R2.dll

Defines the contract for a client that interacts with Cloudflare R2's S3-compatible API, with robust error handling and metric reporting.

public interface IR2Client

Methods

AbortMultipartUploadAsync(string, string, string, CancellationToken)

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

DownloadFileAsync(string, string, Stream, CancellationToken)

Downloads a file from an R2 bucket to a stream.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.