GM.FileStorage
1.2.0
See the version list below for details.
dotnet add package GM.FileStorage --version 1.2.0
NuGet\Install-Package GM.FileStorage -Version 1.2.0
<PackageReference Include="GM.FileStorage" Version="1.2.0" />
<PackageVersion Include="GM.FileStorage" Version="1.2.0" />
<PackageReference Include="GM.FileStorage" />
paket add GM.FileStorage --version 1.2.0
#r "nuget: GM.FileStorage, 1.2.0"
#:package GM.FileStorage@1.2.0
#addin nuget:?package=GM.FileStorage&version=1.2.0
#tool nuget:?package=GM.FileStorage&version=1.2.0
<p align="center"> <img src="https://raw.githubusercontent.com/gmetskhvarishvili/GM.FileStorage/master/icon.png" alt="GM.FileStorage" width="140" height="140" /> </p>
GM.FileStorage
A provider-agnostic file/blob storage abstraction for .NET. Depend on one interface —
IFileStorageService — with streaming upload/download (no loading large files into memory),
metadata + SHA-256 checksum validation, presigned URLs, and a pluggable key/path strategy
(e.g. tenant/user-scoped folders). The backend is chosen by configuration, so switching disk →
S3 → Azure Blob is a config change, not a code change. Targets .NET 10.
Packages
Core has no provider dependencies; each backend is its own package (like
GM.Messaging / its transports). They version and release in lockstep:
| Package | Backend | Status |
|---|---|---|
GM.FileStorage |
core abstraction + config-driven selection | ✅ shipped |
GM.FileStorage.Local |
local disk (dev / tests) | ✅ shipped |
GM.FileStorage.S3 |
AWS S3 / S3-compatible (MinIO) | ✅ shipped |
GM.FileStorage.AzureBlob |
Azure Blob Storage | ✅ shipped |
GM.FileStorage.Domain |
domain model for keeping files in your database: GMStoredFile + metadata |
🆕 new |
GM.FileStorage.Persistence |
EF Core configurations + table names for those entities | 🆕 new |
dotnet add package GM.FileStorage
dotnet add package GM.FileStorage.Local
The interface
public interface IFileStorageService
{
Task<FileMetadata> UploadAsync(FileUploadRequest request, CancellationToken ct = default);
Task<FileDownloadResult> DownloadAsync(string key, CancellationToken ct = default);
Task<bool> ExistsAsync(string key, CancellationToken ct = default);
Task DeleteAsync(string key, CancellationToken ct = default);
Task<Uri> GetPresignedUrlAsync(string key, PresignedUrlRequest request, CancellationToken ct = default);
}
No provider types leak into the surface — just streams, keys and the GM types:
FileUploadRequest—Stream Content,FileName,ContentType, optionalKey,Visibility(Private/Public), customMetadata, and an optionalExpectedChecksum.FileMetadata—Key,FileName,ContentType,Size,Checksum,Visibility,LastModifiedUtc,Metadata.FileDownloadResult— a disposableStream Content+FileMetadata(streamed, not buffered).PresignedUrlRequest—Expiry+Operation(Read/Write).IFileKeyStrategy— decides the storage key when a request doesn't set one.
Quick start
using GM.FileStorage;
using GM.FileStorage.Local;
builder.Services.AddGMFileStorage(builder.Configuration); // reads FileStorage:Provider
builder.Services.AddGMLocalFileStorage(builder.Configuration); // contributes the "Local" backend
// appsettings.json
"FileStorage": {
"Provider": "Local", // swap to "S3" / "AzureBlob" once those packages are added
"Local": { "RootPath": "App_Data/files", "PublicBaseUrl": "http://localhost:5000/files" }
}
Then inject IFileStorageService — the same code works on any backend:
public class KycDocuments(IFileStorageService storage)
{
public async Task<string> StoreAsync(Stream file, string fileName, string tenantId, string userId)
{
var meta = await storage.UploadAsync(new FileUploadRequest(file, fileName, "application/pdf")
{
Visibility = FileVisibility.Private,
Metadata = new Dictionary<string, string> { ["tenantId"] = tenantId, ["userId"] = userId },
// ExpectedChecksum = "<sha256>", // reject if the bytes don't match end to end
});
return meta.Key; // e.g. tenants/acme/users/u1/9f1c…a3.pdf with a tenant/user key strategy
}
public async Task<Uri> LinkAsync(string key) =>
await storage.GetPresignedUrlAsync(key, new PresignedUrlRequest { Expiry = TimeSpan.FromMinutes(10) });
}
Config-driven provider selection
AddGMFileStorage resolves IFileStorageService to the backend named by
FileStorage:Provider. Each provider package registers itself as a keyed service under its name
("Local", "S3", "AzureBlob"). Reference the providers you might use, call their AddGM…
methods, and pick between them purely in config — no code change to swap.
Pluggable key/path strategy
The default key is date-partitioned and collision-free (2026/08/02/{guid}.pdf). For the KYC flow,
replace IFileKeyStrategy to scope by tenant/user:
public sealed class TenantKeyStrategy : IFileKeyStrategy
{
public string GenerateKey(FileKeyContext ctx) =>
$"tenants/{ctx.Metadata["tenantId"]}/users/{ctx.Metadata["userId"]}/{Guid.NewGuid():N}{Path.GetExtension(ctx.FileName)}";
}
builder.Services.AddSingleton<IFileKeyStrategy, TenantKeyStrategy>();
Streaming & integrity
Uploads and downloads stream through an 80 KiB buffer, so a large KYC scan or image is never fully
in memory. Every upload's SHA-256 is computed in the same pass; set
FileUploadRequest.ExpectedChecksum and a mismatch is rejected with ChecksumMismatchException
and nothing is stored.
Keeping files in your database (GM.FileStorage.Domain + GM.FileStorage.Persistence)
Object storage only answers "give me the file at this key". It can't list "every file for tenant
acme", and provider metadata (x-amz-meta-*, blob metadata, the local .gmmeta sidecar) isn't
searchable. To do that, keep each file's properties in your own database. The two packages give you
the domain model and its EF Core mapping, laid out like GM.Identity; your app subclasses them, as
GM.Identity.Samples does.
GM.FileStorage.Domain/
FileStorage/ # bounded context
StoredFileAggregate/
Entities/GMStoredFile.cs # GMStoredFile<TStoredFile, TStoredFileMetadata>
Events/GMStoredFile{Uploaded,Replaced,Deleted,Restored,Activated,Deactivated,Hidden,Unhidden}DomainEvent.cs
StoredFileMetadataAggregate/
Entities/GMStoredFileMetadata.cs # one name/value pair per row
GM.FileStorage.Persistence/
Configuration/GMStoredFileConfiguration.cs # generic; override Schema / Table / Configure
Configuration/GMStoredFileMetadataConfiguration.cs
GMFileStorageTableNames.cs # gm_file_storage.gm_stored_files / gm_stored_file_metadata
GMStoredFile(SoftDeletableEntity<Guid>from GM.EntityFramework) holds the key (unique, up to 450 characters), file name, content type, size, checksum,IsPublicand upload time.Replace(...)records a new upload to the same key, restoring the record if it was deleted.- It raises a domain event for each change. On a
GenericDbContext, they're written to the domain-event log in the same save.
GMStoredFileMetadataholds one metadata pair per row (tenantId = acme), unique per file and name and indexed on (name, value). Filtering files by tenant or user is an index lookup throughGMStoredFile.Metadata.- Constructors are protected. Your app's aggregates subclass the bases and expose the factories.
In your app's Domain:
public class StoredFile : GMStoredFile<StoredFile, StoredFileMetadata>, IAggregateRoot
{
private StoredFile() { } // EF Core materialization
private StoredFile(string key, string fileName, string contentType, long size, string? checksum, bool isPublic, DateTime uploadedAtUtc)
: base(key, fileName, contentType, size, checksum, isPublic, uploadedAtUtc) { }
public static StoredFile Create(string key, string fileName, string contentType, long size, string? checksum, bool isPublic, DateTime uploadedAtUtc) =>
new(key, fileName, contentType, size, checksum, isPublic, uploadedAtUtc);
}
// StoredFileMetadata : GMStoredFileMetadata<StoredFile, StoredFileMetadata>, IAggregateRoot — the same way.
In your app's Persistence:
public class StoredFileConfiguration : GMStoredFileConfiguration<StoredFile, StoredFileMetadata>
{
protected override string Schema => "file_storage"; // optional: map without the gm_ prefix
}
public class StoredFileMetadataConfiguration : GMStoredFileMetadataConfiguration<StoredFile, StoredFileMetadata>;
Then write an upload command that calls IFileStorageService.UploadAsync. It records
StoredFile.Create(...) plus one StoredFileMetadata.Create(...) per pair through your repositories
and unit of work. A delete command deletes the bytes and calls SoftRemove(). A list query filters
StoredFile with a specification on Metadata.
GM.FileStorage.Samples does exactly
this.
Do you need GM.DistributedLock here? (flagged, not assumed)
Core deliberately does not depend on GM.DistributedLock. For the common operations it isn't needed: object stores are last-write-wins per key, and unique keys (the default strategy) mean concurrent uploads don't collide.
A lock is worth it for one specific case: serializing writes to the same logical key —
e.g. "only one upload for kyc/{userId}/passport may be in flight," or a read-modify-write on a
file. That's an application-level concern, so rather than bake it into every consumer, wrap the
upload:
await using var handle = await locks.AcquireAsync($"file:{key}", TimeSpan.FromSeconds(30),
wait: TimeSpan.FromSeconds(5), retryInterval: TimeSpan.FromMilliseconds(100));
await storage.UploadAsync(request with { Key = key });
If this pattern turns out to be pervasive, a thin optional GM.FileStorage.DistributedLock
decorator (IFileStorageService → lock-per-key → inner service) could add it without touching core
or any provider. Recommendation: keep it out of core; add the decorator only if the need is real.
S3 and Azure providers
Both map the same IFileStorageService onto their SDK and register a keyed backend, so an app moves
from Local → S3 → AzureBlob by configuration alone — no code change.
S3 / MinIO (GM.FileStorage.S3)
builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMS3FileStorage(builder.Configuration); // FileStorage:S3
"FileStorage": {
"Provider": "S3",
"S3": {
"BucketName": "kyc-docs",
"Region": "eu-central-1",
// MinIO / S3-compatible instead of AWS:
"ServiceUrl": "http://localhost:9000", "ForcePathStyle": true,
"AccessKey": "…", "SecretKey": "…" // omit to use the default AWS credential chain
}
}
PutObject/GetObject streaming, GetPreSignedURL for presigned read/write, object metadata
(x-amz-meta-gm-* for filename/checksum/visibility), and CannedACL for Public/Private.
Azure Blob (GM.FileStorage.AzureBlob)
builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMAzureBlobFileStorage(builder.Configuration); // FileStorage:AzureBlob
"FileStorage": {
"Provider": "AzureBlob",
"AzureBlob": { "ConnectionString": "…", "ContainerName": "kyc" }
}
Block-blob streaming, SAS URLs via GenerateSasUri, and blob metadata. Note: Azure public access is
container-scoped, so per-blob Visibility is advisory — use the SAS URL for time-limited access.
Repository layout
GM.FileStorage/ # IFileStorageService, requests/results, key strategy, options, DI selector
GM.FileStorage.Local/ # disk provider (streaming + SHA-256 + sidecar metadata)
GM.FileStorage.S3/ # AWS S3 / MinIO provider
GM.FileStorage.AzureBlob/ # Azure Blob Storage provider
GM.FileStorage.Domain/ # stored-file domain: FileStorage bounded context, GMStoredFile + GMStoredFileMetadata
GM.FileStorage.Persistence/ # EF Core configurations + table names for the stored-file domain
tests/GM.FileStorage.Tests/ # xUnit tests
Building & testing
dotnet build -c Release
dotnet test -c Release
Releasing
Versioning is automated from Conventional Commits —
see CONTRIBUTING.md. All packages share one version (Directory.Build.props)
and publish together to nuget.org on each release.
License
MIT — see LICENSE.
| 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.Configuration.Abstractions (>= 10.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Options (>= 10.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.0)
NuGet packages (8)
Showing the top 5 NuGet packages that depend on GM.FileStorage:
| Package | Downloads |
|---|---|
|
GM.FileStorage.Local
Local disk file-storage provider for GM.FileStorage — streams files to a root directory with SHA-256 checksum validation and sidecar metadata. Ideal for development and tests. Register with AddGMLocalFileStorage() and select it via FileStorage:Provider = "Local". |
|
|
GM.FileStorage.S3
AWS S3 (and S3-compatible, e.g. MinIO) provider for GM.FileStorage: streaming Put/Get, presigned read/write URLs, object metadata, and canned-ACL visibility. Register with AddGMS3FileStorage() and select it via FileStorage:Provider = "S3". |
|
|
GM.FileStorage.AzureBlob
Azure Blob Storage provider for GM.FileStorage: streaming block-blob upload/download, SAS URLs, and blob metadata. Register with AddGMAzureBlobFileStorage() and select it via FileStorage:Provider = "AzureBlob". |
|
|
GM.FileStorage.Encryption
Encryption at rest for GM.FileStorage: every file is encrypted with its own AES-256-GCM key (streamed in authenticated chunks), wrapped by a master key from configuration — e.g. supplied by GM.Secrets. Works on every provider (local disk, S3, Azure Blob) and supports master-key rotation. Register with AddGMFileStorageEncryption(). |
|
|
GM.FileStorage.MalwareScanner
Malware scanning for GM.FileStorage, switched on by configuration (FileStorage:MalwareScanner:Enabled): every upload is scanned with ClamAV as it streams into storage (before encryption at rest), and an infected file is deleted and refused. Fails closed when ClamAV can't answer. IMalwareScanner scans anything else; includes a readiness check. Register with AddGMFileStorageMalwareScanner(). |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 6.0.0 | 216 | 11/9/2026 |
| 5.0.0 | 193 | 11/9/2026 |
| 4.4.0 | 193 | 11/8/2026 |
| 4.3.0 | 174 | 11/8/2026 |
| 4.2.0 | 164 | 11/8/2026 |
| 4.1.0 | 182 | 11/8/2026 |
| 4.0.0 | 179 | 11/8/2026 |
| 3.3.0 | 342 | 11/5/2026 |
| 3.2.0 | 174 | 11/4/2026 |
| 3.1.0 | 161 | 11/4/2026 |
| 3.0.0 | 162 | 11/4/2026 |
| 2.0.3 | 123 | 11/4/2026 |
| 2.0.2 | 142 | 11/3/2026 |
| 2.0.1 | 128 | 11/3/2026 |
| 2.0.0 | 148 | 11/3/2026 |
| 1.2.0 | 141 | 10/31/2026 |
| 1.1.1 | 194 | 8/31/2026 |
| 1.1.0 | 351 | 8/2/2026 |
| 1.0.0 | 153 | 8/2/2026 |