---
title: SAIF.NetCore.NHibernate overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework
last_reviewed: 2026-10-02
library: SAIF.NetCore.NHibernate
reference_type: package
---

# SAIF.NetCore.NHibernate overview

> **Documentation context:** Packaged Component (NuGet)

SAIF.NetCore.NHibernate is the repository's NHibernate data-access infrastructure provider: it defines the `IUnitOfWork`/`IUnitOfWorkFactory`/`IRepository<TEntity>`/`ISessionStrategy` stack, a named-options configuration model (`UnitOfWorkOptions`/`ConfigureUnitOfWorkOptions`), and per-engine driver configurations for Oracle, SQL Server, and PostgreSQL built on FluentNHibernate, but it ships no entity mappings or business schema of its own — consuming applications supply those.

## Purpose
- Provide a reusable Unit of Work and generic Repository abstraction over NHibernate so that consuming applications do not have to hand-roll session, transaction, and configuration management for Oracle, SQL Server, or PostgreSQL.
- Supply a named-options configuration pattern (`UnitOfWorkOptions`/`ConfigureUnitOfWorkOptions`) through which a consuming application resolves connection strings and environment settings via `IEnvironmentClient`/`IDBConnectionClient` (both from `SAIF.NetCore.ServiceContracts`).
- Offer both stateful (change-tracking) and stateless (bulk-throughput) NHibernate session strategies behind one `ISessionStrategy` contract.
- No application or library in this repository currently references this package* — `SAIF.NetCore.ServiceExtensions` does not bring it in transitively even though the top-level architecture diagram draws a composition arrow from ServiceExtensions to the data group; consuming applications must reference `SAIF.NetCore.NHibernate` directly, and this is a documented discrepancy between the diagram and the actual package graph*.

## Responsibilities
- Build and cache an NHibernate `ISessionFactory` per connection string, selecting the Oracle, SQL Server, or PostgreSQL driver configuration from `UnitOfWorkOptions.Database`.
- Manage the transaction lifecycle at `ReadCommitted` isolation (`Begin`/`Commit`/`Rollback`/`Dispose`). `Begin` is refused while a transaction is already active. One unit of work per transaction is the recommended usage, but the library does not enforce it.
- Discover consumer-supplied Fluent `ClassMap<T>` and embedded HBM mappings by assembly scan when a session factory is built.
- Register the modern DI surface (`AddNhibernateServices`) while retaining 13 legacy registration methods as `[Obsolete("Due to functional changes between .net core 2.2 and .net core 3.1, this method is obsolete to avoid startup errors.", true)]` compile-time errors for migration enforcement.
- Expose an engine-specific database system-date query (`SystemDate`) through `ISessionHelper` implementations.

## Key components
- `UnitOfWorkFactory`: builds and caches `ISessionFactory` instances per connection string and hands out `IUnitOfWork` instances.
- `UnitOfWork`: the transaction boundary (`Begin`/`Commit`/`Rollback`/`Dispose`) and repository factory.
- `Repository<TEntity>`: generic CRUD/query pass-through to the active `ISessionStrategy`.
- `ISessionStrategy` (`StatefulSessionStrategy`/`StatelessSessionStrategy`): adapts NHibernate's `ISession`/`IStatelessSession` to one contract.
- `BaseConfiguration` (`OracleConfiguration`/`SqlConfiguration`/`PostGreSqlConfiguration`): per-engine FluentNHibernate driver configuration.
- `UnitOfWorkOptions`/`ConfigureUnitOfWorkOptions`: the named-options model a consuming application subclasses per logical database.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [SQL catalog](sql/index.md)
- [Service registration](service-registration.md)
- [API reference](api/index.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate.csproj`
- `src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Factories/UnitOfWorkFactory.cs`
- `src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/UnitOfWork.cs`
- `src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Extensions/IServicesCollectionExtensions.cs`