Because NHibernate is designed to operate in many different environments, there are a large number of configuration parameters. Fortunately, most have sensible default values and NHibernate is distributed with an example App.config file (found in src\NHibernate.Test) that shows the various options. You usually only have to put that file in your project and customize it.
An instance of NHibernate.Cfg.Configuration represents an entire set of mappings of an application's .NET types to a SQL database. The Configuration is used to build an (immutable) ISessionFactory. The mappings are compiled from various XML mapping files.
You may obtain a Configuration instance by instantiating it directly. Here is an example of setting up a datastore from mappings defined in two XML configuration files:
Configuration cfg = new Configuration()
.AddFile("Item.hbm.xml")
.AddFile("Bid.hbm.xml");An alternative (sometimes better) way is to let NHibernate load a mapping file from an embedded resource:
Configuration cfg = new Configuration()
.AddClass(typeof(NHibernate.Auction.Item))
.AddClass(typeof(NHibernate.Auction.Bid));Then NHibernate will look for mapping files named NHibernate.Auction.Item.hbm.xml and NHibernate.Auction.Bid.hbm.xml embedded as resources in the assembly that the types are contained in. This approach eliminates any hardcoded filenames.
Another alternative (probably the best) way is to let NHibernate load all of the mapping files contained in an Assembly:
Configuration cfg = new Configuration()
.AddAssembly( "NHibernate.Auction" );Then NHibernate will look through the assembly for any resources that end with .hbm.xml. This approach eliminates any hardcoded filenames and ensures the mapping files in the assembly get added.
If a tool like Visual Studio .NET or NAnt is used to build the assembly, then make sure that the .hbm.xml files are compiled into the assembly as Embedded Resources.
A Configuration also specifies various optional properties:
var props = new Dictionary<string, string>();
...
Configuration cfg = new Configuration()
.AddClass(typeof(NHibernate.Auction.Item))
.AddClass(typeof(NHibernate.Auction.Bind))
.SetProperties(props);A Configuration is intended as a configuration-time object, to be discarded once an ISessionFactory is built.
When all mappings have been parsed by the Configuration, the application must obtain a factory for ISession instances. This factory is intended to be shared by all application threads:
ISessionFactory sessions = cfg.BuildSessionFactory();
However, NHibernate does allow your application to instantiate more than one ISessionFactory. This is useful if you are using more than one database.
An ISessionFactory may open an ISession on a user-provided ADO.NET connection. This design choice frees the application to obtain ADO.NET connections wherever it pleases:
var conn = myApp.GetOpenConnection(); var session = sessions.OpenSession(conn); // do some data access work
The application must be careful not to open two concurrent ISessions on the same ADO.NET connection!
Alternatively, you can have the ISessionFactory open connections for you. The ISessionFactory must be provided with ADO.NET connection properties in one of the following ways:
Pass an instance of IDictionary mapping property names to property values to Configuration.SetProperties().
Include <property> elements in a configuration section in the application configuration file. The section should be named hibernate-configuration and its handler set to NHibernate.Cfg.ConfigurationSectionHandler. The XML namespace of the section should be set to urn:nhibernate-configuration-2.2.
Include <property> elements in hibernate.cfg.xml (discussed later).
If you take this approach, opening an ISession is as simple as:
ISession session = sessions.OpenSession(); // open a new Session // do some data access work, an ADO.NET connection will be used on demand
All NHibernate property names and semantics are defined on the class NHibernate.Cfg.Environment. We will now describe the most important settings for ADO.NET connection configuration.
NHibernate will obtain (and pool) connections using an ADO.NET data provider if you set the following properties:
Table 3.1. NHibernate ADO.NET Properties
| Property name | Purpose |
|---|---|
| connection.provider |
The type of a custom IConnectionProvider implementation.
eg. full.classname.of.ConnectionProvider if the Provider is built into NHibernate, or full.classname.of.ConnectionProvider, assembly if using an implementation of IConnectionProvider not included in NHibernate. The default is NHibernate.Connection.DriverConnectionProvider. |
| connection.driver_class |
The type of a custom IDriver, if using DriverConnectionProvider.
eg. full.classname.of.Driver if the Driver is built into NHibernate, or full.classname.of.Driver, assembly if using an implementation of IDriver not included in NHibernate. This is usually not needed, most of the time the dialect will take care of setting the IDriver using a sensible default. See the API documentation of the specific dialect for the defaults. |
| connection.connection_string | Connection string to use to obtain the connection. |
| connection.connection_string_name | The name of the connection string (defined in <connectionStrings> configuration file element) to use to obtain the connection. |
| connection.isolation |
Set the ADO.NET transaction isolation level. Check
System.Data.IsolationLevel for meaningful values
and the database's documentation to ensure that level is supported.
eg. Chaos | ReadCommitted | ReadUncommitted | RepeatableRead | Serializable | Unspecified |
| connection.release_mode |
Specify when NHibernate should release ADO.NET connections.
See Section 12.7, “Connection Release Modes”.
eg. auto (default) | on_close | after_transaction Note that for ISessions obtained through ISessionFactory.GetCurrentSession, the ICurrentSessionContext implementation configured for use may control the connection release mode for those ISessions. See Section 2.3, “Contextual Sessions”. |
| prepare_sql |
Specify to prepare DbCommands generated by NHibernate.
Defaults to false.
eg. true | false |
| command_timeout |
Specify the default timeout in seconds of DbCommands
generated by NHibernate. Negative values disable it.
eg. 30 |
| adonet.batch_size |
Specify the batch size to use when batching update statements. Setting this to 0
(the default) disables the functionality.
See Section 21.6, “Batch updates”.
eg. 20 |
| order_inserts |
Enable ordering of insert statements for the purpose of more efficient batching. Defaults
to true if batching is enabled, false otherwise.
eg. true | false |
| order_updates |
Enable ordering of update statements for the purpose of more efficient batching. Defaults
to true if batching is enabled, false otherwise.
eg. true | false |
| adonet.batch_versioned_data |
If batching is enabled, specify that versioned data can also be batched. Requires a dialect which
batcher correctly returns rows count. Defaults to false.
eg. true | false |
| adonet.factory_class |
The class name of a IBatcherFactory implementation.
This is usually not needed, most of the time the driver will take care of setting the IBatcherFactory using a sensible default according to the database capabilities. eg. classname.of.BatcherFactory, assembly |
| adonet.wrap_result_sets |
Some database vendor data reader implementation have inefficient columnName-to-columnIndex
resolution. Enabling this setting allows to wrap them in a data reader that will cache those
resolutions. Defaults to false.
eg. true | false |
This is an example of how to specify the database connection properties inside a web.config:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="hibernate-configuration"
type="NHibernate.Cfg.ConfigurationSectionHandler, NHibernate" />
</configSections>
<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
<session-factory>
<property name="dialect">NHibernate.Dialect.MsSql2012Dialect</property>
<property name="connection.connection_string">
Server=(local);initial catalog=theDb;Integrated Security=SSPI
</property>
<property name="connection.isolation">ReadCommitted</property>
</session-factory>
</hibernate-configuration>
<!-- other app specific config follows -->
</configuration>NHibernate relies on the ADO.NET data provider implementation of connection pooling.
You may define your own plug-in strategy for obtaining ADO.NET connections by implementing the interface NHibernate.Connection.IConnectionProvider. You may select a custom implementation by setting connection.provider.
By default, NHibernate attempts to read the hibernate-configuration section through the .Net ConfigurationManager. Some environments do not support it, so NHibernate provides a way to set a custom configuration provider, through the NHibernate.Cfg.ConfigurationProvider.Current property.
To disable the configuration provider, in case you configure NHibernate entirely programmatically, set this property to null.
ConfigurationProvider.Current = null;
To provide directly the System.Configuration.Configuration instance to use, assign the Current property with an instance of NHibernate.Cfg.SystemConfigurationProvider built with your Configuration instance.
ConfigurationProvider.Current = new SystemConfigurationProvider(yourConfig);
You may also derive a custom provider from NHibernate.Cfg.ConfigurationProvider, implements its abstract methods, and assign an instance of your custom provider to the NHibernate.Cfg.ConfigurationProvider.Current property.
Changes of the ConfigurationProvider.Current property value are to be done very early in the application lifecycle, before any other call on a NHibernate API. Otherwise they may not be taken into account.
There are a number of other properties that control the behaviour of NHibernate at runtime. All are optional and have reasonable default values.
Table 3.2. NHibernate Configuration Properties
| Property name | Purpose |
|---|---|
| dialect |
The class name of a NHibernate Dialect - enables
certain platform dependent features. See Section 3.6.1, “SQL Dialects”.
eg. full.classname.of.Dialect, assembly |
| default_catalog |
Qualify unqualified table names with the given catalog name
in generated SQL.
eg. CATALOG_NAME |
| default_schema |
Qualify unqualified table names with the given schema/table-space
in generated SQL.
eg. SCHEMA_NAME |
| max_fetch_depth |
Set a maximum "depth" for the outer join fetch tree
for single-ended associations (one-to-one, many-to-one).
A 0 disables default outer join fetching.
eg. recommended values between 0 and 3 |
| cache.use_second_level_cache |
Enable the second level cache. Requires specifying a cache.provider_class.
See Chapter 27, NHibernate.Caches. Defaults to false.
eg. true | false |
| cache.provider_class |
The class name of a ICacheProvider implementation.
eg. classname.of.CacheProvider, assembly |
| cache.use_minimal_puts |
Optimize second-level cache operation to minimize writes, at the
cost of more frequent reads (useful for clustered caches).
Defaults to false.
eg. true | false |
| cache.use_query_cache |
Enable the query cache, individual queries still have to be set cacheable.
Defaults to false.
eg. true | false |
| cache.query_cache_factory |
The class name of a custom IQueryCacheFactory implementation.
Defaults to the built-in StandardQueryCacheFactory.
eg. classname.of.QueryCacheFactory, assembly |
| cache.read_write_lock_factory |
Specify the cache lock factory to use for read-write cache regions.
Defaults to the built-in async cache lock factory.
eg. async, or sync, or classname.of.CacheLockFactory, assembly with custom implementation of ICacheReadWriteLockFactory async uses a single writer multiple readers locking mechanism supporting asynchronous operations. sync uses a single access locking mechanism which will throw on asynchronous operations but may have better performances than the async provider for applications using the .Net Framework (4.8 and below). |
| cache.region_prefix |
A prefix to use for second-level cache region names.
eg. prefix |
| cache.default_expiration |
The default expiration delay in seconds for cached entries, for providers supporting
this setting.
eg. 300 |
| query.substitutions |
Mapping from tokens in NHibernate queries to SQL tokens
(tokens might be function or literal names, for example).
eg. hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC |
| query.default_cast_length |
Set the default length used in casting when the target type is length bound and
does not specify it. Defaults to 4000, automatically trimmed down
according to dialect type registration.
eg. 255 |
| query.default_cast_precision |
Set the default precision used in casting when the target type is decimal and
does not specify it. Defaults to 28, automatically trimmed down
according to dialect type registration.
eg. 19 |
| query.default_cast_scale |
Set the default scale used in casting when the target type is decimal and
does not specify it. Defaults to 10, automatically trimmed down
according to dialect type registration.
eg. 5 |
| query.startup_check |
Should named queries be checked during startup (the default is enabled).
eg. true | false |
| query.throw_never_cached |
Should queries set as cacheable raise an error if they reference an entity using the cache
Section 21.2.5, “Strategy: never” (the default is enabled).
eg. true | false Disabling this setting causes NHibernate to ignore the caching of such queries without raising an error. Furthermore NHibernate will log a warning on cacheable queries referencing an entity using the never cache strategy. |
| query.factory_class |
The class name of a custom IQueryTranslatorFactory implementation
(HQL query parser factory). Defaults to the built-in
ASTQueryTranslatorFactory.
eg. classname.of.QueryTranslatorFactory, assembly |
| query.linq_provider_class |
The class name of a custom INhQueryProvider implementation
(LINQ provider). Defaults to the built-in DefaultQueryProvider.
eg. classname.of.LinqProvider, assembly |
| query.query_model_rewriter_factory |
The class name of a custom IQueryModelRewriterFactory implementation
(LINQ query model rewriter factory). Defaults to null (no rewriter).
eg. classname.of.QueryModelRewriterFactory, assembly |
| query.pre_transformer_registrar |
The class name of the LINQ query pre-transformer registrar, implementing
IExpressionTransformerRegistrar. Defaults to null (no registrar).
eg. classname.of.ExpressionTransformerRegistrar, assembly |
| linqtohql.generatorsregistry |
The class name of a custom ILinqToHqlGeneratorsRegistry implementation.
Defaults to the built-in DefaultLinqToHqlGeneratorsRegistry. See
Section 18.8.2, “Adding a custom generator”.
eg. classname.of.LinqToHqlGeneratorsRegistry, assembly |
| linqtohql.legacy_preevaluation |
Whether to use the legacy pre-evaluation or not in Linq queries. Defaults to true.
eg. true | false Legacy pre-evaluation is causing special properties or functions like DateTime.Now or Guid.NewGuid() to be always evaluated with the .Net runtime and replaced in the query by parameter values. The new pre-evaluation allows them to be converted to HQL function calls which will be run on the db side. This allows for example to retrieve the server time instead of the client time, or to generate UUIDs for each row instead of an unique one for all rows. The new pre-evaluation will likely be enabled by default in the next major version (6.0). |
| linqtohql.fallback_on_preevaluation |
When the new pre-evaluation is enabled, should methods which translation is not supported by the current
dialect fallback to pre-evaluation? Defaults to false.
eg. true | false When this fallback option is enabled while legacy pre-evaluation is disabled, properties or functions like DateTime.Now or Guid.NewGuid() used in Linq expressions will not fail when the dialect does not support them, but will instead be pre-evaluated. When this fallback option is disabled while legacy pre-evaluation is disabled, properties or functions like DateTime.Now or Guid.NewGuid() used in Linq expressions will fail when the dialect does not support them. This option has no effect if the legacy pre-evaluation is enabled. |
| sql_exception_converter |
The class name of a custom ISQLExceptionConverter implementation.
Defaults to Dialect.BuildSQLExceptionConverter().
eg. classname.of.SQLExceptionConverter, assembly |
| show_sql |
Write all SQL statements to console. Defaults to false.
eg. true | false |
| format_sql |
Log formatted SQL. Defaults to false.
eg. true | false |
| use_sql_comments |
Generate SQL with comments. Defaults to false.
eg. true | false |
| hbm2ddl.auto |
Automatically export schema DDL to the database when the
ISessionFactory is created. With
create-drop, the database schema
will be dropped when the ISessionFactory
is closed explicitly.
eg. create | create-drop | update | validate |
| hbm2ddl.keywords |
Automatically import reserved/keywords from the database when the
ISessionFactory is created.
none : disable any operation regarding RDBMS KeyWords (the default). keywords : imports all RDBMS KeyWords where the Dialect can provide the implementation of IDataBaseSchema. auto-quote : imports all RDBMS KeyWords and auto-quote all table-names/column-names. eg. none | keywords | auto-quote |
| hbm2ddl.throw_on_update |
When hbm2ddl.auto is update, whether to throw or not on schema auto-update failures.
Disabled by default.
eg. true | false |
| use_proxy_validator |
Enables or disables validation of interfaces or classes specified
as proxies. Enabled by default.
eg. true | false |
| proxyfactory.factory_class |
The class name of a custom IProxyFactoryFactory implementation.
Defaults to the built-in StaticProxyFactoryFactory.
eg. classname.of.ProxyFactoryFactory, assembly |
| collectiontype.factory_class |
The class name of a custom ICollectionTypeFactory implementation.
Defaults to the built-in DefaultCollectionTypeFactory.
eg. classname.of.CollectionTypeFactory, assembly |
| transaction.factory_class |
The class name of a custom ITransactionFactory implementation.
Defaults to the built-in AdoNetWithSystemTransactionFactory.
eg. classname.of.TransactionFactory, assembly |
| transaction.use_connection_on_system_prepare |
When a system transaction is being prepared, is using connection during this process enabled?
Default is true, for supporting FlushMode.Commit with transaction factories supporting system transactions. But this requires enlisting additional connections, retaining disposed sessions and their connections until transaction end, and may trigger undesired transaction promotions to distributed. Set to false for disabling using connections from system transaction preparation, while still benefiting from FlushMode.Auto on querying. See Section 12.8, “Transaction scopes (System.Transactions)”. eg. true | false |
| transaction.system_completion_lock_timeout |
Timeout duration in milliseconds for the system transaction completion lock.
When a system transaction completes, it may have its completion events running on concurrent threads, after scope disposal. This occurs when the transaction is distributed. This notably concerns ISessionImplementor.AfterTransactionCompletion(bool, ITransaction). NHibernate protects the session from being concurrently used by the code following the scope disposal with a lock. To prevent any application freeze, this lock has a default timeout of five seconds. If the application appears to require longer (!) running transaction completion events, this setting allows to raise this timeout. -1 disables the timeout. eg. 10000 |
| transaction.auto_join |
Should sessions check on every operation whether there is an ongoing system transaction or not, and enlist
into it if any?
Default is true. It can also be controlled at session opening, with ISessionFactory.WithOptions. A session can also be instructed to explicitly join the current transaction by calling ISession.JoinTransaction. This setting has no effect when using a transaction factory that is not system transactions aware. eg. false |
| default_flush_mode |
The default FlushMode, Auto when not specified.
See Section 10.6, “Flush”.
eg. Manual | Commit | Auto | Always |
| default_batch_fetch_size |
The default batch fetch size to use when lazily loading an entity or collection.
Defaults to 1. See Section 21.1.5, “Using batch fetching”.
eg. 20 |
| current_session_context_class |
The class name of an ICurrentSessionContext implementation.
See Section 2.3, “Contextual Sessions”.
eg. classname.of.CurrentSessionContext, assembly |
| id.optimizer.pooled.prefer_lo |
When using an enhanced id generator and pooled optimizers (see
Section 5.1.5.9, “Enhanced identifier generators”), prefer interpreting the database
value as the lower (lo) boundary. The default is to interpret it as the high boundary.
eg. true | false |
| generate_statistics |
Enable statistics collection within ISessionFactory.Statistics property.
Defaults to false.
eg. true | false |
| track_session_id |
Set whether the session id should be tracked in logs or not. When true, each
session will have an unique Guid that can be retrieved with
ISessionImplementor.SessionId, otherwise ISessionImplementor.SessionId
will be Guid.Empty.
Session id is used for logging purpose and can also be retrieved on the static property NHibernate.Impl.SessionIdLoggingContext.SessionId, when tracking is enabled. Disabling tracking by setting track_session_id to false increases performances. Default is true. eg. true | false |
| sql_types.keep_datetime |
Since NHibernate v5.0 and if the dialect supports it, DbType.DateTime2
is used instead of DbType.DateTime. This may be disabled by setting
sql_types.keep_datetime to true.
Defaults to false.
eg. true | false |
| firebird.disable_parameter_casting | Firebird with FirebirdSql.Data.FirebirdClient may be unable to determine the type of parameters in many circumstances, unless they are explicitly casted in the SQL query. To avoid this trouble, the NHibernate FirebirdClientDriver parses SQL commands for detecting parameters in them and adding an explicit SQL cast around parameters which may trigger the issue. Defaults to false. For disabling this behavior, set this setting to true. eg. true | false |
| oracle.use_n_prefixed_types_for_unicode | Oracle has a dual Unicode support model. Either the whole database use an Unicode encoding, and then all string types will be Unicode. In such case, Unicode strings should be mapped to non N prefixed types, such as Varchar2. This is the default. Or N prefixed types such as NVarchar2 are to be used for Unicode strings, the others type are using a non Unicode encoding. In such case this setting needs to be set to true. See Implementing a Unicode Solution in the Database. This setting applies only to Oracle dialects and ODP.Net managed or unmanaged driver. eg. true | false |
| oracle.use_binary_floating_point_types | Set whether NHibernate should map .Net double and float to Oracle BINARY_DOUBLE and BINARY_FLOAT types or use Oracle DOUBLE and FLOAT types. Oracle 10g introduced BINARY_DOUBLE and BINARY_FLOAT types which are compatible with .NET double and float types, while Oracle DOUBLE and FLOAT are not. Oracle DOUBLE and FLOAT types do not conform to the IEEE standard as they are internally implemented as NUMBER type, which makes them an exact numeric type. eg. true for using Oracle BINARY_DOUBLE and BINARY_FLOAT types | false for using Oracle DOUBLE and FLOAT types. false by default. See ANSI SQL data types. |
| oracle.suppress_decimal_invalid_cast_exception | This setting specifies whether to suppress or not the InvalidCastException and return a rounded-off 28 precision value if the Oracle NUMBER value has more than a 28 precision. eg. true for suppressing the exception | false for letting the exception be raised. false by default. See SuppressGetDecimalInvalidCastException. This setting works only with ODP.NET 19.10 or newer. |
| odbc.explicit_datetime_scale |
This may need to be set to 3 if you are using the OdbcDriver
with MS SQL Server 2008+.
This is intended to work around issues like: System.Data.Odbc.OdbcException : ERROR [22008] [Microsoft][SQL Server Native Client 11.0] Datetime field overflow. Fractional second precision exceeds the scale specified in the parameter binding.
eg. 3 |
| sqlite.binaryguid | SQLite can store GUIDs in binary or text form, controlled by the BinaryGuid connection string parameter (default is 'true'). The BinaryGuid setting will affect how to cast GUID to string in SQL. NHibernate will attempt to detect this setting automatically from the connection string, but if the connection or connection string is being handled by the application instead of by NHibernate, you can use the sqlite.binaryguid NHibernate setting to override the behavior. The value can be true or false. |
| nhibernate-logger |
The class name of an ILoggerFactory implementation. It allows using another
logger than log4net.
The default is not defined, which causes NHibernate to search for log4net assembly. If this search succeeds, NHibernate will log with log4net. Otherwise, its internal logging will be disabled. This is a very special system-level property. It can only be set through an appSetting named nhibernate-logger in the application configuration file. It cannot be set neither with NHibernate.Cfg.Environment class, nor be defined in the <hibernate-configuration> section of the application configuration file, nor supplied by using Configuration.SetProperties, nor set in the hibernate.cfg.xml configuration file. Alternatively to using the setting, a logger factory can be programmatically supplied by using NHibernateLogger.SetLoggersFactory. eg. classname.of.LoggerFactory, assembly |
You should always set the 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.
Table 3.3. NHibernate SQL Dialects (dialect)
| RDBMS | Dialect | Remarks |
|---|---|---|
| DB2 | NHibernate.Dialect.DB2Dialect | |
| DB2 for iSeries (OS/400) | NHibernate.Dialect.DB2400Dialect | |
| Firebird | NHibernate.Dialect.FirebirdDialect | Set driver_class to NHibernate.Driver.FirebirdClientDriver for Firebird ADO.NET provider 2.0. |
| Informix | NHibernate.Dialect.InformixDialect | |
| Informix 9.40 | NHibernate.Dialect.InformixDialect0940 | |
| Informix 10.00 | NHibernate.Dialect.InformixDialect1000 | |
| Ingres | NHibernate.Dialect.IngresDialect | |
| Ingres 9 | NHibernate.Dialect.Ingres9Dialect | |
| Microsoft SQL Server 7 | NHibernate.Dialect.MsSql7Dialect | |
| Microsoft SQL Server 2000 | NHibernate.Dialect.MsSql2000Dialect | |
| Microsoft SQL Server 2005 | NHibernate.Dialect.MsSql2005Dialect | |
| Microsoft SQL Server 2008 | NHibernate.Dialect.MsSql2008Dialect | |
| Microsoft SQL Azure Server 2008 | NHibernate.Dialect.MsSqlAzure2008Dialect | |
| Microsoft SQL Server 2012 | NHibernate.Dialect.MsSql2012Dialect | |
| Microsoft SQL Server Compact Edition | NHibernate.Dialect.MsSqlCeDialect | |
| Microsoft SQL Server Compact Edition 4.0 | NHibernate.Dialect.MsSqlCe40Dialect | |
| MySQL 3 or 4 | NHibernate.Dialect.MySQLDialect | |
| MySQL 5 | NHibernate.Dialect.MySQL5Dialect | |
| MySQL 5 Inno DB | NHibernate.Dialect.MySQL5InnoDBDialect | |
| MySQL 5.5 | NHibernate.Dialect.MySQL55Dialect | |
| MySQL 5.5 Inno DB | NHibernate.Dialect.MySQL55InnoDBDialect | |
| Oracle | NHibernate.Dialect.Oracle8iDialect | |
| Oracle 9i | NHibernate.Dialect.Oracle9iDialect | |
| Oracle 10g, Oracle 11g | NHibernate.Dialect.Oracle10gDialect | |
| Oracle 12c | NHibernate.Dialect.Oracle12cDialect | |
| PostgreSQL | NHibernate.Dialect.PostgreSQLDialect | |
| PostgreSQL 8.1 | NHibernate.Dialect.PostgreSQL81Dialect | This dialect supports FOR UPDATE NOWAIT available in PostgreSQL 8.1. |
| PostgreSQL 8.2 | NHibernate.Dialect.PostgreSQL82Dialect | This dialect supports IF EXISTS keyword in DROP TABLE and DROP SEQUENCE available in PostgreSQL 8.2. |
| PostgreSQL 8.3 | NHibernate.Dialect.PostgreSQL83Dialect | This dialect supports XML type. |
| SQLite | NHibernate.Dialect.SQLiteDialect |
Set driver_class to
NHibernate.Driver.SQLite20Driver
for System.Data.SQLite provider for .NET 2.0.
Due to the behavior of System.Data.SQLite with DateTime, consider using DateTimeFormatString=yyyy-MM-dd HH:mm:ss.FFFFFFF; in the SQLite connection string for preventing undesired time shifts with its default configuration. |
| Sybase Adaptive Server Anywhere 9 | NHibernate.Dialect.SybaseASA9Dialect | |
| Sybase Adaptive Server Enterprise 15 | NHibernate.Dialect.SybaseASE15Dialect | |
| Sybase SQL Anywhere 10 | NHibernate.Dialect.SybaseSQLAnywhere10Dialect | |
| Sybase SQL Anywhere 11 | NHibernate.Dialect.SybaseSQLAnywhere11Dialect | |
| Sybase SQL Anywhere 12 | NHibernate.Dialect.SybaseSQLAnywhere12Dialect |
Additional dialects may be available in the NHibernate.Dialect namespace.
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 configured (and the default behaviour overridden) by setting the fetch attribute in the XML mapping.
Outer join fetching may be disabled globally by setting the property max_fetch_depth to 0. A setting of 1 or higher enables outer join fetching for one-to-one and many-to-one associations which have been mapped with fetch="join".
See Section 21.1, “Fetching strategies” for more information.
In NHibernate 1.0, outer-join attribute could be used to achieve a similar effect. This attribute is now deprecated in favor of fetch.
You may integrate a process-level (or clustered) second-level cache system by implementing the interface NHibernate.Cache.ICacheProvider. You may select the custom implementation by setting cache.provider_class. See the Section 21.2, “The Second Level Cache” for more details.
You may define new NHibernate query tokens using query.substitutions. For example:
query.substitutions true=1, false=0
would cause the tokens true and false to be translated to integer literals in the generated SQL.
query.substitutions toLowercase=LOWER
would allow you to rename the SQL LOWER function.
Some properties are system-level properties. They can only be set manually by setting static properties of NHibernate.Cfg.Environment class or be defined in the <hibernate-configuration> section of the application configuration file, as direct sub-elements. These properties can neither be set using Configuration.SetProperties or the hibernate.cfg.xml configuration file, nor be set as <session-factory> properties.
Table 3.4. NHibernate system level properties
| Property name | Purpose |
|---|---|
| bytecode-provider | Specifies the bytecode provider to use to optimize the use of reflection in NHibernate. Use null to disable the optimization completely, lcg to use built-in lightweight code generation, or the assembly qualified class name of a custom IBytecodeProvider implementation. Defaults to lcg. <bytecode-provider
type="lcg|null|className" />You can also set this property by code by setting NHibernate.Cfg.Environment.BytecodeProvider before creating any NHibernate.Cfg.Configuration instance. |
| objects-factory | Specifies a custom objects factory to use for instantiating NHibernate dependencies. Use the assembly qualified class name of a custom IObjectsFactory implementation. <objects-factory
type="className" />You can also set this property by code by setting NHibernate.Cfg.Environment.ObjectsFactory before creating any NHibernate.Cfg.Configuration instance. |
| reflection-optimizer | Enables use of a runtime-generated class to set or get properties of an entity or component instead of using runtime reflection. The use of the reflection optimizer inflicts a certain startup cost on the application but should lead to better performance in the long run. Defaults to true. <reflection-optimizer
use="true|false"/>You can also set this property by code by setting NHibernate.Cfg.Environment.UseReflectionOptimizer before creating any NHibernate.Cfg.Configuration instance. |
NHibernate logs various events using Apache log4net.
You may download log4net from https://logging.apache.org/log4net/, or install it with NuGet. To use log4net you will need a log4net configuration section in the application configuration file. An example of the configuration section is distributed with NHibernate in the src/NHibernate.Test project.
We strongly recommend that you familiarize yourself with NHibernate's log messages. A lot of work has been put into making the NHibernate log as detailed as possible, without making it unreadable. It is an essential troubleshooting device. Also don't forget to enable SQL logging as described above (show_sql), it is your first step when looking for performance problems.
The interface NHibernate.Cfg.INamingStrategy allows you to specify a "naming standard" for database objects and schema elements.
You may provide rules for automatically generating database identifiers from .NET identifiers or for processing "logical" column and table names given in the mapping file into "physical" table and column names. This feature helps reduce the verbosity of the mapping document, eliminating repetitive noise (TBL_ prefixes, for example). The default strategy used by NHibernate is quite minimal.
You may specify a different strategy by calling Configuration.SetNamingStrategy() before adding mappings:
ISessionFactory sf = new Configuration()
.SetNamingStrategy(ImprovedNamingStrategy.Instance)
.AddFile("Item.hbm.xml")
.AddFile("Bid.hbm.xml")
.BuildSessionFactory();NHibernate.Cfg.ImprovedNamingStrategy is a built-in strategy that might be a useful starting point for some applications.
An alternative approach is to specify a full configuration in a file named hibernate.cfg.xml. This file can be used as a replacement for the <hibernate-configuration> sections of the application configuration file.
The XML configuration file is by default expected to be in your application directory. Here is an example:
<?xml version='1.0' encoding='utf-8'?>
<hibernate-configuration xmlns="urn:nhibernate-configuration-2.2">
<!-- an ISessionFactory instance -->
<session-factory>
<!-- properties -->
<property name="connection.connection_string">
Server=localhost;initial catalog=nhibernate;User Id=;Password=
</property>
<property name="show_sql">false</property>
<property name="dialect">NHibernate.Dialect.MsSql2012Dialect</property>
<!-- mapping files -->
<mapping resource="NHibernate.Auction.Item.hbm.xml" assembly="NHibernate.Auction" />
<mapping resource="NHibernate.Auction.Bid.hbm.xml" assembly="NHibernate.Auction" />
</session-factory>
</hibernate-configuration>Configuring NHibernate is then as simple as
ISessionFactory sf = new Configuration().Configure().BuildSessionFactory();
You can pick a different XML configuration file using
ISessionFactory sf = new Configuration()
.Configure("/path/to/config.cfg.xml")
.BuildSessionFactory();