Skip to content

Open session

This operation selects and opens the NHibernate session for a new unit of work, choosing between a stateful (change-tracking) and stateless (bulk-throughput) strategy, and pairs it with the engine-appropriate system-date helper.

Field Value
Operation ID OP-NH-06
Trigger Create unit of work calls BuildSessionStrategy/BuildSessionHelper while assembling a UnitOfWork
Inputs ISessionFactory, options.StatelessSessionStrategy, options.Database, the factory's debugOutputSql flag
Outputs An ISessionStrategy (StatefulSessionStrategy or StatelessSessionStrategy) and an ISessionHelper (OracleSessionHelper, SqlServerSessionHelper, or PostgreSqlSessionHelper)
Primary components UnitOfWorkFactory.BuildSessionStrategy, BuildSessionHelper
Entry point src/SAIF.NetCore.Nhibernate/SAIF.NetCore.NHibernate/SAIF.NetCore.NHibernate/Factories/UnitOfWorkFactory.cs

Steps

  1. BuildSessionStrategy(factory, options.StatelessSessionStrategy) checks options.StatelessSessionStrategy (BR-NH-10):
  2. If true: return new StatelessSessionStrategy(factory.OpenStatelessSession()). No interceptor is ever applied on this path.
  3. If false:
    • If the factory's debugOutputSql is true: open the session with factory.WithOptions().Interceptor(new SqlDebugOutputInterceptor()).OpenSession() (BR-NH-09). See Debug SQL tracing for how the interceptor behaves.
    • Otherwise: open the session with factory.OpenSession().
    • Either way, wrap the resulting ISession in new StatefulSessionStrategy(session).
  4. BuildSessionHelper(sessionStrategy, options) switches on options.Database (BR-NH-07):
  5. Oracle → new OracleSessionHelper(strategy)
  6. Sql → new SqlServerSessionHelper(strategy)
  7. PostGreSql → new PostgreSqlSessionHelper(strategy)
  8. Any other value → new OracleSessionHelper(strategy)

Process flow

The diagram below visualizes the stateless/stateful branch, the debug-interceptor sub-branch for stateful sessions, and the engine-selection branch for the matching session helper.

flowchart TD
    Start(["BuildSessionStrategy called"]) --> Stateless{"StatelessSessionStrategy?"}
    Stateless -->|Yes| OpenStateless["factory.OpenStatelessSession()"]
    Stateless -->|No| Debug{"debugOutputSql?"}
    Debug -->|Yes| OpenWithInterceptor["OpenSession() with<br>SqlDebugOutputInterceptor"]
    Debug -->|No| OpenPlain["factory.OpenSession()"]
    OpenStateless --> WrapStateless["new StatelessSessionStrategy"]
    OpenWithInterceptor --> WrapStateful["new StatefulSessionStrategy"]
    OpenPlain --> WrapStateful
    WrapStateless --> Helper["BuildSessionHelper(options.Database)"]
    WrapStateful --> Helper
    Helper --> Return(["Return ISessionStrategy + ISessionHelper"])

Failure and edge-case behavior

  • Stateless sessions never receive the SQL debug interceptor, regardless of debugOutputSql (BR-NH-09).
  • An unrecognized options.Database value falls back to the Oracle session helper, which issues Oracle-specific SQL (select sysdate from dual) against whatever engine the connection string actually points at — this can fail at runtime if the engine is not Oracle.*

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/Factories/UnitOfWorkFactory.cs