Simplify.Repository 1.7.1

Simplify.Repository Documentation

Provides Repository and Unit of Work abstractions, plus ready-made implementations for Entity Framework Core and FluentNHibernate. The same abstraction layer (Simplify.Repository) works with either ORM, so application code depends only on the interfaces.

The family consists of three packages:

Core abstractions (Simplify.Repository)

Entity markers

Implement (or derive from a base class that implements) one of these:

IGenericRepository<T> where T : class

Read methods (each has an ...Async counterpart returning Task<...>):

T GetSingleByID(object id);
T GetSingleByQuery(Expression<Func<T, bool>> query);
T GetFirstByQuery(Expression<Func<T, bool>> query);
IList<T> GetMultiple(Expression<Func<T, bool>>? query = null, Func<IQueryable<T>, IQueryable<T>>? customProcessing = null);
IList<T> GetPaged(int pageIndex, int itemsPerPage, Expression<Func<T, bool>>? query = null, Func<IQueryable<T>, IQueryable<T>>? customProcessing = null);
int GetCount(Expression<Func<T, bool>>? query = null);
long GetLongCount(Expression<Func<T, bool>>? query = null);

Write methods (with ...Async counterparts):

object Add(T entity);   // returns the generated identifier
void Update(T entity);
void Delete(T entity);

Unit of work

public interface IUnitOfWork : IDisposable { }

public interface ITransactUnitOfWork : IUnitOfWork
{
    bool IsTransactionActive { get; }
    void BeginTransaction(IsolationLevel isolationLevel = IsolationLevel.ReadCommitted);
    void Commit();
    Task CommitAsync();
    void Rollback();
    Task RollbackAsync();
}

TransactGenericRepository<T>

A wrapper (IGenericRepository<T>) that automatically begins and commits/rolls back a transaction around each operation when no transaction is already active. It is what the DI registration extensions wire up for you.

public TransactGenericRepository(IGenericRepository<T> baseRepository,
    ITransactUnitOfWork unitOfWork,
    IsolationLevel isolationLevel = IsolationLevel.ReadCommitted);

FluentNHibernate (Simplify.Repository.FluentNHibernate)

Provides:

• Entity base classes: IdentityObject, LongIdentityObject, NamedObject, LongNamedObject, and StringIdentityObject (all with virtual properties).
• Two repository flavours:
  • GenericRepository<T>(ISession session) — uses a stateful NHibernate ISession.
  • StatelessGenericRepository<T>(IStatelessSession session) — uses a lighter IStatelessSession.

Unit of work implementations: UnitOfWork(ISessionFactory), StatelessUnitOfWork(ISessionFactory), TransactUnitOfWork(ISessionFactory), TransactStatelessUnitOfWork(ISessionFactory).

Mapping base classes (FluentNHibernate ClassMap<T>): IdentityObjectMap<T>, NamedObjectMap<T>, LongIdentityObjectMap<T>, LongNamedObjectMap<T>, StringIdentityObjectMap<T>.

Define an entity and its mapping

using Simplify.Repository.FluentNHibernate;
using Simplify.Repository.FluentNHibernate.Mappings;

public class User : NamedObject
{
    public virtual string? Email { get; set; }
}

public class UserMap : NamedObjectMap<User>   // base maps Id(x => x.ID) and Map(x => x.Name).Not.Nullable()
{
    public UserMap()
    {
        Map(x => x.Email).Nullable();
    }
}

Register with Simplify.DI

using Simplify.DI;
using Simplify.Repository;
using Simplify.Repository.FluentNHibernate;
using NHibernate;

DIContainer.Current
    .Register<TransactUnitOfWork>(r => new TransactUnitOfWork(r.Resolve<ISessionFactory>()))
    .Register<ITransactUnitOfWork>(r => r.Resolve<TransactUnitOfWork>())
    .RegisterTransactRepository<User, ITransactUnitOfWork>();

// For stateless sessions, use the stateless overloads instead:
// .RegisterStatelessTransactRepository<User, ITransactUnitOfWork>();

The FluentNHibernate package provides both RegisterTransactRepository<...> and RegisterStatelessTransactRepository<...> (each with a two- and three-type-parameter overload).

Entity Framework Core (Simplify.Repository.EntityFramework)

Provides:

• Entity base classes: IdentityObject, LongIdentityObject, NamedObject, LongNamedObject (all with virtual properties).
• GenericRepository<T>(DbContext session) — IGenericRepository<T> over a DbContext.
• UnitOfWork<T>(DbContext context) where T : DbContext — exposes Context.
• TransactUnitOfWork<T>(DbContext context) where T : DbContext — ITransactUnitOfWork.
• Mapping base classes (Microsoft.EntityFrameworkCore IEntityTypeConfiguration<T>): IdentityObjectMap<T>, NamedObjectMap<T>, LongIdentityObjectMap<T>, LongNamedObjectMap<T>.

Define an entity and its mapping

using Simplify.Repository.EntityFramework;
using Simplify.Repository.EntityFramework.Mappings;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

public class User : NamedObject
{
    public virtual string? Email { get; set; }
}

public class UserMap : NamedObjectMap<User>   // ID + required Name are configured by the base class
{
    protected override void ConfigureEntity(EntityTypeBuilder<User> builder)
    {
        builder.Property(x => x.Email).HasMaxLength(255);
    }
}

Apply the mapping in your DbContext.OnModelCreating:

protected override void OnModelCreating(ModelBuilder modelBuilder) =>
    modelBuilder.ApplyConfiguration(new UserMap());

Register with Simplify.DI

RegisterTransactRepository<T, TUnitOfWork> registers GenericRepository<T> and exposes IGenericRepository<T> as a transaction-wrapped repository:

using System.Data;
using Simplify.DI;
using Simplify.Repository;
using Simplify.Repository.EntityFramework;

DIContainer.Current
    // your DbContext and a unit of work implementing ITransactUnitOfWork must be registered first
    .Register<ITransactUnitOfWork>(r => new TransactUnitOfWork<AppDbContext>(r.Resolve<AppDbContext>()))
    .RegisterTransactRepository<User, ITransactUnitOfWork>();

There is also a three-type-parameter overload that builds the repository from a concrete unit of work's Context:

RegisterTransactRepository<User, ITransactUnitOfWork, MyUnitOfWorkImpl>(IsolationLevel.ReadCommitted);
// where MyUnitOfWorkImpl : UnitOfWork<DbContext>

Note: the stateless-repository registration overloads are not yet implemented for the EntityFramework package.

Using a repository

Once registered, inject IGenericRepository<T> (transaction handling is automatic via the wrapper):

public class UserService(IGenericRepository<User> users)
{
    public Task<User> GetAsync(int id) => users.GetSingleByIDAsync(id);

    public Task<IList<User>> SearchAsync(string namePart) =>
        users.GetMultipleAsync(u => u.Name != null && u.Name.Contains(namePart));

    public async Task<object> CreateAsync(string name, string email) =>
        await users.AddAsync(new User { Name = name, Email = email });
}

For explicit transaction control, resolve and use an ITransactUnitOfWork directly:

unitOfWork.BeginTransaction();
var id = await repository.AddAsync(user);
await unitOfWork.CommitAsync();