Sa.HybridFileStorage.S3 0.20.0

dotnet add package Sa.HybridFileStorage.S3 --version 0.20.0
                    
NuGet\Install-Package Sa.HybridFileStorage.S3 -Version 0.20.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sa.HybridFileStorage.S3" Version="0.20.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sa.HybridFileStorage.S3" Version="0.20.0" />
                    
Directory.Packages.props
<PackageReference Include="Sa.HybridFileStorage.S3" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sa.HybridFileStorage.S3 --version 0.20.0
                    
#r "nuget: Sa.HybridFileStorage.S3, 0.20.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sa.HybridFileStorage.S3@0.20.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sa.HybridFileStorage.S3&version=0.20.0
                    
Install as a Cake Addin
#tool nuget:?package=Sa.HybridFileStorage.S3&version=0.20.0
                    
Install as a Cake Tool

Sa.HybridFileStorage.S3

English | Русский

S3-compatible cloud storage provider for Sa.HybridFileStorage. Wraps Minio/AWS S3 with automatic bucket creation, MIME type detection, and streaming file I/O.


Table of Contents


Overview

S3FileStorage implements IFileStorage backed by any S3-compatible service (AWS S3, MinIO, DigitalOcean Spaces, etc.). Key characteristics:

  • Auto bucket creation — creates the target bucket on first upload if it doesn't exist (thread-safe, single-flight)
  • MIME type detection — resolves content type from file extension using MimeTypeMap
  • Streaming uploads/downloads — uses IS3BucketClient for memory-efficient transfers
  • Thread-safe initialization — concurrent EnsureBucket calls are deduplicated via Interlocked.CompareExchange

File ID Format

s3://{basket}/{tenantId}/{fileName}

Examples:

  • s3://uploads/42/document.pdf
  • s3://avatars/7/profile.png
  • s3://backups/100/database.sql

Installation

dotnet add package Sa.HybridFileStorage.S3

This package depends on Sa.Data.S3 which provides the underlying IS3BucketClient.


Quick Start

Registration

The storage is created by AddSaS3FileStorage — there is no public constructor. Each call registers one storage with its own named options instance and its own keyed bucket client:

using Microsoft.Extensions.Hosting;
using Sa.HybridFileStorage.Domain;
using Sa.HybridFileStorage.S3;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSaS3FileStorage(o => o.Options(ob => ob.Configure(x =>
{
    x.Endpoint = "http://localhost:9000";
    x.AccessKey = "ROOTUSER";
    x.SecretKey = "ChangeMe123";
    x.Bucket = "mybucket";
    x.Basket = "uploads";
    x.Region = "us-east-1";
})));

var host = builder.Build();

// Every call adds one IFileStorage; this resolves the storage registered above. When several S3
// storages live in one container, use GetServices<IFileStorage>() or let the hybrid container
// order them into the failover chain.
var storage = host.Services.GetRequiredService<IFileStorage>();

Options pipeline

AddSaS3FileStorage takes the standard options callback, so configuration goes through Configure / PostConfigure / Validate like any other options type:

using Sa.HybridFileStorage.S3;

builder.Services.AddSaS3FileStorage(o => o.Options(ob => ob.Configure(x =>
{
    x.Endpoint = "http://localhost:9000";
    x.AccessKey = "ROOTUSER";
    x.SecretKey = "ChangeMe123";
    x.Bucket = "mybucket";
    x.Basket = "uploads";
    x.Region = "us-east-1";
})));

The bucket client is created per registration — keyed by the registration's name and built from its very options — and resolved together with its storage. A shared bare IS3BucketClient is not provided by the hybrid registration; register a named client with AddSaS3BucketClient(name, ...) and resolve it via GetRequiredKeyedService<IS3BucketClient>(name) if you need one.

Transport tuning is not a nested object here — TotalRequestTimeout, ConnectionPoolLifetime and HandlerLifetime are properties of the same options instance the bucket client is built from.

From a configuration section

// appsettings.json:
// { "S3FileStorage": { "Endpoint": "http://localhost:9000", "AccessKey": "…", "SecretKey": "…", "Bucket": "mybucket", "Basket": "uploads" } }
builder.Services.AddSaS3FileStorage(b => b.FromConfiguration("S3FileStorage"));

The section binds in a fixed slot first, so an Options(...) Configure has the last word. The Options(...) actions replay after the registration's own PostConfigure and Validate, so your checks add to the built-in ones instead of replacing them.


CRUD Examples

Upload from Stream

using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, S3!"));
var result = await storage.UploadAsync(
    new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
    stream, ct);

// File stored at: mybucket/uploads/1/hello.txt
// Content-Type: text/plain (auto-detected from extension)

Upload Large Files

// Streaming large files without loading into memory
await using var fs = new FileStream(@"C:\large\data.zip", new FileStreamOptions
{
    Mode = FileMode.Open,
    Access = FileAccess.Read,
    Share = FileShare.Read,
    Options = FileOptions.Asynchronous | FileOptions.SequentialScan
});

var result = await storage.UploadAsync(
    new UploadFileInput { FileName = "data.zip", TenantId = 5 },
    fs, ct);

Download to Memory

