IronAlpine.Data.Abstractions 3.0.0

IronAlpine.Data.Abstractions

Why

Defines storage-agnostic contracts for repositories, unit of work, audit context, and query abstractions. This package is the stable API boundary used by handlers and application services.

Key Contracts

• IUnitOfWork
• IReadRepository<TEntity>
• IRepository<TEntity>
• IAggregateRepository<TAggregate>
• IProjectionReadRepository<TProjection>
• IProjectionRepository<TProjection>
• IAuditableCommand

Installation

dotnet add package IronAlpine.Data.Abstractions

Usage

public sealed class GetUsersQueryHandler : IQueryHandler<GetUsersQuery, PagedResult<UserDto>>
{
    private readonly IProjectionReadRepository<UserProjection> _read;

    public GetUsersQueryHandler(IProjectionReadRepository<UserProjection> read)
    {
        _read = read;
    }
}

Repository Selection Rules

• Aggregate writes: IAggregateRepository<TAggregate>.
• Projection reads: IProjectionReadRepository<TProjection>.
• Projection update operations: IProjectionRepository<TProjection>.
• Keep IQueryable inside handlers/services, never leak to controllers.

Unit of Work

IUnitOfWork remains handler-controlled. Save boundary is explicit in handler logic.

Paging

Use package-level paging contracts from IronAlpine.Kernel with repository overloads that accept paged request objects where supported by concrete provider packages.

Combinations

• With IronAlpine.Data.EFCore: EF implementations for repositories/UoW.
• With IronAlpine.Data.Dapper: Dapper path for read-heavy workloads.
• With IronAlpine.Data.EFCore.Mediator: transaction and auditing behaviors.

Troubleshooting

• Injecting IRepository<TProjection> for read-only flow is an architecture smell.
• Using IAggregateRepository for projection updates should fail by design.

Migration Note

Prefer replacing legacy common persistence interfaces with these abstractions first, then switch provider package registrations.

Configuration Deep Dive

When a package exposes options classes, use builder.Configuration binding and keep values explicit per environment.

Common guidance:

• Prefer explicit values in production.
• Keep retries/timeouts conservative; tune with telemetry.
• Enable startup validation in non-development environments.
• Fail fast when required dependencies are missing.

Integration Patterns

Pattern A: API service with EF + Messaging

1. Register EF provider package.
2. Register messaging inbox/outbox package.
3. Register mediator and behavior order.
4. Enable health readiness checks for DB and broker.

Pattern B: Read-heavy service with Dapper + Messaging

1. Register Dapper data package.
2. Register messaging package with consumer enabled.
3. Add observability and structured logging.

Pattern C: Security-focused service

1. Register security ASP.NET package.
2. Add policy catalog or resolver.
3. Register authorization EFCore projection package only where needed.

Options Checklist

Use this checklist when configuring any IronAlpine package:

• Required connection strings present.
• Feature flags intentional (Enable* values reviewed).
• Retry and timeout values match SLO expectations.
• Startup validation behavior understood.
• Environment-specific defaults are overridden in production.

Troubleshooting Matrix

• Startup failure with validation error : A required dependency package or config value is missing. Check package registrations and bound options sections.
• Background workers not starting : Verify execution mode, Enable* flags, and hosted services registration.
• Policy/authorization mismatch : Check claim types, policy naming strategy, and catalog entries.
• Cache stale or no-hit behavior : Validate key generation, invalidation path, and distributed lock configuration.
• Messaging duplicate handling issues : Verify event-id propagation and idempotency key construction.

Best-Practice Notes

• Keep handler logic deterministic and side-effect boundaries explicit.
• Keep IQueryable usage inside application handlers/services.
• Keep transaction save boundaries in handlers where business intent is clear.
• Prefer explicit topic policy metadata for critical events.