SAIF.NetCore.NHibernate operations and processes¶

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog¶

Operation	Intent	Trigger	Inputs	Outputs	Rules	Tables	SQL
Register NHibernate services	Register the singleton unit-of-work factory and scoped accessor with DI	Host calls `AddNhibernateServices`/`AddNhibernateServices<T>` at startup	Mapping assemblies, `debugOutputSql`	`IUnitOfWorkFactory` singleton, `UnitOfWorkAccessor` scoped service	BR-NH-01	—	—
Configure named unit-of-work options	Resolve and cache a connection string and engine for one named database	`IOptionsSnapshot<UnitOfWorkOptions>.Get(name)` runs registered configurers	`IEnvironmentClient`, `IDBConnectionClient`	Populated `UnitOfWorkOptions.Name`/`Database`/`ConnectionString`	BR-NH-02, BR-NH-03	—	—
Obtain unit of work by name	Resolve named options and hand the caller a ready unit of work	Consumer calls `UnitOfWorkAccessor.UnitOfWork(key)`	`key` (options name)	`IUnitOfWork` instance	BR-NH-04	—	—
Create unit of work	Build (or reuse) a session factory and hand out a new unit of work	`UnitOfWorkFactory.GetUnitOfWork(options)` is called	`UnitOfWorkOptions`	`IUnitOfWork` instance	BR-NH-04, BR-NH-05, BR-NH-06	—	—
Build session factory	Build an NHibernate `Configuration`/`ISessionFactory` for a given engine and mapping set	First `GetUnitOfWork` call for a connection string/name pair	`UnitOfWorkOptions`, mapping assemblies	Cached `ISessionFactory`; `INhConfiguration` wrapper (cached), wrapped `Configuration` (rebuilt per call)	BR-NH-06, BR-NH-07, BR-NH-08	—	—
Open session	Choose a stateful or stateless NHibernate session and its system-date helper	`UnitOfWorkFactory` builds a new unit of work	`ISessionFactory`, `options.StatelessSessionStrategy`, `options.Database`	`ISessionStrategy` + `ISessionHelper` pair	BR-NH-09, BR-NH-10	—	—
Begin transaction	Start a `ReadCommitted` transaction on the unit of work's session	Consumer calls `IUnitOfWork.Begin()`	—	Active transaction, or exception	BR-NH-11, BR-NH-12	—	SQL-004 (as part of Test connection)
Commit	Commit the active transaction and clear the session	Consumer calls `IUnitOfWork.Commit()`	—	Committed transaction, cleared session, or exception	BR-NH-13	—	SQL-004 (as part of Test connection)
Rollback	Roll back any active transaction and dispose the session when rollback itself does not throw	Consumer calls `IUnitOfWork.Rollback()`	—	Rolled-back transaction (if any), disposed session (normal path only)	BR-NH-14	—	—
Dispose unit of work	Release the underlying NHibernate session	Consumer calls/`using`-disposes `IUnitOfWork`	—	Disposed session	—	—	—
Repository CRUD and query operations	Add/update/delete/query/get/load entities through the active session strategy	Consumer calls `IRepository<TEntity>` members	Entity instance or id, or a LINQ expression	Persisted change, or query result	BR-NH-15	TEntity	SQL-004
Get database system date	Read the current database server date for the active engine	Consumer reads `IRepository<T>.SystemDate`/`ISessionHelper.SystemDate`	—	`DateTime` (server date, or local fallback)	BR-NH-17, BR-NH-18	DUAL	SQL-001, SQL-002, SQL-003
Test connection	Prove connectivity, session-factory build, and mapped-table accessibility for a generic entity	Consumer calls `IUnitOfWork.TestConnection<TEntity>()`	`TEntity` type parameter	Success (no rows), or exception	BR-NH-11, BR-NH-12, BR-NH-13	TEntity	SQL-004
Debug SQL tracing	Trace generated SQL to `System.Diagnostics.Trace` while debugging a stateful session	NHibernate prepares a statement on a stateful session built with `debugOutputSql = true`	Prepared `SqlString`	Trace output (only while a debugger is attached)	BR-NH-09	—	—

Process flow diagram¶

The following diagram visualizes the primary operational flow across operations, from registration through a typical unit-of-work lifecycle.

