Lesser Known NHibernate Session Methods

The NHibernate ISession, the core of NHibernate usage, has some methods which are quite misunderstood and underused, to name a few, Merge, Persist, Replicate and SaveOrUpdateCopy.

Their purpose is:

• Merge: copies properties from a transient entity to an eventually loaded entity with the same id in the first level cache; if there is no loaded entity with the same id, one will be loaded and placed in the first level cache first; if using version, the transient entity must have the same version as in the database;
• Persist: similar to Save or SaveOrUpdate, attaches a maybe new entity to the session, but does not generate an INSERT or UPDATE immediately and thus the entity does not get a database-generated id, it will only get it at flush time;
• Replicate: copies an instance from one session to another session, perhaps from a different session factory;
• SaveOrUpdateCopy: attaches a transient entity to the session and tries to save it.

Here are some samples of its use.

ISession session = ...;

AuthorDetails existingDetails = session.Get<AuthorDetails>(1);	//loads an entity and places it in the first level cache
AuthorDetails detachedDetails = new AuthorDetails { ID = existingDetails.ID, Name = "Changed Name" };	//a detached entity with the same ID as the existing one
Object mergedDetails = session.Merge(detachedDetails);	//merges the Name property from the detached entity into the existing one; the detached entity does not get attached

session.Flush();	//saves the existingDetails entity, since it is now dirty, due to the change in the Name property

AuthorDetails details = ...;
ISession session = ...;

session.Persist(details);	//details.ID is still 0

session.Flush();	//saves the details entity now and fetches its id

ISessionFactory factory1 = ...;
ISessionFactory factory2 = ...;

ISession session1 = factory1.OpenSession();
ISession session2 = factory2.OpenSession();

AuthorDetails existingDetails = session1.Get<AuthorDetails>(1);	//loads an entity

session2.Replicate(existingDetails, ReplicationMode.Overwrite);	//saves it into another session, overwriting any possibly existing one with the same id; other options are Ignore, where any existing record with the same id is left untouched, Exception, where an exception is thrown if there is a record with the same id and LatestVersion, where the latest version wins