EngineBay.Persistence 6.0.4

There is a newer version of this package available.
See the version list below for details.
dotnet add package EngineBay.Persistence --version 6.0.4                
NuGet\Install-Package EngineBay.Persistence -Version 6.0.4                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="EngineBay.Persistence" Version="6.0.4" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add EngineBay.Persistence --version 6.0.4                
#r "nuget: EngineBay.Persistence, 6.0.4"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install EngineBay.Persistence as a Cake Addin
#addin nuget:?package=EngineBay.Persistence&version=6.0.4

// Install EngineBay.Persistence as a Cake Tool
#tool nuget:?package=EngineBay.Persistence&version=6.0.4                

EngineBay.Persistence

NuGet version Maintainability Test Coverage

Persistence module for EngineBay published to EngineBay.Persistence on NuGet.

About

The persistence module provides structures to configure and register any database connections that modules in your application might need.

The DbContexts from this module should be inherited by the DbContexts of any module that needs to use a database. To support Command and Query Responsibility Segregation (CQRS), a read-optimised and a write-optimised DbContext are provided - though a general-purpose one is also provided.

The TimestampInterceptor will add creation and modification timestamps to any model that implements EngineBay.Core's BaseModel.

The AuditableModel abstract class will provide some standard fields for tracking which users make changes to any inheriting models. If changes are saved on a DbContext that uses EngineBay.Auditing's AuditInterceptor, then audit entries will automatically be created for any models that implement AuditableModel.

ApplicationUser is a simple representation of a user for the application. It has a DbSet provided in ModuleDbContext so that any module inheriting these contexts will have access to the application users. ApplicationUser implements AuditableModel.

Usage

To use this module in your own, you will need to create three DbContexts - generic, read, and write - so that they can be registered. With the currently preferred structure, they will need to inherit from the Persistence DbContexts in a chain like shown in this diagram (using EngineBay.Blueprints module as an example):

%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart BT
    BlueprintsWriteDbContext --> BlueprintsQueryDbContext
    BlueprintsQueryDbContext --> BlueprintsDbContext
    BlueprintsDbContext --> ModuleWriteDbContext
    ModuleWriteDbContext --> ModuleQueryDbContext
    ModuleQueryDbContext --> ModuleDbContext
    click ModuleDbContext "https://github.com/engine-bay/persistence/blob/feature/readmes/EngineBay.Persistence/DbContexts/ModuleDbContext.cs" _blank
    click ModuleQueryDbContext "https://github.com/engine-bay/persistence/blob/feature/readmes/EngineBay.Persistence/DbContexts/ModuleQueryDbContext.cs" _blank
    click ModuleWriteDbContext "https://github.com/engine-bay/persistence/blob/feature/readmes/EngineBay.Persistence/DbContexts/ModuleWriteDbContext.cs" _blank
    click BlueprintsDbContext "https://github.com/engine-bay/blueprints/blob/main/EngineBay.Blueprints/Persistence/BlueprintsDbContext.cs" _blank
    click BlueprintsQueryDbContext "https://github.com/engine-bay/blueprints/blob/main/EngineBay.Blueprints/Persistence/BlueprintsQueryDbContext.cs" _blank
    click BlueprintsWriteDbContext "https://github.com/engine-bay/blueprints/blob/main/EngineBay.Blueprints/Persistence/BlueprintsWriteDbContext.cs" _blank

You should register your DbSets only in your generic DbContext:

namespace EngineBay.Blueprints
{
    using EngineBay.Persistence;
    using Microsoft.EntityFrameworkCore;

    public class BlueprintsDbContext : ModuleWriteDbContext
    {
        public BlueprintsDbContext(DbContextOptions<ModuleWriteDbContext> options)
            : base(options)
        {
        }

        public DbSet<Workbook> Workbooks { get; set; } = null!;

        public DbSet<Blueprint> Blueprints { get; set; } = null!;

        // More DbSets...

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            Workbook.CreateDataAnnotations(modelBuilder);
            Blueprint.CreateDataAnnotations(modelBuilder);
            // More annotations...

            base.OnModelCreating(modelBuilder);
        }
    }
}

If you desire extra functionality for any of the contexts, such as an auditing interceptor from EngineBay.Auditing, you can access the options builder with the OnConfiguring method, like this:

namespace EngineBay.Blueprints
{
    using EngineBay.Auditing;
    using EngineBay.Persistence;
    using Microsoft.EntityFrameworkCore;

    public class BlueprintsWriteDbContext : BlueprintsQueryDbContext
    {
        private readonly IAuditingInterceptor auditingInterceptor;

        public BlueprintsWriteDbContext(DbContextOptions<ModuleWriteDbContext> options, IAuditingInterceptor auditingInterceptor)
            : base(options)
        {
            this.auditingInterceptor = auditingInterceptor;
        }

        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
        {
            ArgumentNullException.ThrowIfNull(optionsBuilder);

            optionsBuilder.AddInterceptors(this.auditingInterceptor);

            base.OnConfiguring(optionsBuilder);
        }
    }
}

When you've created your module's DbContexts, you will need to create a CQRSDatabaseConfiguration object in your module's setup class that will register the contexts. For example:

namespace EngineBay.Blueprints
{
    using EngineBay.Core;
    using EngineBay.Persistence;
    using FluentValidation;

