Sa.HybridFileStorage.FileSystem
0.20.0
dotnet add package Sa.HybridFileStorage.FileSystem --version 0.20.0
NuGet\Install-Package Sa.HybridFileStorage.FileSystem -Version 0.20.0
<PackageReference Include="Sa.HybridFileStorage.FileSystem" Version="0.20.0" />
<PackageVersion Include="Sa.HybridFileStorage.FileSystem" Version="0.20.0" />
<PackageReference Include="Sa.HybridFileStorage.FileSystem" />
paket add Sa.HybridFileStorage.FileSystem --version 0.20.0
#r "nuget: Sa.HybridFileStorage.FileSystem, 0.20.0"
#:package Sa.HybridFileStorage.FileSystem@0.20.0
#addin nuget:?package=Sa.HybridFileStorage.FileSystem&version=0.20.0
#tool nuget:?package=Sa.HybridFileStorage.FileSystem&version=0.20.0
Sa.HybridFileStorage.FileSystem
English | Русский
Local filesystem provider for Sa.HybridFileStorage. Stores files as physical files on disk, delegating every read, write and delete to a Sa.Data.TempFolder instance that owns the root, the path guard, the cleanup activity and the retry policy.
Table of Contents
- Overview
- File ID Format
- Installation
- Quick Start
- CRUD Examples
- Options Reference
- Security
- Error Handling
- Migrating from
BasePath
Overview
The filesystem provider registers an IFileStorage backed by the local file system. Files are stored under the root of a keyed Sa.Data.TempFolder instance using the structure:
{RootPath}/{Basket}/{TenantId}/{FileName}
The storage itself only maps a File ID to that relative path and shapes the result. The root, the path guard, the cleanup activity marker and the transient-I/O retries are the temp folder's — the provider no longer opens FileStreams or calls File.Delete directly.
Key characteristics:
- Path guarding — every path is resolved against the temp-folder root; traversal and injection-style characters are rejected
- Cleanup lifetime — files live under a temp-folder instance with an age-based cleanup (30 days by default; see below)
- Preallocated writes — the temp folder preallocates the target file when the source length is known
- Retries — transient
IOException/UnauthorizedAccessExceptionfailures are retried by the temp folder
File ID Format
fs://{basket}/{tenantId}/{fileName}
Examples:
fs://documents/42/report.pdffs://uploads/7/avatar.pngfs://share/100/data.binfs://share/7/sub/dir/file.txt— a nestedFileNamekeeps its directories
Note: leading separators in
FileNameare stripped, backslashes are treated as separators, and a File ID always uses/— nested names read the same on every OS. On disk the layout mirrors the ID ({RootPath}/{basket}/{tenantId}/{fileName}).
Installation
dotnet add package Sa.HybridFileStorage.FileSystem
Quick Start
The provider is registered by name, because its root and I/O policy live on a temp folder registered under the same name. The callback receives the IFileSystemStorageBuilder: the options section comes from FromConfiguration("…"), the standard Configure / PostConfigure / Validate methods are reached through Options(...), and the mandatory root/I-O channel is TempFolder(...):
using Sa.HybridFileStorage.FileSystem;
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.Options(ob => ob.Configure(options => options.Basket = "documents"))
.TempFolder(tb => tb.Options(ob => ob.Configure(folder =>
{
folder.RootPath = @"C:\data\files";
}))));
A storage without the TempFolder(...) channel throws InvalidOperationException at the
AddSaFileSystemFileStorage call — a filesystem storage with no root has nowhere to put a file.
The storage options pipeline runs in a fixed order — Configure → PostConfigure → validate — so a value normalised in post-initialisation is what validation sees.
Pre-initialisation (Configure)
Configure runs first and receives the raw values:
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.Options(ob => ob.Configure(options => options.Basket = "documents"))
.TempFolder(tb => tb.Options(ob => ob.Configure(folder => folder.RootPath = @"C:\data\files"))));
Post-initialisation (PostConfigure)
PostConfigure runs after every Configure and before validation. The registration already trims StorageType / Basket; anything you add here runs after that, so it sees normalised values:
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.Options(ob => ob.Configure(options => options.Basket = "documents")
.PostConfigure(options => options.IsReadOnly = false))
.TempFolder(tb => tb.Options(ob => ob.Configure(folder => folder.RootPath = @"C:\data\files"))));
From configuration
Pass the sections via FromConfiguration; the storage options and the temp-folder options bind from IConfiguration:
// appsettings.json
// {
// "FileSystemStorage": { "Basket": "documents" },
// "TempFolder": { "RootPath": "C:\\data\\files", "MaxAge": "30.00:00:00" }
// }
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.FromConfiguration("FileSystemStorage")
.TempFolder(tb => tb.FromConfiguration("TempFolder")));
The section binds in a fixed slot before the Options(...) actions replay, so their Configure has the last word when both are used.
Several storages in one host
Each call registers one storage under its own name; different names are independent, so one host can
run several filesystem roots. Repeating a name throws InvalidOperationException — the name keys the
storage, its named options instance and its temp folder:
var documents = sp.GetRequiredKeyedService<IFileStorage>("documents");
var uploads = sp.GetRequiredKeyedService<IFileStorage>("uploads");
The unkeyed IFileStorage registration stays as an alias of the last registered storage, so
sp.GetRequiredService<IFileStorage>() keeps working for the single-storage case (and for
IHybridFileStorage, which enumerates the unkeyed registrations only).
A blank or missing RootPath, or one pointing at the system temp directory, surfaces as
OptionsValidationException — at host start (ValidateOnStart()) or at first resolve in a container
built by hand — rather than on the first upload.
CRUD Examples
storage below is the registered IFileStorage; hybridStorage is IHybridFileStorage from the
core package.
var storage = sp.GetRequiredService<IFileStorage>();
// several storages in one host: sp.GetRequiredKeyedService<IFileStorage>("documents")
Upload from Stream
using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Hello, world!"));
var result = await storage.UploadAsync(
new UploadFileInput { FileName = "hello.txt", TenantId = 1 },
stream, ct);
// File created at: {RootPath}/documents/1/hello.txt
// File ID: fs://documents/1/hello.txt
Upload from File
Use CopyFromFileAsync from Sa.HybridFileStorage core:
var result = await hybridStorage.CopyFromFileAsync(
filePath: @"C:\temp\large-video.mp4",
basket: "media",
input: new UploadFileInput { FileName = "video.mp4", TenantId = 5 },
bufferSize: 1024 * 1024, // 1 MB buffer for large files
ct: ct);
Download to Memory
byte[]? downloaded = default;
await storage.DownloadAsync(result.FileId, async (stream, token) =>
{
downloaded = await stream.ReadAllBytesAsync(token);
}, ct);
Download to Disk
using var destination = new FileStream(@"C:\output\downloaded.pdf", FileMode.Create);
await storage.DownloadAsync(result.FileId, async (source, token) =>
await source.CopyToAsync(destination, 81920, token),
ct);
Delete
var deleted = await storage.DeleteAsync(result.FileId, ct);
// true — a file existed and was removed
// false — no file there, or a transient failure survived the temp folder's retries
Get Metadata
var metadata = await storage.GetMetadataAsync(result.FileId, ct);
if (metadata != null)
{
Console.WriteLine($"Basket: {metadata.Basket}");
Console.WriteLine($"Tenant: {metadata.TenantId}");
Console.WriteLine($"Name: {metadata.FileName}");
Console.WriteLine($"Type: {metadata.StorageType}");
}
GetMetadataAsync parses and shapes the File ID, like the S3 and Postgres providers: it answers for
any well-formed ID this storage owns without probing the disk (only the in-memory provider checks
that the entry exists). DownloadAsync / DeleteAsync are the calls that report a missing file, and
Basket in the result is always the configured basket.
Options Reference
FileSystemStorageOptions
One mutable type, served by the options pipeline. Every property is bindable and settable, and the
same instance is what the storage is constructed from — there is no second settings type and no
copy step that could drop a property. The storage root and the file-I/O policy now live on
TempFolderOptions, reached through the mandatory TempFolder(...) channel.
| Property | Description | Default |
|---|---|---|
Basket |
Container name appended to the root | "share" |
StorageType |
Scheme prefix in File ID | "fs" |
IsReadOnly |
Prevent write/delete operations | false |
FileSystemStorageOptions.DefaultStorageType and FileSystemStorageOptions.DefaultBasket are
exposed as constants. The defaults live on the type itself, so binding a partial configuration
leaves the rest intact.
TempFolderOptions (the storage root)
The TempFolder(...) channel configures the keyed ITempFolder the storage reads and writes
through. The properties that matter to a filesystem storage:
| Property | Description | Default |
|---|---|---|
RootPath |
Root directory of the storage; must not be blank or the system temp directory itself (a subdirectory of it is accepted but the OS may wipe it) | Path.GetTempPath() (rejected) |
MaxAge |
Age after which the cleanup strategy removes an expired subfolder | 30 days (storage default) |
CleanupEnabled |
Whether the storage's temp folder deletes expired subfolders at all | true |
OverwriteFiles |
Whether an existing file is replaced on write | true |
ReadOnly |
Rejects every mutation in the temp folder. Independent of FileSystemStorageOptions.IsReadOnly — see below |
false |
TouchDebounce |
Debounce before a write refreshes the folder's activity marker | 5 seconds |
FileSystemStorageOptions.IsReadOnly and TempFolderOptions.ReadOnly are two switches for one
intent: the storage reports IsReadOnly to HybridFileStorage (which skips it when choosing a
target for a write), while the temp folder enforces it on the disk. Set both when a storage must
not change — with only the storage flag set, HybridFileStorage skips the storage but its files are
still cleaned up by age; with only the temp-folder flag set, the hybrid chain still picks the
storage for a write and the write then fails with InvalidOperationException.
Sa.HybridFileStorage.FileSystem raises a storage's MaxAge from the temp-folder default of 24
hours to 30 days, because storage files are meant to outlive a scratch folder. A section value
or a code Configure that sets MaxAge still wins.
CleanupEnabled = false (through the same TempFolder(...) channel) turns the deletion off: the
storage keeps working, but nothing is ever cleaned up — use it when the files' lifetime is managed
elsewhere. The volume tracking and the free-space check keep running: they only report.
Validation runs after post-configuration and enforces:
| Requirement | Applies to |
|---|---|
StorageType at most 10 characters, no :, / or \ |
StorageType |
Basket 3-63 characters, starts with a letter or _, no path separator |
Basket |
RootPath set and not the system temp directory itself |
TempFolderOptions |
Adding your own validation
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.Options(ob => ob.Configure(options => options.Basket = "documents")
.Validate(options => options.StorageType == "fs", "Only the 'fs' scheme is supported."))
.TempFolder(tb => tb.Options(ob => ob.Configure(folder => folder.RootPath = @"C:\data\files"))));
Your rule runs in addition to the built-in checks; all failures are reported together in the
resulting OptionsValidationException.
Security
The provider protects against directory traversal and injection attacks through the temp folder's path guard:
- Path sanitisation — leading
/or\characters inFileNameare stripped; separators are normalised, so a nested name is a set of directories under the tenant - Root containment — every resolved file path must land inside
{RootPath}/{Basket}(a sibling basket that only shares the name prefix does not belong to this storage). Attempts to escape via..are rejected withSecurityException - Injection rejection —
~, shell/glob metacharacters (< > | & ;$ ^ * ? " ' %), control and invisible Unicode characters are rejected withSecurityException` - Portable names — reserved Windows device names (
CON,PRN,AUX,NUL,CONIN$,CONOUT$,COM0–COM9,LPT0–LPT9, with or without an extension) and segments ending with a dot are rejected withSecurityException, on every platform: Windows would resolve the former to a device and alias the latter to another file, soreport.txt.would silently share a file withreport.txt - Deterministic paths — File IDs map to relative paths without resolution, preventing symlink-based attacks
// Safe — leading separators are dropped, the directories below them are kept
new UploadFileInput { FileName = "/api/files/var/www/report.pdf" }
// Creates: {RootPath}/documents/1/api/files/var/www/report.pdf
// File ID: fs://documents/1/api/files/var/www/report.pdf
// Blocked — directory traversal detected
// fileName = "../../../etc/passwd" → throws SecurityException
// Blocked — injection-style character (query-string percent)
// fileName = "file%name.txt" → throws SecurityException
Error Handling
| Scenario | Behavior |
|---|---|
IsReadOnly = true + upload/delete |
Throws HybridFileStorageWritableException |
TempFolderOptions.ReadOnly = true + upload/delete |
Throws InvalidOperationException (the temp folder owns the switch; set FileSystemStorageOptions.IsReadOnly too so the hybrid chain skips this storage) |
| File not found during download/delete | Returns false (no exception) |
| Path points at a directory during download/delete | Throws InvalidOperationException |
IOException / UnauthorizedAccessException on delete |
Retried by the temp folder; returns false if all retries fail |
| Permission failure on upload | Throws UnauthorizedAccessException from the temp folder (not retried away) |
| Path escape or injection attempt | Throws SecurityException |
Reserved device name (NUL, COM1, …) or a segment ending with a dot |
Throws SecurityException |
| Malformed or foreign File ID | CanProcess returns false; download/delete return false, GetMetadataAsync returns null |
| Invalid options | Throws OptionsValidationException at host start (ValidateOnStart) or on first resolve |
Migrating from BasePath
FileSystemStorageOptions.BasePath was removed: the root now lives on the temp folder behind the
mandatory TempFolder(...) channel. To keep existing File IDs valid, point the new root at the old
value:
// Before
builder.Services.AddSaFileSystemFileStorage(o => o.Options(ob => ob.Configure(x =>
{
x.BasePath = @"C:\data\files";
x.Basket = "documents";
})));
// After
builder.Services.AddSaFileSystemFileStorage("documents", b => b
.Options(ob => ob.Configure(x => x.Basket = "documents"))
.TempFolder(tb => tb.Options(ob => ob.Configure(folder =>
folder.RootPath = @"C:\data\files"))));
FileSystemStorageOptions.BufferSize was also removed — the temp folder owns the copy buffer
(81920 bytes). The registration is now named-only: every existing
AddSaFileSystemFileStorage(configure) call needs a name and a TempFolder(...) channel.
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.Logging.Abstractions (>= 10.0.14)
- Microsoft.Extensions.Options (>= 10.0.14)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.14)
- Sa.Data.TempFolder (>= 0.20.0)
- Sa.HybridFileStorage (>= 0.20.0)
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 |
|---|---|---|
| 0.20.0 | 64 | 11/13/2026 |
| 0.18.0 | 100 | 11/3/2026 |
| 0.17.0 | 97 | 10/29/2026 |
| 0.16.0 | 109 | 10/14/2026 |
| 0.15.0 | 103 | 10/2/2026 |
| 0.12.0 | 135 | 7/28/2026 |
| 0.11.0 | 124 | 7/14/2026 |
| 0.10.0 | 126 | 7/2/2026 |
| 0.9.1 | 140 | 5/8/2026 |
| 0.9.0 | 123 | 4/29/2026 |
| 0.8.3 | 139 | 3/11/2026 |
| 0.8.2 | 132 | 3/10/2026 |
| 0.8.1 | 126 | 3/6/2026 |
| 0.8.0 | 136 | 2/10/2026 |
| 0.7.0 | 135 | 1/27/2026 |
| 0.6.0 | 137 | 1/15/2026 |
| 0.5.0 | 137 | 12/29/2025 |
| 0.4.0 | 310 | 12/17/2025 |
| 0.3.0 | 179 | 10/17/2025 |
| 0.1.0 | 236 | 9/1/2025 |