GM.FileStorage.AzureBlob
2.0.2
See the version list below for details.
dotnet add package GM.FileStorage.AzureBlob --version 2.0.2
NuGet\Install-Package GM.FileStorage.AzureBlob -Version 2.0.2
<PackageReference Include="GM.FileStorage.AzureBlob" Version="2.0.2" />
<PackageVersion Include="GM.FileStorage.AzureBlob" Version="2.0.2" />
<PackageReference Include="GM.FileStorage.AzureBlob" />
paket add GM.FileStorage.AzureBlob --version 2.0.2
#r "nuget: GM.FileStorage.AzureBlob, 2.0.2"
#:package GM.FileStorage.AzureBlob@2.0.2
#addin nuget:?package=GM.FileStorage.AzureBlob&version=2.0.2
#tool nuget:?package=GM.FileStorage.AzureBlob&version=2.0.2
<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.Encryption |
encryption at rest for any provider (AES-256-GCM, a key per file) | 🆕 new |
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<FileDownloadResult> DownloadAsync(string key, FileByteRange range, 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.
Key layout: a template, or your own strategy
Without configuration, keys are date-partitioned and collision-free (2026/08/02/{guid}.pdf). To lay
them out differently, set a key template. No code is needed:
"FileStorage": {
"KeyTemplate": "{category}/{shard}/{id}{ext}" // → documents/9f/9f1c…a3.pdf, images/4e/4e07…png
}
| Token | Becomes |
|---|---|
{id} |
a random 32-hex id; required, so keys never collide |
{ext} |
the file's extension, lower-case and cleaned (.pdf), or nothing |
{category} |
documents, images, videos, audio, archives or other, from the content type |
{shard} |
the id's first two characters: 256 folders, so none grows huge |
{date:format} |
the upload time (UTC), e.g. {date:yyyy/MM} |
{meta:name} |
an upload metadata value, e.g. {meta:tenantId} (_ when absent) |
- Categories come from the verified type. The key strategy gets the content type after the upload
rules have run (
FileKeyContext.ContentType). WithVerifyContentTypeon, a renamed executable can't land inimages/, and anapplication/octet-streamupload is placed by its detected type. - Upload values are cleaned. Metadata values and extensions are reduced to letters, digits,
-,_and., with no..and no leading dot, so they can't add folders, climb out of the storage root or break a URL. - The template is checked at startup. An unknown token, a missing
{id}, unbalanced braces, or an absolute or..path fails at startup, not at the first upload.FileKeyTemplate.Parse(...)andFileCategories.Of(...)are public if you want them in your own code.
For anything a template can't express, implement IFileKeyStrategy:
public sealed class TenantKeyStrategy : IFileKeyStrategy
{
public string GenerateKey(FileKeyContext ctx) =>
$"tenants/{ctx.Metadata["tenantId"]}/{FileCategories.Of(ctx.ContentType)}/{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.
Upload rules: size, allowed types, real content
Set them once in FileStorage and they apply to every provider. All three are off by default.
"FileStorage": {
"MaxFileSize": 10485760, // bytes (10 MB); larger → FileTooLargeException
"AllowedContentTypes": [ "application/pdf", "image/*" ], // anything else → FileContentTypeNotAllowedException
"VerifyContentType": true // check the bytes, not just the claimed type
}
VerifyContentTypereads the upload's first bytes and checks them against the declared type withFileTypeDetector. It knows PDF, the common image, audio and video formats (including HEIC and MOV), ZIP-based Office documents, legacy Office, archives and executables.- Mismatch: an
.exedeclared asimage/pngthrowsFileContentTypeMismatchException. - Generic type: an upload declared as
application/octet-streamtakes the detected type. - No signature: text formats (plain text, CSV, JSON, SVG) can't be verified and pass as declared.
- Mismatch: an
- Nothing is kept from a rejected upload.
- The type check runs before the provider reads anything.
- An oversize stream fails as the provider reads it: S3 and Azure spool before sending, and the Local provider deletes its partial file.
- Request bodies that can't seek are handled: the sniffed header is replayed.
- Detection on its own:
FileTypeDetector.Detect(bytes)andFileTypeDetector.Matches(type, bytes)are public.
Ranged downloads (seek in video, resume downloads)
await using var part = await storage.DownloadAsync(key, new FileByteRange(offset: 1_000_000, length: 65_536));
// part.Content: just those bytes · part.Range: the slice served (clamped to the file)
// part.Metadata.Size: the whole file's size · part.Range.Value.ToContentRange(size): "bytes 1000000-1065535/5242880"
- Built-in providers fetch only the requested bytes: S3
ByteRange, AzureHttpRange, and a seek on Local. - Other
IFileStorageServiceimplementations get a default that reads from the start and skips ahead. - Out-of-range starts: a range starting at or past the end throws
FileRangeNotSatisfiableException, which carries the file'sSizefor an HTTP 416Content-Range: bytes */size.
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,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.- A file's content never changes after it's created: new content is a new file.
StorageKeyis where the bytes live. It defaults toKey; pass your own (e.g. a path from the key template,documents/9f/9f1c….pdf) to keep the stored layout separate from the key callers use.- A constructor takes the id too. Pass
id.ToString()as the key to give callers a single GUID per file, while the bytes sit under a readable folder path. - 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.
Encryption at rest (GM.FileStorage.Encryption)
Every file is encrypted before it reaches the provider, so local disk, S3 and Azure only ever hold ciphertext. Your code doesn't change:
UploadAsyncandDownloadAsynctake and return plaintext.- Sizes and checksums are the plaintext's.
- Ranged downloads still work.
builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMS3FileStorage(builder.Configuration);
builder.Services.AddGMFileStorageEncryption(builder.Configuration); // FileStorage:Encryption
// From secrets (GM.Secrets: appsecrets.json, SECRETS_PROVIDER, environment), never a committed file.
"FileStorage": {
"Encryption": {
"ActiveKeyId": "2026-11",
"Keys": {
"2026-11": "<base64 of 32 random bytes>", // wraps new uploads
"2025-06": "<retired key>" // still needed to read files it wrapped
}
}
}
Generate a key with openssl rand -base64 32, or Convert.ToBase64String(RandomNumberGenerator.GetBytes(32)).
How a file is protected (envelope encryption)
- A key per file. Each upload gets a random 256-bit key, and its content is encrypted with AES-256-GCM in 64 KiB chunks. Only one chunk is ever held in memory.
- The master key wraps the file key. The file key is stored, encrypted by the master key (AES-256-GCM), in a small header at the start of the object, together with the master key's id. The object is therefore self-contained and needs no database.
- Tampering is detected. Every chunk is authenticated, and its nonce includes the chunk's index
and a last-chunk flag (the STREAM construction). An altered, reordered or truncated file throws
FileDecryptionExceptioninstead of returning garbage. - Ranges stay cheap. A ranged download reads the header, then only the chunks that cover the range.
Operating it
- Rotating the master key: add a new key, make it
ActiveKeyId, and keep the old one inKeys. New uploads use the new key and old files keep decrypting. Remove an old key only once no file uses it. - Switching encryption on for existing data: files stored before then (with no encryption marker) are served as stored. New uploads are encrypted.
- Switching it off explicitly: set
FileStorage:Encryption:Enabledtofalse. For example, keepfalsein a committed appsettings.json and settruetogether with the keys in secrets. It's on by default, so registering encryption without keys fails as soon as storage is first used, instead of silently storing plaintext. - Presigned URLs throw
NotSupportedException: a read link would hand out ciphertext, and a write link would bypass encryption. Stream files through your API instead. - Upload rules (
MaxFileSize,VerifyContentType, …) see the plaintext, because encryption sits closest to the provider. - Other key stores: to keep master keys in a KMS or HSM, implement
IFileEncryptionKeyProvider. - Keyed providers resolved directly bypass encryption, like the upload rules. Always go through
IFileStorageService.
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.Encryption/ # encryption at rest: per-file AES-256-GCM keys wrapped by master keys
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
- Azure.Storage.Blobs (>= 12.29.1)
- GM.FileStorage (>= 2.0.2)
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 |
|---|---|---|
| 6.0.0 | 139 | 11/9/2026 |
| 5.0.0 | 107 | 11/9/2026 |
| 4.4.0 | 123 | 11/8/2026 |
| 4.3.0 | 104 | 11/8/2026 |
| 4.2.0 | 104 | 11/8/2026 |
| 4.1.0 | 118 | 11/8/2026 |
| 4.0.0 | 126 | 11/8/2026 |
| 3.3.0 | 198 | 11/5/2026 |
| 3.2.0 | 111 | 11/4/2026 |
| 3.1.0 | 102 | 11/4/2026 |
| 3.0.0 | 117 | 11/4/2026 |
| 2.0.3 | 89 | 11/4/2026 |
| 2.0.2 | 97 | 11/3/2026 |
| 2.0.1 | 90 | 11/3/2026 |
| 2.0.0 | 109 | 11/3/2026 |
| 1.2.0 | 118 | 10/31/2026 |
| 1.1.1 | 154 | 8/31/2026 |
| 1.1.0 | 144 | 8/2/2026 |