OpsFusion.Data 10.0.2

OpsFusion.Data

OpsFusion.Data is the shared data-access foundation for OpsFusion services. Use it to keep every project consistent in:

• Connection management
• Read vs write behavior
• Transaction boundaries
• Repository rules
• Main DB and log DB separation

Quick Start (Recommended)

1. Install package:

dotnet add package OpsFusion.Data

2. Add configuration keys shown in this README.
3. Register in DI: services.AddOpsFusionData(configuration).
4. Use IUnitOfWorkRunner in CQRS handlers.
5. Save via EF Core SaveChangesAsync or RunReadWriteAndSaveAsync(...).

What You Get

• IUnitOfWorkFactory (main DB)
• IUnitOfWorkLogFactory (log DB)
• IUnitOfWorkRunner (scope runner)
• IUnitOfWorkSessionAccessor (current mode/session)
• BaseRepositoryWithKey<TEntity, TKey, TDbContext>
• BaseRepository<TEntity, TDbContext>
• AddOpsFusionData(...) DI extension

Core Concepts

1) Unit of Work Modes

• ReadOnly: for query handlers.
• ReadWrite: for simple writes.
• ReadWriteWithTransaction: for multi-step atomic writes.

2) Session-bound Safety

Inside runner scope, repositories can detect mode. Writes in ReadOnly mode throw by design.

3) Main and Log Database Split

• Main domain data → IUnitOfWorkFactory
• Audit/log/telemetry data → IUnitOfWorkLogFactory

Required Configuration

AddOpsFusionData resolves:

• Database:Provider
• LogStorage:Provider (optional, fallback = Database:Provider)

and provider-specific connection strings.

SQL Server

{
  "Database": { "Provider": "SqlServer" },
  "LogStorage": { "Provider": "SqlServer" },
  "ConnectionStrings": {
    "SqlServerReadOnly": "Server=...;Database=MainDb;User Id=...;Password=...;TrustServerCertificate=True",
    "SqlServerWrite": "Server=...;Database=MainDb;User Id=...;Password=...;TrustServerCertificate=True",
    "LogSqlServerReadOnly": "Server=...;Database=LogDb;User Id=...;Password=...;TrustServerCertificate=True",
    "LogSqlServerWrite": "Server=...;Database=LogDb;User Id=...;Password=...;TrustServerCertificate=True"
  }
}

PostgreSQL

{
  "Database": { "Provider": "Postgres" },
  "LogStorage": { "Provider": "Postgres" },
  "ConnectionStrings": {
    "PostgresReadOnly": "Host=...;Database=MainDb;Username=...;Password=...",
    "PostgresWrite": "Host=...;Database=MainDb;Username=...;Password=...",
    "LogPostgresReadOnly": "Host=...;Database=LogDb;Username=...;Password=...",
    "LogPostgresWrite": "Host=...;Database=LogDb;Username=...;Password=..."
  }
}

CQRS-First Usage (Recommended)

Query Handler (ReadOnly)

public sealed class GetCustomersQueryHandler(
    IUnitOfWorkRunner unitOfWorkRunner,
    ICustomerRepository customerRepository)
{
    public Task<IReadOnlyList<CustomerEntity>> Handle(CancellationToken ct)
        => unitOfWorkRunner.RunReadOnlyAsync(
            async token =>
            {
                IList<CustomerEntity> rows = await customerRepository.GetByFilterAsync(_ => true, track: false, cancellationToken: token);
                return (IReadOnlyList<CustomerEntity>)rows.ToList();
            },
            ct);
}

Command Handler (ReadWrite + Save)

public sealed class CreateCustomerCommandHandler(
    IUnitOfWorkRunner unitOfWorkRunner,
    ICustomerRepository customerRepository,
    PosInventoryDbContext dbContext)
{
    public Task<Guid> Handle(CreateCustomerCommand command, CancellationToken ct)
        => unitOfWorkRunner.RunReadWriteAndSaveAsync(
            dbContext,
            async token =>
            {
                var entity = new CustomerEntity { Id = Guid.NewGuid(), Name = command.Name };
                await customerRepository.AddAsync(entity, token);
                return entity.Id;
            },
            ct);
}

Command Handler (Transactional)

await unitOfWorkRunner.RunReadWriteWithTransactionAsync(
    async ct =>
    {
        await orderRepository.AddAsync(order, ct);
        await stockRepository.RemoveByFilterAsync(x => x.ProductId == order.ProductId, cancellationToken: ct);
        await dbContext.SaveChangesAsync(ct);
    },
    DataIsolationLevel.ReadCommitted,
    cancellationToken);

Dapper-First Usage

await using IConnectionUnitOfWork uow = await unitOfWorkFactory.OpenReadWriteWithTransactionAsync(
    DataIsolationLevel.ReadCommitted,
    cancellationToken);

const string sql = "INSERT INTO Customers (Id, Name) VALUES (@Id, @Name);";

await uow.Connection.ExecuteAsync(
    sql,
    new { Id = Guid.NewGuid(), Name = "John" },
    uow.Transaction);

await uow.CommitAsync(cancellationToken);

If you use read replicas, use OpenReadOnlyAsync for query workloads.

Repository Pattern

public interface ICustomerRepository : IBaseRepositoryWithKey<CustomerEntity, Guid>
{
}

public sealed class CustomerRepository(
    PosInventoryDbContext dbContext,
    IUnitOfWorkSessionAccessor sessionAccessor)
    : BaseRepositoryWithKey<CustomerEntity, Guid, PosInventoryDbContext>(
        dbContext,
        id => x => x.Id == id,
        sessionAccessor),
      ICustomerRepository
{
}

Project Integration Template

Starter files are available at:

• src/OpsFusion.Data/templates/starter/DependencyInjection.cs
• src/OpsFusion.Data/templates/starter/appsettings.data.json
• src/OpsFusion.Data/templates/starter/SampleCreateCustomerCommandHandler.cs
• src/OpsFusion.Data/templates/starter/SampleGetCustomersQueryHandler.cs
• src/OpsFusion.Data/templates/starter/SampleDapperRepository.cs

Copy these into a new project and rename namespaces/types.

Integration Checklist

1. Add OpsFusion.Data package
2. Add provider + main/log connection strings
3. Register AddOpsFusionData(configuration)
4. Register your DbContext
5. Register repositories
6. Use IUnitOfWorkRunner in CQRS handlers
7. Always save EF changes for writes
8. Use transaction mode for atomic writes

Common Mistakes

• Missing provider-specific keys
• Running writes in read-only mode
• Forgetting SaveChangesAsync
• Mixing main and log unit-of-work factories