Net.Persistence 3.0.0

Net.Persistence nuget

Easy way to store objects using SQLite under the hood. Provides a lightweight file-based persistence layer with a minimal DI-friendly API.

Installation

dotnet add package Net.Persistence

Registering services (dependency injection)

The library exposes an extension method UsePersistence<T> that will add an IDbContext pointing at a file, register a Store<T> singleton and the two helper wrappers StorableCollection<T> and StorableSingle<T>.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices(services => services
            .UsePersistence<ExampleStorableObject>("databaseName.db")
            .AddHostedService<HostedCollectionTest>());

Note: UsePersistence<T> can be called multiple times with different types or database names if you need more than one store. Under the hood it creates a new DatabaseContext per call.

If you prefer to register the pieces manually (or implement a custom IPersistence<T>), the equivalent code is:

services
    .AddTransient<IDbContext>(sp => new DatabaseContext("databaseName.db"))
    .AddSingleton<Store<ExampleObject>>()               // low-level store
    .AddTransient<StorableCollection<ExampleObject>>() // collection wrapper
    .AddTransient<StorableSingle<ExampleObject>>();    // single-value wrapper

// optionally register your own persistence implementation
services.AddSingleton<IPersistence<ExampleObject>,
                         ExampleSaveAndGetImplementation>();

Defining a storable type

All objects persisted by the library must inherit from Storable. You can also decorate properties with [StoreIgnore] so they are skipped.

using Net.Persistence.Models;
using Net.Persistence.Attributes;

class ExampleObject : Storable
{
    public string Name { get; set; }
    public bool SomeAwesomeProperty { get; set; }

    [StoreIgnore]
    public string IgnoredProperty { get; set; }
}

Working with a collection

StorableCollection<T> wraps a Store<T> and exposes convenient methods and properties for typical collection operations:

public class HostedCollectionTest : IHostedService
{
    private readonly ILogger<HostedCollectionTest> _logger;
    private readonly StorableCollection<ExampleObject> _store;

    public HostedCollectionTest(ILogger<HostedCollectionTest> logger,
                                 StorableCollection<ExampleObject> store)
    {
        _logger = logger;
        _store = store;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        // clear everything
        _store.Clear();

        // add an item
        var item = _store.Add(new ExampleObject { Name = "foo" });

        // check membership
        if (_store.Contains(item))
        {
            _logger.LogInformation("item stored successfully");
        }

        // query
        var found = _store.Find(x => x.Name.StartsWith("f"));
        var all   = _store.Get;

        // remove
        _store.Remove(item);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;
}

The collection supports:

• Get � all elements
• Add � save a new object
• Remove � delete by instance
• Clear � wipe the database
• Contains � by instance or predicate
• Find / GetValue � query using a predicate

Working with a single value

StorableSingle<T> is handy when you only need to persist one record. It stores the first (and only) item in the underlying table.

var single = serviceProvider.GetRequiredService<StorableSingle<ExampleObject>>();

// set or overwrite the value
single.Set(new ExampleObject { Name = "singleton" });

if (single.IsSet)
{
    var current = single.Get;
}

if (single.TryGet(out var value))
{
    // use value
}

single.Delete(value);

Methods and properties include: IsSet, Get, Set, Delete, and TryGet.

Low-level persistence interface

For more control you can implement IPersistence<T> yourself using a DatabaseContext subclass. The example project contains a simple PersistenceImplementation showing how to register, update and query objects.

The previously shown StorableCollection and StorableSingle are just convenience wrappers around Store<T>, which is itself the core API:

var registered = _persistence.Register(example);
registered.Name = "modified";
_persistence.Update(registered);
var allObjects = _persistence.GetAll();