You should always set the hibernate.dialect property to the correct NHibernate.Dialect.Dialect subclass for your database. This is not strictly essential unless you wish to use native or sequence primary key generation or pessimistic locking (with, eg. ISession.Lock() or IQuery.SetLockMode()). However, if you specify a dialect, NHibernate will use sensible defaults for some of the other properties listed above, saving you the effort of specifying them manually.

If your database supports ANSI or Oracle style outer joins, outer join fetching might increase performance by limiting the number of round trips to and from the database (at the cost of possibly more work performed by the database itself). Outer join fetching allows a graph of objects connected by many-to-one, one-to-many or one-to-one associations to be retrieved in a single SQL SELECT.

By default, the fetched graph when loading an objects ends at leaf objects, collections, objects with proxies, or where circularities occur.

For a particular association, fetching may be enabled or disabled (and the default behaviour overridden) by setting the outer-join attribute in the XML mapping.

Outer join fetching may be disabled globally by setting the property hibernate.use_outer_join to false. A setting of true enables outer join fetching for all one-to-one and many-to-one associations, which are, also by default, set to auto outer join. However, one-to-many associations and collections are never fetched with an outer-join, unless explicitly declared for each particular association. This behavior can also be overriden at runtime with Hibernate queries.

You may integrate a second-level cache system by implementing the interface NHibernate.Cache.ICacheProvider. You may select the custom implementation by setting hibernate.cache.provider_class.

You may define new Hibernate query tokens using hibernate.query.substitutions. For example:

hibernate.query.substitutions true=1, false=0

would cause the tokens true and false to be translated to integer literals in the generated SQL.

hibernate.query.substitutions toLowercase=LOWER

would allow you to rename the SQL LOWER function.

All XML mappings have to use the nhibernate-mapping-2.0 schema. The actual schema may be found in the NHibernate source directory, or as an Embedded Resource in NHibernate.dll. NHibernate will always use the Embedded Resource as the source for the schema.

To get intellisense while working with the hibernate-mapping xml inside of VisualStudio.NET you should copy the schema to the folder C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml

This element has four optional attributes. The schema attribute specifies that tables referred to by this mapping belong to the named schema. If specified, tablenames will be qualified by the given schema name. If missing, tablenames will be unqualified. The default-cascade attribute specifies what cascade style should be assumed for properties and collections which do not specify a cascade attribute. The auto-import attribute lets us use unqualified class names in the query language, by default. The default-access attribute tells us how to access property values.

 
<hibernate-mapping
         schema="schemaName" (1)
         default-cascade="none|save-update" (2)
         auto-import="true|false" (3)
         default-access="property|field|nosetter|ClassName" (4)
 >
			

If you have two persistent classes with the same (unqualified) name, you should set auto-import="false". NHibernate will throw an exception if you attempt to assign two classes to the same "imported" name.

You may declare a persistent class using the class element:

<class
        name="ClassName" (1)
        table="tableName"(2)
        discriminator-value="discriminator_value"(3)
        mutable="true|false"(4)
        schema="owner"(5)
        proxy="ProxyInterface"(6)
        dynamic-update="true|false"(7)
        dynamic-insert="true|false"(8)
        polymorphism="implicit|explicit"(9)
        where="arbitrary sql where condition"(10)
        persister="PersisterClass"(11)
/>

It is perfectly acceptable for the named persistent class to be an interface. You would then declare implementing classes of that interface using the <subclass> element. You may persist any inner class. You should specify the class name using the standard form ie. Eg.Foo+Bar.

Immutable classes, mutable="false", may not be updated or deleted by the application. This allows NHibernate to make some minor performance optimizations.

The optional proxy attribute enables lazy initialization of persistent instances of the class. NHibernate will initially return proxies generated by Castle.DynamicProxy which implement the named interface or extend the class. The actual persistent object will be loaded when a method of the proxy is invoked. See "Proxies for Lazy Initialization" below.

Implicit polymorphism means that instances of the class will be returned by a query that names any superclass or implemented interface or the class and that instances of any subclass of the class will be returned by a query that names the class itself. Explicit polymorphism means that class instances will be returned only be queries that explicitly name that class and that queries that name the class will return only instances of subclasses mapped inside this <class> declaration as a <subclass> or <joined-subclass>. For most purposes the default, polymorphism="implicit", is appropriate. Explicit polymorphism is useful when two different classes are mapped to the same table (this allows a "lightweight" class that contains a subset of the table columns).

The persister attribute lets you customize the persistence strategy used for the class. You may, for example, specify your own subclass of NHibernate.Persister.EntityPersister or you might even provide a completely new implementation of the interface NHibernate.Persister.IClassPersister that implements persistence via, for example, stored procedure calls, serialization to flat files or LDAP. See NHibernate.DomainModel.CustomPersister for a simple example (of "persistence" to a Hashtable).

Note that the dynamic-update and dynamic-insert settings are not inherited by subclasses and so may also be specified on the <subclass> or <joined-subclass> elements. These settings may increase performance in some cases, but might actually decrease performance in others. Use judiciously.

Mapped classes must declare the primary key column of the database table. Most classes will also have a Property holding the unique identifier of an instance. The <id> element defines the mapping from that property to the primary key column.

<id 
        name="propertyName" (1)
        type="typename" (2)
        column="column_name" (3)
        unsaved-value="any|none|null|id_value" (4)
        access="field|property|nosetter|ClassName"> (5)

        <generator class="generatorClass"/>
</id>		

If the name attribute is missing, it is assumed that the class has no identifier property.

The unsaved-value attribute is important! If the identfier property of your class does not default to null, then you should specify the actual default. This is especially important when using a System.ValueType such as System.Int32 or System.Guid as your <id> property. Make sure to explicity set this attribute because System.ValueType objects can not be null.

