SoftwareDriven.Persistence 3.2.0

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

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>>();

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);

Provider Packages

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.

Models

Inherit from PersistenceModelBase or implement IPersistenceModel:

public class MyModel : PersistenceModelBase
{
    public string Title { get; set; } = "";
    public bool IsActive { get; set; }
}

License

MIT