SoftwareDriven.Persistence
3.4.1
dotnet add package SoftwareDriven.Persistence --version 3.4.1
NuGet\Install-Package SoftwareDriven.Persistence -Version 3.4.1
<PackageReference Include="SoftwareDriven.Persistence" Version="3.4.1" />
<PackageVersion Include="SoftwareDriven.Persistence" Version="3.4.1" />
<PackageReference Include="SoftwareDriven.Persistence" />
paket add SoftwareDriven.Persistence --version 3.4.1
#r "nuget: SoftwareDriven.Persistence, 3.4.1"
#:package SoftwareDriven.Persistence@3.4.1
#addin nuget:?package=SoftwareDriven.Persistence&version=3.4.1
#tool nuget:?package=SoftwareDriven.Persistence&version=3.4.1
SoftwareDriven.Persistence
A .NET persistence abstraction library providing a unified interface for different data storage backends. Targets net10.0.
Installation
dotnet add package SoftwareDriven.Persistence
Core Interfaces
| Interface | Purpose |
|---|---|
IPersistenceModel |
Base model interface requiring string? Id |
IBasicPersistenceProvider<T> |
CRUD operations, expression-based querying, pagination |
IPersistenceProvider<T> |
Extended: nested collection projections, element match, file storage |
IConditionalPersistenceProvider<T> |
Conditional writes of models carrying a revision (IRevisioned) |
IBlobProvider |
Streamed file access, ranges, metadata and listing |
IDatabaseManager |
Provider factory and table name registry |
Built-in: FileSystem Provider
The core package includes a JSON file-based provider for simple scenarios.
services.AddSingleton(new JsonSerializerOptions());
services.AddSingleton<FileSystemManager>();
services.AddSingleton<FileSystemDataProvider<MyModel>>();
Every change reads, modifies and writes the collection file as one step; all instances of the process working on the same file share its locks. Other processes are not coordinated with.
Conditional Writes
Models implementing IRevisioned (long Revision) can be written conditionally by providers implementing
IConditionalPersistenceProvider<T> (FileSystem, MongoDb, SQLite documents):
var conditional = (IConditionalPersistenceProvider<Session>)provider;
await conditional.TryInsert(session); // Written, or Conflict if the ID exists; Revision = 1
var stored = await provider.FindById(id);
stored.State = "changed";
var outcome = await conditional.TryReplace(stored, stored.Revision);
if (outcome == WriteOutcome.Conflict)
{
// Changed by someone else in the meantime: read again and retry.
}
TryReplace sets the revision of the entry to the expected revision + 1. MongoDB checks the condition on the server,
so it holds across processes and nodes; the file system provider checks it within the process.
File Storage
Providers implementing IPersistenceProvider<T> also store binary files via IFileProvider
(StoreFile, LoadFile, DeleteFile, FileExists). The backend used for those files is independent
of the backend storing the models and is chosen by registering an IFileProviderFactory:
// Local file system (default for FileSystem and MongoDb)
services.AddLocalFileStorage();
// S3 bucket instead - the models stay in MongoDB, the files go to S3
services.AddS3("Files");
services.AddS3FileStorage(managerKey: "Files");
A factory registered under the service key of a persistence provider takes precedence over an unkeyed
registration. Without any registration each provider keeps its own default: the local file system for
FileSystemDataProvider and MongoDbRepositoryProvider, the bucket for S3RepositoryProvider and the
database for IndexedDbRepositoryProvider.
The implementation can also be exchanged per instance at runtime:
provider.FileProvider = new S3FileProvider(s3Manager, logger);
| Implementation | Package | Storage |
|---|---|---|
LocalFileProvider |
Core | {BasePath}/{FileFolder}/{fileId} in the local file system |
S3FileProvider |
S3 | {BasePath}/files/{FileFolder}/{fileId} in the bucket |
IndexedDbFileProvider |
IndexedDb | the _files_{FileFolder} object store |
Streamed access
IBlobProvider extends IFileProvider by streams, byte ranges, metadata and listing. LocalFileProvider and
S3FileProvider implement it; AsBlobProvider() gets it from any file provider, buffering the files of providers
with byte access only (listing is not supported then):
var blobs = provider.FileProvider.AsBlobProvider();
await blobs.Store(hash, requestBody, "image/png");
await using var stream = await blobs.OpenRead(hash, offset: 1024, length: 4096);
var info = await blobs.GetInfo(hash); // Length, ContentType, LastModified
await foreach (var id in blobs.List(prefix: "items/")) { }
LocalFileProvider writes a temporary file and moves it into place, so readers never see a partly written file,
and rejects file IDs leading out of its folder.
Provider Packages
| Package | Backend |
|---|---|
| SoftwareDriven.Persistence.MongoDb | MongoDB |
| SoftwareDriven.Persistence.Cassandra | Apache Cassandra |
| SoftwareDriven.Persistence.SQLite | SQLite, models as JSON documents |
| SoftwareDriven.Persistence.EF.SQLite | Entity Framework Core / SQLite |
| SoftwareDriven.Persistence.IndexedDb | Browser IndexedDB (Blazor) |
Usage
All providers implement the same interfaces, allowing backend-agnostic code:
public class MyService
{
private readonly IBasicPersistenceProvider<MyModel> provider;
public MyService(IBasicPersistenceProvider<MyModel> provider)
{
this.provider = provider;
}
public async Task Example()
{
// Create
await provider.CreateOrUpdate(new MyModel { Title = "Hello" });
// Query with expressions
var results = await provider.FindByExpression(x => x.Title == "Hello");
// Paginate
var page = await provider.GetAll(new PaginationOptions<MyModel>
{
PageSize = 10,
PageNumber = 0
});
}
}
Maintenance
Deleting entries does not necessarily return their storage to the file system. IDatabaseManager therefore offers
maintenance on the database as a whole, independent of a single entity:
if (!databaseManager.SupportsMaintenance)
return;
var statistics = await databaseManager.GetStatistics();
// statistics.TotalBytes - what the database occupies
// statistics.ReclaimableBytes - occupied without being used
// statistics.IsAvailable - whether the figures could be determined
var result = await databaseManager.Compact();
// result.Success, result.BytesBefore, result.BytesAfter, result.Error
Query SupportsMaintenance instead of switching on DatabaseType. Backends without a maintenance concept report
false, unavailable statistics and a CompactResult with Success = false and an explanatory Error.
| Backend | SupportsMaintenance |
Operation |
|---|---|---|
| EF.SQLite | true | VACUUM plus PRAGMA wal_checkpoint(TRUNCATE) |
| MongoDb | true (when connected) | compact per collection, figures from dbStats |
| Cassandra | false | compaction is a matter of the server and nodetool |
| FileSystem | false | deleted entries vanish with their file |
| IndexedDb | false | the browser manages the storage itself |
Migrations
var result = await new MigrationManager(serviceProvider)
.UseDatabase<MongoDbManager>("_migrations")
.UseAssembly(Assembly.GetExecutingAssembly())
.Run(); // or Run(targetVersion), also downwards
Migrations implement IMigration (version, name, database type, Up, Down). The applied migrations are kept in
the status table; a run stops at the first migration that fails.
If the backend supports conditional writes and a provider of MigrationLease is registered (AddFileSystem and
AddMongoDb and AddSQLiteDocuments do so), a run holds a lock in the table {status table}_lock: concurrent processes migrating the same
database wait for each other, and the lease of a process that died expires. WithLock(timeout, leaseTime) changes the
times (default 10 minutes and 1 minute), WithoutLock() switches the lock off.
Models
Inherit from PersistenceModelBase or implement IPersistenceModel:
public class MyModel : PersistenceModelBase
{
public string Title { get; set; } = "";
public bool IsActive { get; set; }
}
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.Logging.Abstractions (>= 10.0.13)
NuGet packages (6)
Showing the top 5 NuGet packages that depend on SoftwareDriven.Persistence:
| Package | Downloads |
|---|---|
|
SoftwareDriven.Persistence.MongoDb
SoftwareDriven.Persistence.MongoDb is a library with a persistence layer for MongoDb building on top of SoftwareDriven.Persistence. |
|
|
SoftwareDriven.Persistence.Cassandra
SoftwareDriven.Persistence.Cassandra is a library with a persistence layer for Apache Cassandra building on top of SoftwareDriven.Persistence. Includes DataStax C# Driver for Apache Cassandra v3.19.1 with modifications. |
|
|
SoftwareDriven.Persistence.EF.SQLite
SoftwareDriven.Persistence.EF.SQLite is a library with a persistence layer for EntityFramework SQLite building on top of SoftwareDriven.Persistence. |
|
|
SoftwareDriven.Persistence.IndexedDb
SoftwareDriven.Persistence.IndexedDb is a library with a persistence layer for browser IndexedDB building on top of SoftwareDriven.Persistence. |
|
|
SoftwareDriven.Persistence.S3
SoftwareDriven.Persistence.S3 is a library with a persistence layer for S3-compatible object storage building on top of SoftwareDriven.Persistence. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.4.1 | 104 | 11/11/2026 |
| 3.3.1 | 288 | 9/30/2026 |
| 3.3.0 | 234 | 9/24/2026 |
| 3.2.0 | 176 | 9/8/2026 |
| 3.1.0 | 160 | 8/25/2026 |
| 3.0.5 | 921 | 4/2/2026 |
| 3.0.4 | 273 | 2/12/2026 |
| 3.0.3 | 527 | 2/11/2026 |
| 3.0.2 | 164 | 2/11/2026 |
| 3.0.1 | 175 | 2/11/2026 |
| 3.0.0 | 259 | 2/1/2026 |
| 2.12.0 | 259 | 1/8/2026 |
| 2.9.1 | 554 | 4/24/2025 |
| 2.9.0 | 990 | 11/30/2024 |
| 2.8.2 | 322 | 11/18/2024 |
| 2.8.1 | 687 | 7/19/2024 |
| 2.8.0 | 472 | 7/7/2024 |
| 2.7.3 | 272 | 11/18/2024 |
| 2.7.2 | 304 | 6/30/2024 |