There is an alternative <composite-id> declaration to allow access to legacy data with composite keys. We strongly discourage its use for anything else.

<id name="Id" type="Int64" column="uid" unsaved-value="0">
        <generator class="NHibernate.Id.TableHiLoGenerator">
                <param name="table">uid_table</param>
                <param name="column">next_hi_value_column</param>
        </generator>
</id>

<id name="Id" type="Int64" column="cat_id">
        <generator class="hilo">
                <param name="table">hi_value</param>
                <param name="column">next_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>

<id name="Id" type="Int64" column="cat_id">
        <generator class="seqhilo">
                <param name="sequence">hi_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>

<id name="Id" type="String" column="cat_id">
        <generator class="uuid.hex">
                <param name="format">format_value</param>
                <param name="seperator">seperator_value</param>
        </generator>
</id>

<id name="Id" type="Int64" column="uid">
        <generator class="sequence">
                <param name="sequence">uid_sequence</param>
        </generator>
</id>

<id name="Id" type="Int64" column="uid" unsaved-value="0">
        <generator class="identity"/>
</id>

<composite-id
        name="propertyName"(1)
        class="ClassName"(2)
        unsaved-value="any|none"(3)
        access="field|property|nosetter|ClassName">

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName class="ClassName" column="column_name"/>
        ......
</composite-id>

For a table with a composite key, you may map multiple properties of the class as identifier properties. The <composite-id> element accepts <key-property> property mappings and <key-many-to-one> mappings as child elements.

<composite-id>
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>

Your persistent class must override Equals() and GetHashCode() to implement composite identifier equality. It must also be Serializable.

Unfortunately, this approach to composite identifiers means that a persistent object is its own identifier. There is no convenient "handle" other than the object itself. You must instantiate an instance of the persistent class itself and populate its identifier properties before you can Load() the persistent state associated with a composite key. We will describe a much more convenient approach where the composite identifier is implemented as a seperate class in TODO:LINKTOCOMPENENTS. The attributes described below apply only to this alternative approach:

The <discriminator> element is required for polymorphic persistence using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the table. The discriminator column contains marker values that tell the persistence layer what subclass to instantiate for a particular row. A restricted set of types may be used: String, Char, Int32, Byte, Int16, Boolean, YesNo, TrueFalse.

<discriminator
        column="discriminator_column"(1)
        type="discriminator_type"(2)
        force="true|false"(3)
/>

Actual values of the discriminator column are specified by the discriminator-value attribute of the <class> and <subclass> elements.

The force attribute is (only) useful if the table contains rows with "extra" discriminator values that are not mapped to a persistent class. This will not usually be the case.

The <version> element is optional and indicates that the table contains versioned data. This is particularly useful if you plan to use long transactions (see below).

<version
        column="version_column"(1)
        name="propertyName"(2)
        type="typename"(3)
        access="field|property|nosetter|ClassName"(4)
/>

Version numbers may be of type Int64, Int32, Int16, Ticks, Timestamp, or TimeSpan.

The optional <timestamp> element indicates that the table contains timestamped data. This is intended as an alternative to versioning. Timestamps are by nature a less safe implementation of optimistic locking. However, sometimes the application might use the timestamps in other ways.

<timestamp
        column="timestamp_column"(1)
        name="propertyName"(2)
        access="field|property|nosetter|ClassName"(3)
/>

Note that <timestamp> is equivalent to <version type="timestamp">.

The <property> element declares a persistent, property of the class.

<property
        name="propertyName"(1)
        column="column_name"(2)
        type="typename"(3)
        update="true|false"(4)
        insert="true|false"(5)
        formula="arbitrary SQL expression"(6)
        access="field|property|nosetter|ClassName"(7)
/>

typename could be:

If you do not specify a type, NHibernate will use reflection upon the named property to take a guess at the correct NHibernate type. NHibernate will try to interpret the name of the return class of the property getter using rules 2, 3, 4 in that order. However, this is not always enough. In certain cases you will still need the type attribute. (For example, to distinguish between NHibernate.DateTime and NHibernate.Timestamp, or to specify a custom type.)

The access attribute lets you control how NHibernate will access the value of the property at runtime. The value of the access attribute should be text formatted as access-strategy.naming-strategy. The .naming-stragey is not always required.

To understand the behaviour of various .NET language-level objects with respect to the persistence service, we need to classify them into two groups:

An entity exists independently of any other objects holding references to the entity. Contrast this with the usual .NET model where an unreferenced object is garbage collected. Entities must be explicitly saved and deleted (except that saves and deletions may be cascaded from a parent entity to its children). Entities support circular and shared references. They may also be versioned.

An entity's persistent state consists of references to other entities and instances of value types. Values are structs, collections, components and certain immutable objects. Unlike entities, values (in particular collections and components) are persisted and deleted by reachability. Since value objects (and structs) are persisted and deleted along with their containing entity they may not be independently versioned. Values have no independent identity, so they cannot be shared by two entities or collections.

All NHibernate types except collections support null semantics if the .NET type also supports it.

Up until now, we've been using the term "persistent class" to refer to entities. We will continue to do that. Strictly speaking, however, not all user-defined classes with persistent state are entities. A component is a user defined class with value semantics.

The basic types may be roughly categorized into three groups - System.ValueType types, System.Object types, and System.Object types for large objects. Just like the .NET Types, columns for System.ValueType types can not store null values and System.Object types can store null values.

For those of you coming over from Hibernate or using some of the tools to generate hbm.xml files that are intended for Hibernate, there is a Hibernate compatiblity layer for type names. A type="integer" will map to an Int32 NHibernateType, type="short" to an Int16 NHibernateType. To see all of the conversions you can view the source of static constructor of the class NHibernate.Type.TypeFactory.