When an entity instance of an immutable class is made persistent, NHibernate automatically makes it read-only.

An entity of an immutable class can created and deleted the same as an entity of a mutable class.

NHibernate treats a persistent entity of an immutable class the same way as a read-only persistent entity of a mutable class. The only exception is that NHibernate will not allow an entity of an immutable class to be changed so it is not read-only.

To change the default behavior so NHibernate loads entity instances of mutable classes into the session and automatically makes them read-only, call:

Session.DefaultReadOnly = true;

To change the default back so entities loaded by NHibernate are not made read-only, call:

Session.DefaultReadOnly = false;

You can determine the current setting by using the property:

Session.DefaultReadOnly;

If Session.DefaultReadOnly property returns true, entities loaded by the following are automatically made read-only:

Changing this default has no effect on:

If Session.DefaultReadOnly returns false (the default) when an HQL query or criteria executes, then entities and proxies of mutable classes loaded by the query will not be read-only.

You can override this behavior so that entities and proxies loaded by an HQL query or criteria are automatically made read-only.

For an HQL query, call:

Query.SetReadOnly(true);

Query.SetReadOnly(true) must be called before Query.List(), Query.UniqueResult(), or Query.Enumerable()

For an HQL criteria, call:

Criteria.SetReadOnly(true);

Criteria.SetReadOnly(true) must be called before Criteria.List(), or Criteria.UniqueResult()

Entities and proxies that exist in the session before being returned by an HQL query or criteria are not affected.

Uninitialized persistent collections returned by the query are not affected. Later, when the collection is initialized, entities loaded into the session will be read-only if Session.DefaultReadOnly returns true.

Using Query.SetReadOnly(true) or Criteria.SetReadOnly(true) works well when a single HQL query or criteria loads all the entities and initializes all the proxies and collections that the application needs to be read-only.

When it is not possible to load and initialize all necessary entities in a single query or criteria, you can temporarily change the session default to load entities as read-only before the query is executed. Then you can explicitly initialize proxies and collections before restoring the session default.

using (ISession session = factory.OpenSession())
using (ITransaction tx = session.BeginTransaction())
{
    session.DefaultReadOnly = true;
    Contract contract = session
        .CreateQuery("from Contract where CustomerName = 'Sherman'")
        .UniqueResult<Contract>();
    NHibernate.Initialize(contract.Plan);
    NHibernate.Initialize(contract.Variations);
    NHibernate.Initialize(contract.Notes);
    session.DefaultReadOnly = false;
    ...
    tx.Commit();
}

If Session.DefaultReadOnly returns true, then you can use Query.SetReadOnly(false) and Criteria.SetReadOnly(false) to override this session setting and load entities that are not read-only.

To make a persistent entity or proxy read-only, call:

Session.SetReadOnly(entityOrProxy, true)

To change a read-only entity or proxy of a mutable class so it is no longer read-only, call:

Session.SetReadOnly(entityOrProxy, false)

To throw away non-flushed changes and make the persistent entity consistent with its database representation, call:

Session.Refresh(entity);

To flush changes made before or while the entity was read-only and make the database representation consistent with the current state of the persistent entity:

// evict the read-only entity so it is detached
session.Evict(entity);

// make the detached entity (with the non-flushed changes) persistent
session.Update(entity);

// now entity is no longer read-only and its changes can be flushed
s.Flush();

When a persistent object is read-only, NHibernate does not dirty-check simple properties.

NHibernate will not synchronize simple property state changes to the database. If you have automatic versioning, NHibernate will not increment the version if any simple properties change.

using (ISession session = factory.OpenSession())
using (ITransaction tx = session.BeginTransaction())
{
    // get a contract and make it read-only
    Contract contract = session.Get<Contract>(contractId);
    session.SetReadOnly(contract, true);

    // contract.CustomerName is "Sherman"
    contract.CustomerName = "Yogi";
    tx.Commit();

    tx = session.BeginTransaction();

    contract = session.Get<Contract>(contractId);
    // contract.CustomerName is still "Sherman"
    ...
    tx.Commit();
}