WriteableFileProviders.AmazonS3 2027.1.0

WriteableFileProviders.AmazonS3

An Amazon S3 bucket, or a bucket on an S3-compatible server, as an IWriteableFileProvider, on AWSSDK.S3 4. Part of WriteableFileProviders.

Install

dotnet add package WriteableFileProviders.AmazonS3

Needs .NET 10, and is native AOT compatible. Keep every WriteableFileProviders package in an app on the same major version.

Use

using WriteableFileProviders;
using WriteableFileProviders.AmazonS3;

await using var files = new WriteableAmazonS3FileProvider(new AmazonS3FileProviderOptions
{
    BucketName = "my-bucket",
    BucketRegion = "eu-west-1",
    UseDefaultCredentials = true,
    RootDirectoryPath = "tenants/acme",
});

await files.UpdateFileAsync("reports/2026.csv", stream);
var url = await files.GetSignedUrlAsync("reports/2026.csv", new SignedUrlOptions { Validity = TimeSpan.FromHours(1) });

From configuration (services.AddWriteableFileProvider(section)):

{ "Files": { "Type": "WriteableAmazonS3FileProvider", "BucketName": "my-bucket", "BucketRegion": "eu-west-1",
             "AccessKey": "...", "SecretKey": "..." } }

Or pass an IAmazonS3 you build (assumed roles, retries, a shared client), which the provider never disposes: new WriteableAmazonS3FileProvider(new AmazonS3FileProviderOptions { BucketName = "my-bucket" }, s3). The client's credentials and endpoint are used; the options give the bucket, the root, the storage class and CreateBucketIfMissing.

Configuration

Authentication

The first that applies: UseDefaultCredentials, then IsAnonymus, then AccessKey with SecretKey. None of them, or UseDefaultCredentials with AccessKey, throws ArgumentException when the provider is built. For anything else, pass your own IAmazonS3. Nothing touches the network until the first call.

What's different

• Writes up to 8 MiB are one PUT, larger ones a multipart upload. A failed write leaves the old content.
• Conditions (IfMatch, IfNotExists) go to S3 with the write, which checks them atomically. Toward a ServiceUrl, the provider also checks them first: not atomic, since the server may ignore them.
• Appends rewrite the file with If-Match on the version read: a concurrent write makes the append throw PreconditionFailedException.
• Copies and moves run on the server, files over 5 GiB in parts of 512 MiB or more. A move deletes the source with If-Match and undoes the copy if the source changed meanwhile.
• Listings carry no content type; GetFileInfoAsync does. Requester-pays buckets work on AWS.
• Old versions: ReadFileVersionAsync(versionId, path) reads one in a bucket with versioning.
• Signed URLs are presigned (SigV4) read and write URLs, up to 7 days. Create URLs are native only on AWS without a ServiceUrl; elsewhere the gateway issues them. A URL never outlives its credential: with temporary credentials, or your own client, set AllowShorterValidity. An anonymous provider can't presign.
• AWS_ENDPOINT_URL_S3, AWS_ENDPOINT_URL or a profile's endpoint_url redirect the provider like a ServiceUrl does. Set AWS_IGNORE_CONFIGURED_ENDPOINT_URLS to ignore them.
• Limits: 10,000 parts per file: 5 TiB from a stream with a known length, about 430 GiB without. Watch throws NotSupportedException.

Learn more

• The guide: reading and writing, signed URLs, errors, providers compared.
• Moving from 2026.