The object-relational mapper for .NET

NHibernate 2.0

This page is converted from the old nhforge.org Wiki. First published by: Stefan Steinegger on 05-28-2009, Last revision by: abhishek644 on 02-08-2012

NHibernate Documentation Structure Proposal

This is a proposal for a new structure of the NHibernate reference documentation. The goal is to discuss it and get some feedback from the community.


The goals of the restructuring of the documentation are:

  • move from "feature oriented" to "solution oriented". For instance, instead of having a chapter about the "version" xml element, there is a chapter about "concurrency". So the reader has a problem to solve, and he finds a chapter that explains, how NH solves it. The reader can't know that he needs a version element. Such a chapter should cover all elements of a certain problem, in the given example this are the version xml-element, the optimistic-lock xml-attribute of classes and properties, explicit version increment, locking and so on.
  • Additionally, there shall be a complete reference of the mappings, configurations and others in an appendix that links to the chapters.
  • More diagrams for mapping strategies
  • More best practices and patterns
  • Fill gaps where the documentation is not complete (enough), for instance special HQL features, user types, interceptors and events, connection factories and other extensions, (new) proxy factories etc.


Part 1: First Steps

In this part: a high-level overview of the whole picture.

Quick start

  • simple program that runs "out of the box"
  • not too much code, not too much explanation (but links to chapters)
  • includes inheritance, reference, list
  • includes schema generation
  • includes some simple hql
  • includes configuration for sqlserver, oracle, mysql

Architecture and basic concepts

  •  Architecture (diagrams)
  •  "Factory-Chain" Configuration => SessionFactory => Session => Transaction / Query
  •  Instance States
  •  Session Cache (see also "Working with persistent objects")
  •  Application Architectures (referenced assemblies from application layers)

Setting Up

  • Three ways: nhibernate.cfg.xml, app.config, programmatic
  • Dialects and Drivers (See also Appendix "full list of Drivers / Dialects")
  • ProxyFactory configuration (see "lazy loading")
  • SessionProvider, contextual sessions
  • Getting a connection (connection provider, user provided, connection release mode)
  • How to set up a Project, minimal program
    • configuration file
    • mapping files (see "OR Mapping Basics")

Part 2: Writing and Mapping Classes

In this part: Static view, classes, mappings, db schema

Persistent classes

  • Example poco, basic rules
  • Object Identity
    • id generators
    • best practices
    • composite keys (see also "Working with legacy databases")
    • component keys (see also "Working with legacy databases")
  • Overriding Equals and GetHashCode
  • Optional: Version (see optimistic locking)
  • lifecycle callbacks
  • validation
  • see also: lazy loading (because of virtual)

OR Mapping Basics

  • Manage mapping files
    • as xml files
    • as embedded resources
    • modular mapping files
    • alternatives (attributes, FNH)
  • Using quoted identifiers
    • NH Types (see also: "Extend NH behaviour - user types", Appendix "Full List of Types")
  • Naming conventions
  • Property / field (access strategy)

Mapping primitive values and single ended references

  • properties
  • references many-to-one
  • references one-to-one
  • map several classes to one table: components
  • dynamic components
  • map a class to several tables: join
  • any types

Mapping Collections

  • persistent collections
  • set, list, map, bag, array, primitive-array
  • one-to-many relations
  • many-to-many relations
  • composite-elemements
  • collection performance
  • Sorted collections

Mapping Inheritance

  • Table per Hierarchy
  • Table per Concrete Class
  • Table per Class
  • Mixing strategies

Mapping to legacy databases

  • composite keys
  • component keys
  • property-ref

Generating The Database

  • The schema export tool
  • not null
  • foreign keys
  • indexes
  • unique keys
  • Auxiliary Database Objects

mapping file generation from entity

Part 3: Working with Persistent Objects

In this part: Dynamic view, sessions, queries, modifications, transactions etc.

Working with sessions

  • sessions, session cache, flushing
  • cascading
  • detached objects, reattaching


  • Introduction, when to use which kind of query

HQL Queries

  • Syntax
  • Multi Query

Criteria Queries

  • API
  • Multi Criteria

Using NH filters

Lazy loading and fetching strategies

  • fetching strategies
  • collections
  • references (proxies)
  • load
  • Utility.Initialize
  • batch fetching

Updating and deleting

  • updating, batch-updates, HQL updates
  • deleting, one-shot-delete, HQL delete

Transactions And Concurrency

  • Transaction factory (see also: setting up)
  • Concurrency
    • Optimistic Locking
      • Version columns
      • Property level
      • Force version increment
      • application version check
    • Pessimistic Locking

Part 4: Enhanced Features

In this part: Features that are not used by everyone. They are not important to understand to work with NH.

Using Native SQL

  • Sql queries
  • custom SQL for query/update/insert/delete
  • precompiled queries
  • Using SP's, db functions and triggers
    • property update/insert
    • property generated
    • property formula
    • see also: "Generating The Database - Auxiliary Database Objects"
  • Using Database Views


  • second level cache
  • query cache

Meta API

Extend NH behaviour

  • user types
  • Interceptors
  • events
  • connection provider
  • transaction factory
  • session provider

Part 5: Examples

In this part: examples


In this part: lists and references. The references (eg. mapping xml elements, dialects etc are important to find the documentation. So there are basically only links to chapters)

Trouble shooting

Configuration Reference

  • Getting a connection (connection provider, user provided) (setting up)
  • proxy generator (lazy loading)
  • cache configuration (optimizing)
  • Transaction factory (setting up)
  • Dialects (setting up)
  • Outer join fetching (lazy loading?)
  • logging (trouble shooting)
  • naming strategy (mapping)

Full List of Dialiects

Full List of Drivers

XML-Mapping full reference

Full List of Type

© NHibernate Community 2024