byte[]? downloaded = default;
await storage.DownloadAsync(result.FileId, async (stream, token) =>
{
    downloaded = await stream.ReadAllBytesAsync(token);
}, ct);

Download to Disk

await using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
await storage.DownloadAsync(result.FileId, async (source, token) =>
    await source.CopyToAsync(destination, 1024 * 1024, token),  // 1 MB buffer
    ct);

Get Metadata

var metadata = await storage.GetMetadataAsync(result.FileId, ct);
if (metadata != null)
{
    Console.WriteLine($"Basket: {metadata.Basket}");       // uploads
    Console.WriteLine($"Tenant: {metadata.TenantId}");      // 42
    Console.WriteLine($"Name: {metadata.FileName}");        // document.pdf
    Console.WriteLine($"Type: {metadata.StorageType}");     // s3
}

Delete

bool deleted = await storage.DeleteAsync(result.FileId, ct);
// Always returns true if CanProcess(fileId) == true — S3 deletes silently ignore missing objects

Settings Reference

S3FileStorageOptions

Property Description Default
Endpoint S3-compatible endpoint URL (required)
AccessKey Access key ID (required)
SecretKey Secret access key (required)
Bucket Target bucket name (required)
Basket Scope/container prefix within the bucket "share"
Region AWS region for SigV4 signing "eu-central-1"
StorageType Scheme prefix in File ID "s3"
IsReadOnly Prevent write/delete operations false
TotalRequestTimeout Per-request timeout 180 sec
ConnectionPoolLifetime Connection pool lifetime 15 min
HandlerLifetime HttpClient handler lifetime ∞ (infinite)
Service, UseHttp2 SigV4 service name / force HTTP/2 "s3" / false

S3FileStorageOptions is a single mutable type served by the options pipeline, and it inherits the connection and transport settings from S3BucketClientSetupOptions — the very type the bucket client is constructed from. There is no second copy and no hand-written projection, which is how UseHttp2 used to be configurable yet never applied.

Options are validated

Values are normalised first (PostConfigure), then validated. ValidateOnStart() turns an invalid configuration into an OptionsValidationException at host start rather than a bare UriFormatException from the middle of the first upload:

Property Requirement
Endpoint absolute http(s) URL, not blank
AccessKey, SecretKey, Bucket not null or blank
StorageType at most 10 characters, no :, / or \ (it becomes the file ID scheme)
Basket 3-63 characters, starts with a letter or _, no path separator
TotalRequestTimeout, ConnectionPoolLifetime positive
HandlerLifetime positive, or Timeout.InfiniteTimeSpan

The same checks stay usable from a non-DI path:

options.Validate(); // throws DataAnnotations.ValidationException naming the offending option

Several S3 storages per service collection

Registration is additive: every AddSaS3FileStorage call registers one IFileStorage with its own named options instance and its own keyed bucket client. Several S3 storages — even several in the same basket, which is how two buckets back one folder — coexist in one collection:

// Two buckets, one folder: reads probe bucket-a first and continue to bucket-b on a miss
// (same storage type), uploads are first-wins into bucket-a.
builder.Services.AddSaS3FileStorage(o => o.Options(ob => ob.Configure(x =>
{
    x.Endpoint = "http://localhost:9000";
    x.AccessKey = "ROOTUSER";
    x.SecretKey = "ChangeMe123";
    x.Bucket = "bucket-a";
})));
builder.Services.AddSaS3FileStorage(o => o.Options(ob => ob.Configure(x =>
{
    x.Endpoint = "http://localhost:9000";
    x.AccessKey = "ROOTUSER";
    x.SecretKey = "ChangeMe123";
    x.Bucket = "bucket-b";
})));

Each registration's options live under a unique name, and the bucket client is built from that very instance and keyed by the same name — so no two storages ever share a client or an options instance, and the settings of one registration can never merge into another. The registration order is the probing order of the basket's chain.

Rotate credentials or retarget a bucket by editing that storage's registration, not by adding another that would compete for the same play.


Dependencies

Package Purpose
Sa.Data.S3 S3 client (IS3BucketClient, S3BucketClient)
Sa Shared utilities (MimeTypeMap)

The AddSaS3FileStorage extension method registers one IS3BucketClient per call — keyed by the registration's name and built from its very options — through the same internal HTTP wiring (pool, resilience, handler lifetime) that the public named AddSaS3BucketClient(name, ...) uses.


License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.20.0 65 11/13/2026
0.18.0 98 11/3/2026
0.17.0 98 10/29/2026
0.16.0 106 10/14/2026
0.15.0 102 10/2/2026
0.12.0 134 7/28/2026
0.11.0 124 7/14/2026
0.10.0 129 7/2/2026
0.9.1 132 5/8/2026
0.9.0 126 4/29/2026
0.8.3 134 3/11/2026
0.8.1 130 3/6/2026
0.8.0 131 2/10/2026
0.7.0 145 1/27/2026
0.6.0 138 1/15/2026
0.5.0 135 12/29/2025
0.4.0 314 12/17/2025
0.3.0 172 10/17/2025
0.1.0 221 9/1/2025
0.0.3 215 6/16/2025
Loading failed