    public class BlueprintsModule : BaseModule
    {
        public override IServiceCollection RegisterModule(IServiceCollection services, IConfiguration configuration)
        {
            // Other services registration...

            var databaseConfiguration = new CQRSDatabaseConfiguration<BlueprintsDbContext, BlueprintsQueryDbContext, BlueprintsWriteDbContext>();
            databaseConfiguration.RegisterDatabases(services);

            return services;
        }

        // Other setup methods...
    }
}

You will then be able to use your DbContexts freely, as you might any other DbContext, though do try to keep CQRS principals in mind.

Registration

This module cannot run on its own. You will need to register it in your application to use its functionality. See the Demo API registration guide.

Note that you do not need to register the Persistence DbContexts. The ApplicationUsers DbSet that these contexts provide will be available to any other module's DbContexts by virtue of inheritance.

Environment Variables

See the Documentation Portal.

Dependencies

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on EngineBay.Persistence:

Package Downloads
EngineBay.Blueprints

Package Description

EngineBay.Authentication

Package Description

EngineBay.Auditing

Package Description

EngineBay.DatabaseManagement

Package Description

EngineBay.DemoModule

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
8.0.0 500 2/12/2024
7.0.2 332 1/16/2024
7.0.1 176 1/10/2024
7.0.0 240 1/9/2024
6.0.8 139 1/3/2024
6.0.7 108 1/3/2024
6.0.6 116 1/3/2024
6.0.5 140 12/21/2023
6.0.4 499 12/20/2023
6.0.3 608 12/6/2023
6.0.2 139 11/29/2023
6.0.1 369 11/23/2023
6.0.0 179 11/23/2023
5.0.7 128 11/20/2023
5.0.6 132 11/17/2023
5.0.5 435 11/15/2023
5.0.4 129 11/9/2023
5.0.3 120 11/9/2023
5.0.2 118 11/9/2023
5.0.1 294 11/2/2023
5.0.0 675 10/31/2023
4.2.1 125 10/31/2023
4.2.0 445 10/24/2023
4.1.4 146 10/11/2023
4.1.3 128 10/10/2023
4.1.2 141 10/9/2023
4.1.1 252 9/28/2023
4.1.0 481 9/28/2023
4.0.0 274 9/28/2023
3.4.12 138 9/25/2023
3.4.11 134 9/25/2023
3.4.10 118 9/25/2023
3.4.9 129 9/24/2023
3.4.8 367 9/24/2023
3.4.7 138 9/24/2023
3.4.6 214 9/23/2023
3.4.5 128 9/23/2023
3.4.4 136 9/23/2023
3.4.3 117 9/22/2023
3.4.2 131 9/21/2023
3.4.1 264 6/2/2023
3.4.0 148 6/1/2023
3.3.18 153 5/31/2023
3.3.17 147 5/31/2023
3.3.16 149 5/31/2023
3.3.15 627 4/25/2023
3.3.14 181 4/24/2023
3.3.13 264 4/21/2023
3.3.12 173 4/17/2023
3.3.11 179 4/17/2023
3.3.10 173 4/17/2023
3.3.9 249 4/12/2023
3.3.8 183 4/12/2023
3.3.7 186 4/8/2023
3.3.6 635 4/3/2023
3.3.5 192 4/3/2023
3.3.4 281 4/2/2023
3.3.3 213 4/1/2023
3.3.2 211 4/1/2023
3.3.1 201 4/1/2023
3.3.0 1,185 3/29/2023
3.2.5 545 3/27/2023
3.2.4 288 3/26/2023
3.2.3 207 3/26/2023
3.2.2 212 3/26/2023
3.2.1 198 3/26/2023
3.2.0 903 3/26/2023
3.1.0 478 3/26/2023
3.0.1 213 3/25/2023
3.0.0 1,272 3/25/2023
2.5.2 1,085 3/24/2023
2.5.1 297 3/24/2023
2.5.0 305 3/23/2023
2.4.0 218 3/23/2023
2.3.1 226 3/23/2023
2.3.0 307 3/23/2023
2.2.0 205 3/22/2023
2.1.2 329 3/22/2023
2.1.1 392 3/22/2023
2.0.1 305 3/21/2023
2.0.0 254 3/21/2023
1.3.0 295 3/21/2023
1.2.0 267 3/21/2023
1.1.1 306 3/20/2023
1.1.0 282 3/20/2023
1.0.3 211 3/20/2023
1.0.2 239 3/19/2023
1.0.1 224 3/19/2023
1.0.0 224 3/19/2023
0.10.2 240 3/19/2023
0.10.1 198 3/19/2023
0.10.0 211 3/19/2023
0.9.0 222 3/19/2023
0.8.0 228 3/19/2023
0.7.3 225 3/19/2023
0.7.2 218 3/19/2023
0.7.1 217 3/19/2023
0.7.0 418 3/19/2023
0.6.0 273 3/19/2023
0.5.0 307 3/18/2023
0.4.1 222 3/18/2023
0.4.0 279 3/18/2023
0.3.0 231 3/18/2023
0.2.1 228 3/18/2023
0.2.0 232 3/18/2023
0.1.0 236 3/17/2023
0.0.1 240 3/17/2023