NCache 4.3 - Online Documentation


NCache provides a second level or process level distributed cache for NHibernate by implementing ICacheProvider and ICache interfaces. You can plug-in NCache to your existing NHibernate application without any code change. Just change your NHibernate configuration file to plug-in NCache as your cache provider and you're all set to start using distributed caching.
Follow these steps to use NCache with NHibernate:
  • Register 'nhibernate' configuration sections in the <configSections> of the web.config or app.config as follows:
<section name="hibernate-configuration" type="NHibernate.Cfg.ConfigurationSectionHandler,
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  • Provide application id in appSetting section:
            <add key="ncache.application_id" value="myapp"/>
  • Define section details for <nhibernate> as follows:
    <hibernate-configuration xmlns = "urn:nhibernate-configuration-2.2">
    <bytecode-provider type="lcg"/>
    <reflection-optimizer use="true"/>
      <property name="connection.provider"> NHibernate.Connection.DriverConnectionProvider
      <property name="connection.isolation">ReadCommitted</property>
      <property name="dialect">NHibernate.Dialect.MsSql2008Dialect</property>
      <property name="connection.driver_class">NHibernate.Driver.OleDbDriver</property>
      <property name="connection.connection_string">Provider=SQLOLEDB; Data Source=;
                    Initial Catalog=Northwind;User ID=sp; Password=12345</property>
      <property name="cache.provider_class">
                    Alachisoft.NCache.Integrations.NHibernate.Cache </property>
      <property name="proxyfactory.factory_class">
                    NHibernate.Bytecode.DefaultProxyFactoryFactory, NHibernate </property>
      <property name="cache.use_second_level_cache">true</property>
      <property name="cache.use_query_cache" >true</property>
      <property name="show_sql">true</property>
  1. Add following section in NCacheNHibernate.xml file you can place this file in the config folder of NCache or in bin folder of your application:
  <application-config application-id="myapp" enable-cache-exception="true" default-region-name="default" 
  <region name="AbsoluteExpirationRegion" cache-name="myCache" priority="Default" expiration-type="sliding" 
    expiration-period="180" use-async="false"  />
  <region name="default" cache-name="myCache" priority="default" expiration-type="none" expiration-period="0" 
  <dependency entity-name="nhibernator.BLL.Customer" type="oledb" sql-statement="select ContactName from 
  dbo.Customers where CustomerID =?" cache-key-format="depdency.customer:[pk]"/>
The above example of app.config or web.config contains the following options for you to configure. Each of them is explained below as well.
cache.provider_class: This option lets you specify that NCache is your second level cache provider. You need to mention two classes which implement NHibernate.Cache.ICacheProvider and NHibernate.Cache.ICache interfaces respectively. This is how NHibernate knows how to call this second level cache.
ncache.application_id: This option lets you specify application id of current NHibernate application for NCache. This id will be than used to select configurations for current application from NCacheNhibernate.xml.
NCacheNHibernate.xml  contains all the configurations used by NCache provider for NHibernate. NCacheNHibernate.xml contains following configurable options:
This section lets you specify configuration for NCache use for a particular application.
Multiple application configurations can be specified in NCacheNHibernate.xml. Any NHibernate application will use one of the specified configuration based on the application-id specified in applications app.config/web.config file.
Following are the configurable options in application-config section.
application-id: This options let you specify the unique id for current application-config. This id is used to select appropriate configuration for a particular application.
enable-cache-exception: Identifies whether the exceptions if occurred in NCache will be propagated to NHibernate provider.
default-region-name: Allows to specify a default region for the application. If a particular region's configurations are not fount default region's configurations will be used. Specified default region's configuration must exist in cache-regions section.
key-case-sensitivity: This option allows to specify whether cache keys will be case sensitive or not. This option has to be configured according to database used. If database is case-sensitive set this option true, otherwise false.
    This sections lets you configure multiple cache regions for NHibernate application. Each region's configuration is specified in region tag.
This tag contains the configurations for one particular region. Following options can be configured for any particular region.
name: Each region is identified by its name. Name of the region should be unique.
cache-name: This option allows to specify NCache's cache name to be used for this region.
priority: The priority you want to use for items cached. The possible values are :
  •     Default
  •     Low
  •     BelowNormal
  •     Normal
  •     AboveNormal
  •     High
  •     NotRemovable
expiration-type: This options allows to specify type of expiration for any item in this region. Possible values are absolute/sliding/none.
expiraion-period: Allows to specify expiration period if absolute/sliding expiration is configured. Its value should be greater than 0.
This section lets you specify database dependencies for current NHibernate application.
dependency: Each dependency is configured in dependency tag. Multiple tags can be configured for multiple dependencies. Following options can be configured for each dependency.
entity-name: Dependencies are added based on the fully qualified name of classes. This option allows to specify name of class for which current dependency is to be added.
type: Allows to specify database dependency type. Possible values are sql/oracle/oledb.
sql-statement: Allows to specify sql statement to be used for building NCache's database dependency.
cache-key-format: This option is used to configure cache key format for any item of current entity type. Cache key format should include "[pk]" in it, which will be replaced with the primary key of record. cache-key-format may also include "[en]" which will be replaced with entity name. Default value of cache key format is "NHibernateNCache:[en] #[pk]".
composite-key-separator: If the records of current entity have composite key as primary key, cache-key can be formed by combining all keys separated by this composite-key-separator. composite-key-separator must be of one character length. Its default value is "$".
  • Calling new Configuration() reads the <nhibernate> section only.
  • Calling no-parameter version of cfg.Configure() configures NHibernate from app.config if it contains <nhibernate-configuration>, otherwise hibernate.cfg.xml is used.
See Also
© Copyright  2014 Alachisoft. All rights reserved.