From ebea8e41cc61c59daaa05cd0c79a02b3e152651a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= Date: Sun, 18 Mar 2018 18:00:59 +0100 Subject: [PATCH 1/5] Fix cache custom settings The nhibernate session factory configuration settings is restricted by a xsd. Adjust documentation of custom settings for reflecting this. --- doc/reference/modules/nhibernate_caches.xml | 30 +++++++++++++-------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index 24aa760ce0c..5a7a60c59bb 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -204,6 +204,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 +219,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 +238,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 +282,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. @@ -577,11 +584,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. From 3c33955a34184d22ea967612498d51d15edd9c79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= Date: Thu, 22 Mar 2018 13:51:12 +0100 Subject: [PATCH 2/5] Adjust caches documentation * Fix typos * Remove obsolete stuff * Add a note on caches potentially shared between session factories * Link each cache to its configuration documentation * Give ids to all sections * Switch Memcache for EnyimMemcached and document it. The former is no more maintained since years, and its NuGet package is not updated. Moreover it fails some basic tests. The later appears to be no more maintained since one year and a half, but it does not fail tests and its NuGet package is still updated. --- doc/reference/modules/nhibernate_caches.xml | 45 +++++++++++++++------ 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index 5a7a60c59bb..a0c598f4da2 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: @@ -45,6 +51,7 @@ 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. + 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. + Also see . @@ -69,14 +77,17 @@ SysCache2 requires Microsoft SQL Server 2000 or higher. + + 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. Also see . @@ -96,6 +107,7 @@ Uses System.Runtime.Caching.MemoryCache.Default as the cache provider. + See . @@ -111,17 +123,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> @@ -312,7 +323,7 @@ ]]> -
+
Table-based Dependency @@ -369,7 +380,7 @@ -
+
Command-Based Dependencies @@ -464,7 +475,7 @@
-
+
Aggregate Dependencies @@ -508,7 +519,7 @@
-
+
Additional Settings In addition to data dependencies for the cache regions, time based expiration policies can be specified @@ -571,7 +582,15 @@
+
+
+ EnyimMemcached Configuration + + Its configuration relies on the EnyimMemcached library own configuration, through its + enyim.com/memcached configuration section. See + project site. +
From 5f98378e633be37f4f5cb13f609baeab47f8d0c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= Date: Thu, 22 Mar 2018 15:05:08 +0100 Subject: [PATCH 3/5] Document CoreMemoryCache --- doc/reference/modules/nhibernate_caches.xml | 74 +++++++++++++++++++-- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index a0c598f4da2..341065a66c0 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -50,8 +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. - Also see . + you can also visit its website. This + provider is available for the .Net Framework only. Also see . @@ -62,7 +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. - Also see . + This provider is available for the .Net Framework only. Also see . @@ -75,7 +75,7 @@ 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 . @@ -87,7 +87,8 @@ Uses Memcached. See memcached homepage - for more information on Memcached. Also see . + for more information on Memcached. This provider is available for the .Net Framework only. Also see + . @@ -106,8 +107,17 @@ NHibernate.Caches.RtMemoryCache - Uses System.Runtime.Caching.MemoryCache.Default as the cache provider. - See . + 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 . @@ -641,4 +651,54 @@
+
+ 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: + + + + + + +
+ + + + + + +]]> + +
+ From 2f488cd446c8cc10939d5c78ace097ff5563f772 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= Date: Thu, 22 Mar 2018 17:01:03 +0100 Subject: [PATCH 4/5] Document CoreDistributedCache --- doc/reference/modules/nhibernate_caches.xml | 201 ++++++++++++++++++++ 1 file changed, 201 insertions(+) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index 341065a66c0..358fd2a6731 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -121,6 +121,20 @@ + + 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 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 . + + + @@ -701,4 +715,191 @@
+
+ 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. + + +
+ 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. + + + +
+
+ From 6cadaf76879d207d84c526061ca44ee174bc7d80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Delaporte?= Date: Fri, 23 Mar 2018 18:48:51 +0100 Subject: [PATCH 5/5] Document Memcached distributed cache factory --- doc/reference/modules/nhibernate_caches.xml | 48 ++++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/doc/reference/modules/nhibernate_caches.xml b/doc/reference/modules/nhibernate_caches.xml index 358fd2a6731..387dea6fd8c 100644 --- a/doc/reference/modules/nhibernate_caches.xml +++ b/doc/reference/modules/nhibernate_caches.xml @@ -127,8 +127,9 @@ Uses Microsoft.Extensions.Caching.Abstractions.IDistributedCache implementations as the cache provider. The implementation has to be provided through an IDistributedCacheFactory. - Distributed cache factories for Redis, SqlServer and Memory - caches are available through their own package, prefixed by NHibernate.Caches.CoreDistributedCache.. + 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 . @@ -778,6 +779,49 @@ 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