diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml
index 24aa760ce0c..387dea6fd8c 100644
--- a/doc/reference/modules/nhibernate_caches.xml
+++ b/doc/reference/modules/nhibernate_caches.xml
@@ -9,7 +9,7 @@
NHibernate.Caches namespace contains several second-level cache providers for NHibernate.
- A cache is place where entities are kept after being loaded from the database; once cached, they can be
+ A cache is a place where entities are kept after being loaded from the database; once cached, they can be
retrieved without going to the database. This means that they are faster to (re)load.
@@ -35,6 +35,12 @@
the same entity without hitting the database each time; hence the performance gain.
+
+ Depending on the chosen cache provider, the second level cache may be actually shared between different session
+ factories. If you need to avoid this for some session factories, configure each of them with a different
+ cache.region_prefix. See .
+
+
Several cache providers have been contributed by NHibernate users:
@@ -44,7 +50,8 @@
Uses Bamboo.Prevalence as the cache provider. Open the
file Bamboo.Prevalence.license.txt for more information about its license;
- you can also visit its website.
+ you can also visit its website. This
+ provider is available for the .Net Framework only. Also see .
@@ -55,6 +62,7 @@
Uses System.Web.Caching.Cache as the cache provider. This means that you can
rely on ASP.NET caching feature to understand how it works. For more information, read (on the MSDN):
Caching Application Data.
+ This provider is available for the .Net Framework only. Also see .
@@ -67,16 +75,20 @@
expire when the relevant data in the database changes.
- SysCache2 requires Microsoft SQL Server 2000 or higher.
+ SysCache2 requires Microsoft SQL Server 2000 or higher. This provider is available for the .Net Framework only.
+
+
+ See .
- NHibernate.Caches.MemCache
+ NHibernate.Caches.EnyimMemcached
- Uses memcached. See memcached homepage
- for more information.
+ Uses Memcached. See memcached homepage
+ for more information on Memcached. This provider is available for the .Net Framework only. Also see
+ .
@@ -95,7 +107,32 @@
NHibernate.Caches.RtMemoryCache
- Uses System.Runtime.Caching.MemoryCache.Default as the cache provider.
+ Uses System.Runtime.Caching.MemoryCache.Default as the cache provider. This provider
+ is available for the .Net Framework only. See .
+
+
+
+
+ NHibernate.Caches.CoreMemoryCache
+
+
+ Uses Microsoft.Extensions.Caching.Memory.MemoryCache as the cache provider. This provider
+ is available as a .Net Standard NuGet package. See .
+
+
+
+
+ NHibernate.Caches.CoreDistributedCache
+
+
+ Uses Microsoft.Extensions.Caching.Abstractions.IDistributedCache implementations as the cache
+ provider. The implementation has to be provided through an IDistributedCacheFactory.
+ Distributed cache factories for Memcached, Redis, SqlServer
+ and Memory caches are available through their own package, prefixed by
+ NHibernate.Caches.CoreDistributedCache..
+
+
+ This provider is available as a .Net Standard NuGet package. See .
@@ -111,17 +148,16 @@
- Choose the cache provider you want to use and copy its assembly in your assemblies directory
- (NHibernate.Caches.Prevalence.dll or
- NHibernate.Caches.SysCache.dll).
+ Choose the cache provider you want to use and copy its assembly in your assemblies directory.
+ (For example, NHibernate.Caches.Prevalence.dll or
+ NHibernate.Caches.SysCache.dll.)
To tell NHibernate which cache provider to use, add in your NHibernate configuration file
(can be YourAssembly.exe.config or web.config or a
- .cfg.xml file, in the latter case the syntax will be different from what
- is shown below):
+ .cfg.xml file):
<property name="cache.provider_class">XXX</property>
<property name="cache.default_expiration">120</property>
@@ -204,6 +240,10 @@
file system where the Prevalence engine will save data. It can be relative to the current directory or a
full path. If the directory doesn't exist, it will be created.
+
+ The prevalenceBase setting can only be set programmatically through on the NHibernate
+ configuration object, by example with Configuration.SetProperty.
+
@@ -215,11 +255,12 @@
- expiration
+ cache.default_expiration
Number of seconds to wait before expiring each item.
- Takes precedence over cache.default_expiration.
- If none of them are defined, defaults to 300.
+ Defaults to 300. It can also be set programmatically on the NHibernate
+ configuration object under the name expiration, which then takes precedence
+ over cache.default_expiration.
@@ -233,8 +274,9 @@
priority
A numeric cost of expiring each item, where 1 is a low cost, 5 is the highest, and 3 is normal.
- Only values 1 through 5 are valid. 6 is a special value corresponding to
- NotRemovable, it should not be used.
+ Only values 1 through 6 are valid. 6 is a special value corresponding to
+ NotRemovable. This setting can only be set programmatically through on the
+ NHibernate configuration object, by example with Configuration.SetProperty.
@@ -276,11 +318,12 @@
- expiration
+ cache.default_expiration
Number of seconds to wait before expiring each item.
- Takes precedence over cache.default_expiration.
- If none of them are defined, defaults to 300.
+ Defaults to 300. It can also be set programmatically on the NHibernate
+ configuration object under the name expiration, which then takes precedence
+ over cache.default_expiration.
@@ -305,7 +348,7 @@
]]>
-
+
Table-based Dependency
@@ -362,7 +405,7 @@
-
+
Command-Based Dependencies
@@ -457,7 +500,7 @@
-
+
Aggregate Dependencies
@@ -501,7 +544,7 @@
-
+
Additional Settings
In addition to data dependencies for the cache regions, time based expiration policies can be specified
@@ -564,7 +607,15 @@
+
+
+ EnyimMemcached Configuration
+
+ Its configuration relies on the EnyimMemcached library own configuration, through its
+ enyim.com/memcached configuration section. See
+ project site.
+
@@ -577,11 +628,12 @@
- expiration
+ cache.default_expiration
Number of seconds to wait before expiring each item.
- Takes precedence over cache.default_expiration.
- If none of them are defined, defaults to 300.
+ Defaults to 300. It can also be set programmatically on the NHibernate
+ configuration object under the name expiration, which then takes precedence
+ over cache.default_expiration.
@@ -614,4 +666,284 @@
+
+ CoreMemoryCache Configuration
+
+ CoreMemoryCache relies on Microsoft.Extensions.Caching.Memory.MemoryCache for the
+ underlying implementation.
+ The following NHibernate configuration settings are available:
+
+
+
+
+ cache.default_expiration
+
+ Number of seconds to wait before expiring each item.
+ Defaults to 300. It can also be set programmatically on the NHibernate
+ configuration object under the name expiration, which then takes precedence
+ over cache.default_expiration.
+
+
+
+ cache.use_sliding_expiration
+
+ Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+ Defaults to false.
+
+
+
+
+
+ CoreMemoryCache has a config file section handler to allow configuring different expirations for
+ different regions, and configuring the MemoryCache expiration scan frequency.
+ Here is an example:
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
+ CoreDistributedCache Configuration
+
+ CoreDistributedCache relies on Microsoft.Extensions.Caching.Abstractions.IDistributedCache
+ implementations. The implementation has to be provided through an IDistributedCacheFactory, either
+ supplied through configuration or programmatically by affecting
+ CoreDistributedCacheProvider.CacheFactory before building a session factory.
+ The following NHibernate configuration settings are available:
+
+
+
+
+ cache.default_expiration
+
+ Number of seconds to wait before expiring each item.
+ Defaults to 300. It can also be set programmatically on the NHibernate
+ configuration object under the name expiration, which then takes precedence
+ over cache.default_expiration.
+
+
+
+ cache.use_sliding_expiration
+
+ Should the expiration be sliding? A sliding expiration is reinitialized at each get.
+ Defaults to false.
+
+
+
+
+
+ CoreDistributedCache has a config file section handler to allow configuring different expirations for
+ different regions, configuring the IDistributedCacheFactory to use, and configuring
+ additional properties specific to the chosen IDistributedCache implementation.
+ Here is an example:
+
+
+
+
+
+
+
+
+
+
+
+ 00:10:00
+ 1048576
+
+
+
+
+]]>
+
+
+
+ CoreDistributedCache does not support NHibernate.Cache.ICache.Clear. Clearing the NHibernate
+ cache has no effects with CoreDistributedCache.
+
+
+
+ Memcached distributed cache factory
+
+
+ NHibernate.Caches.CoreDistributedCache.Memcached provides a Redis distributed cache factory.
+ This factory yields a Enyim.Caching.MemcachedClient from EnyimMemcachedCore.
+ For using it, reference the cache factory package and set the factory-class attribute of the
+ coredistributedcache configuration section to
+ NHibernate.Caches.CoreDistributedCache.Memcached.MemcachedFactory, NHibernate.Caches.CoreDistributedCache.Memcached.
+
+
+
+ Memcached does not support sliding expirations. cache.use_sliding_expiration setting or
+ sliding region setting do not have any effect with Memcached.
+
+
+
+ The following additional properties can be configured:
+
+
+
+
+ configuration
+
+ The JSON configuration of EnyimMemcachedCore, see its
+ project website. It has to be structured
+ like the value part of the "enyimMemcached" property in an
+ appsettings.json file.
+
+
+
+
+
+
+
+
+
+ Redis distributed cache factory
+
+
+ NHibernate.Caches.CoreDistributedCache.Redis provides a Redis distributed cache factory.
+ This factory yields a Microsoft.Extensions.Caching.Redis.RedisCache. For using it,
+ reference the cache factory package and set the factory-class attribute of the
+ coredistributedcache configuration section to
+ NHibernate.Caches.CoreDistributedCache.Redis.RedisFactory, NHibernate.Caches.CoreDistributedCache.Redis.
+
+
+ The following additional properties can be configured:
+
+
+
+
+ configuration
+
+ Its value will be used to set the Configuration property of the
+ RedisCache options (RedisCacheOptions).
+
+
+
+ instance-name
+
+ Its value will be used to set the InstanceName property of the
+ RedisCache options (RedisCacheOptions).
+
+
+
+
+
+
+ SQL Server distributed cache factory
+
+
+ NHibernate.Caches.CoreDistributedCache.SqlServer provides a SQL Server distributed cache factory.
+ This factory yields a Microsoft.Extensions.Caching.SqlServer.SqlServerCache. For using it,
+ reference the cache factory package and set the factory-class attribute of the
+ coredistributedcache configuration section to
+ NHibernate.Caches.CoreDistributedCache.SqlServer.SqlServerFactory, NHibernate.Caches.CoreDistributedCache.SqlServer.
+
+
+ The following additional properties can be configured:
+
+
+
+
+ connection-string
+
+ Its value will be used to set the ConnectionString property of the
+ SqlServerCache options (SqlServerCacheOptions).
+
+
+
+ schema-name
+
+ Its value will be used to set the SchemaName property of the
+ SqlServerCache options (SqlServerCacheOptions).
+
+
+
+ table-name
+
+ Its value will be used to set the TableName property of the
+ SqlServerCache options (SqlServerCacheOptions).
+
+
+
+ expired-items-deletion-interval
+
+ Its value will be used to set the ExpiredItemsDeletionInterval property of the
+ SqlServerCache options (SqlServerCacheOptions). It can be
+ provided either as an integer being a number of minutes or as a TimeSpan string
+ representation.
+
+
+
+
+
+
+ Memory distributed cache factory
+
+
+ NHibernate.Caches.CoreDistributedCache.Memory provides a memory "distributed" cache factory.
+ This factory yields a Microsoft.Extensions.Caching.Memory.MemoryDistributedCache. For using it,
+ reference the cache factory package and set the factory-class attribute of the
+ coredistributedcache configuration section to
+ NHibernate.Caches.CoreDistributedCache.Memory.MemoryFactory, NHibernate.Caches.CoreDistributedCache.Memory.
+
+
+ As implied by its name, this cache is not actually distributed. It is meant for testing purpose. For other usages, consider
+ using another memory cache provider, like CoreMemoryCache. Due to the distributed cache implementation, using
+ the MemoryDistributedCache has some drawbacks compared to most other memory cache providers: it will
+ serialize cached objects, incurring some overhead; it does not support clearing the cache. But due to the serialization of
+ cached objects, it is able of computing its consumed memory size, thus the availability of the SizeLimit
+ option.
+
+
+ The following additional properties can be configured:
+
+
+
+
+ expiration-scan-frequency
+
+ Its value will be used to set the ExpirationScanFrequency property of the
+ MemoryDistributedCache options (MemoryDistributedCacheOptions). It can be
+ provided either as an integer being a number of minutes or as a TimeSpan string
+ representation.
+
+
+
+ size-limit
+
+ Its value will be used to set the SizeLimit property of the
+ MemoryDistributedCache options (MemoryDistributedCacheOptions).
+ Its value is an integer, representing the maximal bytes count to be stored in the cache.
+
+
+
+
+
+