NIS.Rustfs.Sdk

A lightweight .NET SDK for RustFS, a fully S3-compatible object storage system. Built on top of the official AWS SDK for .NET (AWSSDK.S3).

Features

• Simple abstraction over AmazonS3Client
• Custom ServiceURL for self-hosted RustFS instances
• Full bucket operations (create, list, delete)
• Full object operations (upload, download, list, delete)
• Image preview support in the included Blazor Server sample
• Built with TreatWarningsAsErrors for production-grade code
• Ships with NuGet symbol package (.snupkg) for debugging

Installation

dotnet add package NIS.Rustfs.Sdk

Prerequisites

• .NET 10 SDK or later
• A running RustFS instance
• RustFS access key and secret key

Quick Start

1. Configure Options

var options = new RustFsOptions
{
    ServiceUrl = "https://rfsapi.nis.mv/",
    AccessKey = "your-access-key",
    SecretKey = "your-secret-key",
    Region = "us-east-1",
    ForcePathStyle = true
};

2. Create Client

using var client = new RustFsClient(options);

Or register with dependency injection:

builder.Services.AddScoped<IRustFsClient>(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var options = config.GetSection("RustFS").Get<RustFsOptions>();
    return new RustFsClient(options);
});

3. Bucket Operations

// Create bucket
await client.CreateBucketAsync("my-bucket");

// List buckets
var buckets = await client.ListBucketsAsync();
foreach (var bucket in buckets)
    Console.WriteLine(bucket.BucketName);

// Delete bucket
await client.DeleteBucketAsync("my-bucket");

4. Object Operations

// Upload from file
await client.UploadAsync("my-bucket", "photo.jpg", @"/path/to/photo.jpg", "image/jpeg");

// Upload from stream
await using var stream = File.OpenRead("document.pdf");
await client.UploadAsync("my-bucket", "document.pdf", stream, "application/pdf");

// Upload from bytes
var bytes = Encoding.UTF8.GetBytes("Hello, RustFS!");
await client.UploadAsync("my-bucket", "hello.txt", bytes, "text/plain");

// Download to bytes
var data = await client.DownloadBytesAsync("my-bucket", "photo.jpg");

// Download to file
await client.DownloadFileAsync("my-bucket", "photo.jpg", @"/path/to/download/photo.jpg");

// List objects
var objects = await client.ListObjectsAsync("my-bucket");
foreach (var obj in objects)
    Console.WriteLine($"{obj.Key} ({obj.Size} bytes)");

// Delete object
await client.DeleteObjectAsync("my-bucket", "photo.jpg");

Configuration File

Example appsettings.json:

{
  "RustFS": {
    "ServiceUrl": "https://rfsapi.nis.mv/",
    "AccessKey": "your-access-key",
    "SecretKey": "your-secret-key",
    "Region": "us-east-1",
    "ForcePathStyle": true
  }
}

Blazor Server Sample

A complete Blazor Server sample app is included in samples/Rustfs.BlazorServer/. It demonstrates:

• Bucket management (list, create, delete)
• Object management (list, upload, download, delete)
• Image preview for downloaded image files

Run the sample:

cd samples/Rustfs.BlazorServer
dotnet run

Then open https://localhost:5001 (or the URL shown in the console).

Image Preview

The sample automatically detects image files (.jpg, .png, .gif, .webp, .bmp, .svg) when downloaded and displays an inline preview using a base64 data URI.

Testing

The SDK includes both unit tests and integration tests.

Unit Tests

Test argument validation without network access:

dotnet test --filter "FullyQualifiedName~RustFsClientTests"

Integration Tests

Tests that perform real S3 operations against your RustFS instance:

1. Update src/NIS.Rustfs.Sdk.Tests/appsettings.Test.json with your credentials
2. Run:

dotnet test --filter "FullyQualifiedName~IntegrationTests"

Each test creates a uniquely named bucket and cleans up after itself.

Building

dotnet build

Packing

dotnet pack src/NIS.Rustfs.Sdk -c Release

Produces:

• NIS.Rustfs.Sdk.1.0.0.nupkg
• NIS.Rustfs.Sdk.1.0.0.snupkg (symbols)

Versioning

This project follows Semantic Versioning.

• MAJOR: Breaking API changes
• MINOR: New features, backwards compatible
• PATCH: Bug fixes, backwards compatible

License

MIT