flowchart TD
    Register["Register NHibernate services<br>(AddNhibernateServices)"] --> ConfigureOptions["Configure named<br>unit-of-work options"]
    ConfigureOptions --> Obtain["Obtain unit of work<br>by name"]
    Obtain --> Create["Create unit of work<br>(factory)"]
    Create --> BuildFactory{"Session factory<br>cached?"}
    BuildFactory -->|No| Build["Build session factory"]
    BuildFactory -->|Yes| OpenSession["Open session<br>(choose strategy)"]
    Build --> OpenSession
    OpenSession --> Begin["Begin transaction"]
    Begin --> Work["Repository CRUD / query operations"]
    Work --> Decision{"Operation<br>succeeded?"}
    Decision -->|Yes| Commit["Commit"]
    Decision -->|No| Rollback["Rollback"]
    Commit --> Dispose["Dispose unit of work"]
    Rollback --> Dispose

Database interactions¶

The following table summarizes which operations read from or write to the database. Per-step SQL and table citations live in each operation's detail page under operations/.

Operation	SQL	Tables	Type
Begin transaction	SQL-004 (as part of Test connection)	—	—
Commit	SQL-004 (as part of Test connection)	—	—
Repository CRUD and query operations	SQL-004 (illustrative LINQ shape)	TEntity	Read / Write (consumer-dependent)
Get database system date	SQL-001, SQL-002, SQL-003	DUAL (Oracle only)	Read
Test connection	SQL-004	TEntity	Read

All other operations (register services, configure options, obtain/create/dispose a unit of work, open a session, debug SQL tracing) manage infrastructure only and contain no literal SQL text authored by this library; see the SQL catalog and database tables for full detail on the statements above. This is distinct from Commit and Rollback: although neither contains SQL text in this library's own source, Commit calls NHibernate's ITransaction.Commit() — which internally issues a database COMMIT and, for a stateful session, triggers NHibernate's auto-flush of any pending INSERT/UPDATE/DELETE changes before committing, subject to the session's own externally-configured FlushMode (for example FlushMode.Never/Manual would suppress the implicit flush) — this is not an unconditional guarantee independent of session configuration. For a stateless session there is no such flush step, because stateless Add/Update/Delete operations already execute immediately rather than being queued; Session.Clear() after commit is a first-level-cache discard on a stateful session and a literal no-op on a stateless session. Rollback calls ITransaction.Rollback(), issuing a database ROLLBACK, when a transaction is active. These are NHibernate/ADO.NET provider behaviors external to this library's own source code, so "no SQL text in this library's source" must not be read as "no database activity occurs."*

Failure and edge-case behavior¶

Resolving an unregistered options name yields default UnitOfWorkOptions with no connection string, so Create unit of work throws InvalidOperationException.
A GetConnectionString() failure in a consumer's ConfigureUnitOfWorkOptions subclass surfaces when the named options are first resolved, before any session work begins.
Calling Begin transaction while the unit of work's transaction is still active throws InvalidOperationException. After a successful Commit, the session stays open, and against NHibernate 5.2.7 a further Begin on the same unit of work starts a new transaction. Rollback disposes the session, so what happens on a later Begin is not confirmed by this library's source. Using one unit of work per transaction is recommended, but the library does not enforce it.
When Rollback's own transaction.Rollback() call does not throw, Rollback disposes the session; whether the unit of work can still be used afterward is not fully guaranteed either way (the stateful session strategy can transparently reopen a closed session on next access — see ISessionStrategy). Rollback has no try/finally, so a throwing transaction.Rollback() skips that disposal (see the Rollback page for the full caveat). Disposal of an open transaction/session by some ADO.NET providers can itself trigger an implicit rollback — this is inferred provider behavior, not confirmed in this library's own source.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources¶

src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Extensions/IServicesCollectionExtensions.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Options/ConfigureUnitOfWorkOptions.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/UnitOfWorkAccessor.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Factories/UnitOfWorkFactory.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Factories/Configuration/BaseConfiguration.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/UnitOfWork.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Repository.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/SessionHelpers/SessionHelperBase.cs
src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Factories/Configuration/SqlDebugOutputInterceptor.cs