S3Lite 1.1.0

S3Lite

Lightweight Amazon S3 and S3-compatible storage client for .NET.

S3Lite keeps the surface area small while still covering the core bucket and object operations most applications actually need. It targets AWS S3, Less3, MinIO, LocalStack, and other S3-compatible endpoints without dragging in the official AWS SDK.

Why S3Lite

• Small dependency footprint
• Simple fluent client configuration
• AWS S3 and S3-compatible endpoint support
• Anonymous access support for public buckets
• Caller-supplied HttpClient support for DI, proxying, custom handlers, and connection reuse
• Multi-targeted package: netstandard2.0, netstandard2.1, net8.0, and net10.0

New in v1.1.0

• Upgraded to RestWrapper v3.2.0
• Added support for caller-supplied HttpClient instances
• Reworked the automated test infrastructure around Touchstone
• Added xUnit and NUnit runner projects alongside the console runner

Installation

dotnet add package S3Lite

Quick Start

AWS S3 with Credentials

using System;
using System.Text;
using S3Lite;
using S3Lite.ApiObjects;

S3Client s3 = new S3Client()
    .WithRegion("us-west-1")
    .WithAccessKey("AKIAIOSFODNN7EXAMPLE")
    .WithSecretKey("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
    .WithRequestStyle(RequestStyleEnum.VirtualHostedStyle)
    .WithLogger(Console.WriteLine);

ListAllMyBucketsResult buckets = await s3.Service.ListBucketsAsync();

await s3.Object.WriteAsync(
    "my-bucket",
    "hello.txt",
    Encoding.UTF8.GetBytes("hello from s3lite"),
    "text/plain");

byte[] data = await s3.Object.GetAsync("my-bucket", "hello.txt");
Console.WriteLine(Encoding.UTF8.GetString(data));

Anonymous Access for Public Buckets

If a bucket is public, simply omit credentials:

using System;
using S3Lite;
using S3Lite.ApiObjects;

S3Client s3 = new S3Client()
    .WithRegion("us-west-1")
    .WithRequestStyle(RequestStyleEnum.VirtualHostedStyle);

ListBucketResult result = await s3.Bucket.ListAsync("public-dataset-bucket");
Console.WriteLine(result.Contents.Count);

S3-Compatible Storage

using S3Lite;

S3Client s3 = new S3Client()
    .WithHostname("localhost")
    .WithPort(9000)
    .WithProtocol(ProtocolEnum.Http)
    .WithRegion("us-west-1")
    .WithRequestStyle(RequestStyleEnum.PathStyle)
    .WithAccessKey("minioadmin")
    .WithSecretKey("minioadmin");

Bring Your Own HttpClient

S3Lite now exposes the caller-supplied HttpClient support added in RestWrapper v3.2.0. Use this when you already manage HttpClient instances through dependency injection, need a custom handler pipeline, or want to centralize transport settings.

using System;
using System.Net.Http;
using S3Lite;

HttpClient httpClient = new HttpClient();
httpClient.Timeout = TimeSpan.FromSeconds(30);

S3Client s3 = new S3Client(httpClient)
    .WithRegion("us-east-1")
    .WithHostname("s3.us-east-1.amazonaws.com")
    .WithRequestStyle(RequestStyleEnum.PathStyle)
    .WithAccessKey("AKIAIOSFODNN7EXAMPLE")
    .WithSecretKey("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");

bool exists = await s3.Bucket.ExistsAsync("my-bucket");

You can also attach one fluently:

S3Client s3 = new S3Client()
    .WithHttpClient(httpClient)
    .WithRegion("us-east-1");

Notes:

• The caller owns the lifetime of the supplied HttpClient
• S3Lite does not dispose a caller-supplied HttpClient
• Transport behavior such as proxying, TLS, decompression, retries, and timeouts should be configured on your HttpClient or its handler

Common Operations

Service APIs

ListAllMyBucketsResult buckets = await s3.Service.ListBucketsAsync();

Bucket APIs

bool exists = await s3.Bucket.ExistsAsync("my-bucket");

await s3.Bucket.WriteAsync("my-bucket", "us-west-1");

ListBucketResult objects = await s3.Bucket.ListAsync("my-bucket");

ListBucketResult filtered = await s3.Bucket.ListAsync("my-bucket", prefix: "images/");

ListBucketResult page = await s3.Bucket.ListAsync("my-bucket", continuationToken: "token-value", maxKeys: 100);

await s3.Bucket.DeleteAsync("my-bucket");

Object APIs

await s3.Object.WriteAsync("my-bucket", "notes/hello.txt", Encoding.UTF8.GetBytes("hello"));

bool exists = await s3.Object.ExistsAsync("my-bucket", "notes/hello.txt");

ObjectMetadata metadata = await s3.Object.GetMetadataAsync("my-bucket", "notes/hello.txt");

byte[] data = await s3.Object.GetAsync("my-bucket", "notes/hello.txt");

await s3.Object.DeleteAsync("my-bucket", "notes/hello.txt");

Endpoint Guidance

The right hostname depends on the request style you choose:

For S3-compatible platforms such as Less3, MinIO, or LocalStack, point Hostname and Port at your service endpoint and usually prefer PathStyle.

Key Client Properties

Error Behavior

S3Lite throws WebException for failed requests and includes useful context in the exception Data collection, including:

• StatusCode
• URL
• RequestBody
• ResponseBody
• S3 error metadata such as RequestId, VersionId, Resource, and ErrorCode when available

Automated Testing

The repository now uses Touchstone so the same shared descriptors can run through multiple hosts:

• src/Test.Shared: shared Touchstone descriptors and test configuration
• src/Test.Automated: console runner using Touchstone.Cli
• src/Test.Xunit: xUnit adapter host
• src/Test.Nunit: NUnit adapter host

Run the Console Runner

dotnet run --framework net8.0 --project src/Test.Automated -- -b my-bucket -a ACCESS_KEY -s SECRET_KEY

Optional arguments:

• --endpoint <host>
• --port <port>
• --region <region>
• --http
• --https
• --path-style
• --virtual-hosted
• --verbose
• --skip-cleanup
• --skip-write-tests
• --results <path>

Run xUnit and NUnit

dotnet test src/Test.Xunit/Test.Xunit.csproj
dotnet test src/Test.Nunit/Test.Nunit.csproj

These runners read the same configuration from environment variables:

• S3LITE_TEST_ENDPOINT
• S3LITE_TEST_PORT
• S3LITE_TEST_REGION
• S3LITE_TEST_ACCESS_KEY
• S3LITE_TEST_SECRET_KEY
• S3LITE_TEST_BUCKET
• S3LITE_TEST_PROTOCOL
• S3LITE_TEST_REQUEST_STYLE
• S3LITE_TEST_VERBOSE
• S3LITE_TEST_SKIP_CLEANUP
• S3LITE_TEST_SKIP_WRITE_TESTS

Example Projects

• src/Test.S3: interactive AWS S3 example
• src/Test.S3Compatible: interactive S3-compatible example
• src/Test.Script: script-style object hierarchy walkthrough
• src/Test.LargeEnumeration: large-listing exercise

Feedback and Enhancements

Encounter an issue or have an enhancement request? Please open an issue or start a discussion in the repository.

Version History

See CHANGELOG.md for release details.