Sa.Data.S3
0.20.0
dotnet add package Sa.Data.S3 --version 0.20.0
NuGet\Install-Package Sa.Data.S3 -Version 0.20.0
<PackageReference Include="Sa.Data.S3" Version="0.20.0" />
<PackageVersion Include="Sa.Data.S3" Version="0.20.0" />
<PackageReference Include="Sa.Data.S3" />
paket add Sa.Data.S3 --version 0.20.0
#r "nuget: Sa.Data.S3, 0.20.0"
#:package Sa.Data.S3@0.20.0
#addin nuget:?package=Sa.Data.S3&version=0.20.0
#tool nuget:?package=Sa.Data.S3&version=0.20.0
Sa.Data.S3
English | Русский
Wrapper over HttpClient for S3-compatible storage systems (Minio, AWS S3, DigitalOcean Spaces, etc.) with a fully self-implemented AWS Signature Version 4 — no dependencies on AWS SDK or Minio SDK.
Installation
dotnet add package Sa.Data.S3
Contents
- Installation
- Features
- Quick Start
- Configuration in appsettings
- Named clients
- Settings
- Motivation
- License
Features
- Own AWS SigV4 implementation — neither AWS SDK nor Minio SDK in the dependencies: just
HttpClientandMicrosoft.Extensions.*. - Low memory footprint — roughly 150× lower than the Minio SDK and 17× lower than the AWS SDK, at speed comparable to AWS.
- Named clients —
AddSaS3BucketClient("name", ...): its own namedHttpClient(connection pool, resilience, handler lifetime), its own settings and its ownIS3BucketClientper name; resolve withGetRequiredKeyedService<IS3BucketClient>("name"). - Configuration in appsettings — an
S3section bound viaFromConfiguration, withConfigure/PostConfigure/Validateon top; a bad configuration fails the host at start-up rather than mid-request. - Files — upload (including multipart uploads via
S3Upload, whoseDisposeAsyncaborts an unfinished upload), streamed reads, listing by prefix withList(followsNextContinuationToken, so a bucket with more than 1000 objects is listed completely), presigned links viaBuildFileUrl(fileName, expiration)/GetFileUrl,IsFileExists,DeleteFile. A missing object is not an error:GetFilereturns a wrapper withExists == falseandnullLength/ContentType. - Buckets —
CreateBucket,DeleteBucket(with an optional force mode that empties the bucket in batches of 1000),IsBucketExists. - Transport under control — per-request timeout, connection-pool and handler lifetime, HTTP/2 — all in
S3BucketClientSetupOptions. Sa.HybridFileStorage.S3integration — theAddSaS3FileStorageprovider registers each folder's client with the same named registration.
Quick Start
Without DI
using Sa.Data.S3;
var client = new S3BucketClient(
new HttpClient { Timeout = TimeSpan.FromMinutes(3) },
new S3BucketSettings
{
Bucket = "mybucket",
Endpoint = "http://localhost:9000",
AccessKey = "ROOTUSER",
SecretKey = "ChangeMe123"
});
CancellationToken ct = CancellationToken.None;
await client.UploadFile("docs/hello.txt", "text/plain", "hello"u8.ToArray(), ct);
using Stream stream = await client.GetFileStream("docs/hello.txt", ct);
The options pipeline kicks in only with the DI registration; without it the transport is configured on the HttpClient itself (timeout, connection pool) and HTTP/2 via S3BucketSettings.UseHttp2. The constructor still validates the settings with the same Validate() the pipeline calls, so a missing bucket or a malformed endpoint fails immediately instead of mid-request.
With DI
services.AddSaS3BucketClient("my-client", o => o.Options(ob => ob.Configure(x =>
{
x.Bucket = "mybucket";
x.Endpoint = "http://localhost:9000";
x.AccessKey = "ROOTUSER";
x.SecretKey = "ChangeMe123";
})));
IS3BucketClient client = serviceProvider.GetRequiredKeyedService<IS3BucketClient>("my-client");
await client.UploadFile("docs/hello.txt", "text/plain", "hello"u8.ToArray(), ct);
// Presigned link, valid for an hour; null when the file does not exist.
string? url = await client.GetFileUrl("docs/hello.txt", TimeSpan.FromHours(1), ct);
The registration name is the key to everything: the named HttpClient, the settings, the options instance and the client itself. Several clients per host and the naming rules — see Named clients.
Configuration in appsettings
{
"S3": {
"Endpoint": "http://minio:9000",
"AccessKey": "ROOTUSER",
"SecretKey": "ChangeMe123",
"Bucket": "mybucket",
"Region": "us-east-1",
"TotalRequestTimeout": "00:03:00"
}
}
services.AddSaS3BucketClient("my-client", b =>
{
b.FromConfiguration("S3");
b.Options(ob => ob.Validate(
v => !string.IsNullOrWhiteSpace(v.SecretKey),
"SecretKey is required"));
});
AddSaS3BucketClient takes a single builder callback: FromConfiguration binds the section, Options(...) hands you the standard OptionsBuilder<S3BucketClientSetupOptions> — configuration goes through the ordinary options pipeline, no bespoke overloads.
- The section is an ordinary host configuration section:
appsettings.{Environment}.json, environment variables (S3__Bucket=mybucket) and the wholeIConfigurationchain work as usual.FromConfigurationmay be called several times — the last path wins. - The section binds in a fixed slot first, so an
Options(...)Configurehas the last word — wherever those calls sit in the callback. TheOptions(...)actions replay after the registration's ownPostConfigureandValidate, so your checks add to the built-in ones instead of replacing them. - Validation is on by default: the registration itself calls
ValidateOnStart(), so a bad section yields anOptionsValidationExceptionat host start rather than a bareUriFormatExceptionfrom the middle of the first upload. Extra checks are added viaValidate(...)inOptions(...); the same checks are available outside DI:
options.Validate(); // throws DataAnnotations.ValidationException
Named clients
Every registration is keyed by its name, and the name must be unique in the service collection: a second AddSaS3BucketClient call under the same name throws InvalidOperationException, because the second Configure would stack on the same named options instance and a second keyed client under the same key would make resolution ambiguous. Different names, however, are fully independent — each gets its own named HttpClient (connection pool, resilience, handler lifetime), its own keyed S3BucketSettings, its own keyed IS3BucketClient and its own named options instance:
services.AddSaS3BucketClient("orders", o => o.Options(ob => ob.Configure(x =>
{
x.Endpoint = "http://minio:9000";
x.AccessKey = "ROOTUSER";
x.SecretKey = "ChangeMe123";
x.Bucket = "orders-bucket";
})));
services.AddSaS3BucketClient("archive", o => o.Options(ob => ob.Configure(x =>
{
x.Endpoint = "http://minio:9000";
x.AccessKey = "ROOTUSER";
x.SecretKey = "ChangeMe123";
x.Bucket = "archive-bucket";
})));
Two clients never share credentials, timeouts or a connection pool. The HTTP wiring underneath is shared code exposed internally as AddSaS3BucketClientCore(services, clientName, settingsFactory).
Resolving the client — keyed by the registration name; there are no unkeyed aliases, so GetService<IS3BucketClient>() returns null and GetRequiredService<IS3BucketClient>() throws:
IS3BucketClient ordersClient = serviceProvider.GetRequiredKeyedService<IS3BucketClient>("orders");
S3BucketSettings ordersSettings = serviceProvider.GetRequiredKeyedService<S3BucketSettings>("orders");
The S3 provider of Sa.HybridFileStorage.S3 (AddSaS3FileStorage, call it once per storage) keys each storage's client by the registration's name the same way, so two storages — even two with the same endpoint — stay isolated, and a read that misses the first bucket continues to the next one of the same storage type. For AddSaS3FileStorage the registration name is an internal detail — the storage resolves its own client together with its options, so consumers never hardcode the key.
Settings
S3BucketClientSetupOptions inherits S3BucketSettings, so the very same object is handed to S3BucketClient — there is no projection between them that could quietly drop a property.
| Property | Description | Default |
|---|---|---|
AccessKey |
S3 access key | (required) |
SecretKey |
S3 secret key | (required) |
Bucket |
Bucket name | (required) |
Endpoint |
S3 storage URL (absolute http/https) | (required) |
Region |
Region for SigV4 | "us-east-1" |
Service |
Service name for SigV4 | "s3" |
UseHttp2 |
Force HTTP/2 | false |
TotalRequestTimeout |
Per-request timeout | 180 sec |
ConnectionPoolLifetime |
Connection pool lifetime | 15 min |
HandlerLifetime |
HttpClient handler lifetime | ∞ (infinite) |
TotalRequestTimeout, ConnectionPoolLifetime and HandlerLifetime belong to the named HttpClient of the DI registration; when creating a client by hand, the timeout is set on the HttpClient itself. HandlerLifetime applies to clients obtained from IHttpClientFactory directly: the keyed IS3BucketClient is a singleton holding one HttpClient, so for its connections the effective knob is ConnectionPoolLifetime.
Motivation
This is a fork of teoadal/Storage. The motivation was memory: the AWS SDK for .NET (4.x) and Minio .NET (6.x) clients consumed too much of it. The package keeps the idea of a lean HttpClient-only client; the speed and memory benchmark results are listed under Features.
License
MIT
| Product | Versions 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. |
-
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Http.Resilience (>= 10.11.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Options (>= 10.0.14)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.14)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Sa.Data.S3:
| Package | Downloads |
|---|---|
|
Sa.HybridFileStorage.S3
File storage management in S3 |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.20.0 | 72 | 11/13/2026 |
| 0.18.0 | 110 | 11/3/2026 |
| 0.17.0 | 107 | 10/29/2026 |
| 0.16.0 | 111 | 10/14/2026 |
| 0.15.0 | 113 | 10/2/2026 |
| 0.12.0 | 149 | 7/28/2026 |
| 0.11.0 | 142 | 7/14/2026 |
| 0.10.0 | 150 | 7/2/2026 |
| 0.9.0 | 142 | 4/29/2026 |
| 0.8.0 | 162 | 2/10/2026 |
| 0.7.0 | 161 | 1/27/2026 |
| 0.6.0 | 144 | 1/15/2026 |
| 0.5.0 | 157 | 12/29/2025 |
| 0.4.0 | 326 | 12/17/2025 |
| 0.3.0 | 193 | 10/17/2025 |
| 0.1.0 | 236 | 9/1/2025 |
| 0.0.3 | 226 | 6/16/2025 |
| 0.0.2 | 321 | 5/15/2025 |