Skip to content

Commit e04642f

Browse files
fredericDelaportefredericDelaporte
committed
Document CoreDistributedCache
1 parent f635588 commit e04642f

File tree

1 file changed

+201
-0
lines changed

1 file changed

+201
-0
lines changed

‎doc/reference/modules/nhibernate_caches.xml

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,20 @@
121121
</para>
122122
</listitem>
123123
</varlistentry>
124+
<varlistentry>
125+
<term><classname>NHibernate.Caches.CoreDistributedCache</classname></term>
126+
<listitem>
127+
<para>
128+
Uses <classname>Microsoft.Extensions.Caching.Abstractions.IDistributedCache</classname> implementations as the cache
129+
provider. The implementation has to be provided through an <literal>IDistributedCacheFactory</literal>.
130+
Distributed cache factories for <literal>Redis</literal>, <literal>SqlServer</literal> and <literal>Memory</literal>
131+
caches are available through their own package, prefixed by <literal>NHibernate.Caches.CoreDistributedCache.</literal>.
132+
</para>
133+
<para>
134+
This provider is available as a .Net Standard NuGet package. See <xref linkend="NHibernate.Caches.CoreDistributedCache" />.
135+
</para>
136+
</listitem>
137+
</varlistentry>
124138
</variablelist>
125139
</para>
126140
</abstract>
@@ -701,4 +715,191 @@
701715
</example>
702716
</section>
703717

718+
<section id="NHibernate.Caches.CoreDistributedCache">
719+
<title>CoreDistributedCache Configuration</title>
720+
<para>
721+
CoreDistributedCache relies on <classname>Microsoft.Extensions.Caching.Abstractions.IDistributedCache</classname>
722+
implementations. The implementation has to be provided through an <literal>IDistributedCacheFactory</literal>, either
723+
supplied through configuration or programmatically by affecting
724+
<literal>CoreDistributedCacheProvider.CacheFactory</literal> before building a session factory.
725+
The following NHibernate configuration settings are available:
726+
</para>
727+
728+
<variablelist>
729+
<varlistentry>
730+
<term><literal>cache.default_expiration</literal></term>
731+
<listitem>
732+
Number of seconds to wait before expiring each item.
733+
Defaults to <literal>300</literal>. It can also be set programmatically on the NHibernate
734+
configuration object under the name <literal>expiration</literal>, which then takes precedence
735+
over <literal>cache.default_expiration</literal>.
736+
</listitem>
737+
</varlistentry>
738+
<varlistentry>
739+
<term><literal>cache.use_sliding_expiration</literal></term>
740+
<listitem>
741+
Should the expiration be sliding? A sliding expiration is reinitialized at each get.
742+
Defaults to <literal>false</literal>.
743+
</listitem>
744+
</varlistentry>
745+
</variablelist>
746+
747+
<para>
748+
CoreDistributedCache has a config file section handler to allow configuring different expirations for
749+
different regions, configuring the <literal>IDistributedCacheFactory</literal> to use, and configuring
750+
additional properties specific to the chosen <literal>IDistributedCache</literal> implementation.
751+
Here is an example:
752+
</para>
753+
754+
<example>
755+
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
756+
<configuration>
757+
<configSections>
758+
<section name="coredistributedcache"
759+
type="NHibernate.Caches.CoreDistributedCache.CoreDistributedCacheSectionHandler,
760+
NHibernate.Caches.CoreDistributedCache" />
761+
</configSections>
762+
763+
<coredistributedcache
764+
factory-class="NHibernate.Caches.CoreDistributedCache.Memory.MemoryFactory,
765+
NHibernate.Caches.CoreDistributedCache.Memory">
766+
<properties>
767+
<property name="expiration-scan-frequency">00:10:00</property>
768+
<property name="size-limit">1048576</property>
769+
</properties>
770+
<cache region="foo" expiration="500" sliding="true" />
771+
<cache region="noExplicitExpiration" sliding="true" />
772+
</coredistributedcache>
773+
</configuration>]]></programlisting>
774+
</example>
775+
776+
<para>
777+
CoreDistributedCache does not support <literal>NHibernate.Cache.ICache.Clear</literal>. Clearing the NHibernate
778+
cache has no effects with CoreDistributedCache.
779+
</para>
780+
781+
<section>
782+
<title>Redis distributed cache factory</title>
783+
784+
<para>
785+
<literal>NHibernate.Caches.CoreDistributedCache.Redis</literal> provides a Redis distributed cache factory.
786+
This factory yields a <literal>Microsoft.Extensions.Caching.Redis.RedisCache</literal>. For using it,
787+
reference the cache factory package and set the <literal>factory-class</literal> attribute of the
788+
<literal>coredistributedcache</literal> configuration section to
789+
<literal>NHibernate.Caches.CoreDistributedCache.Redis.RedisFactory, NHibernate.Caches.CoreDistributedCache.Redis</literal>.
790+
</para>
791+
<para>
792+
The following additional properties can be configured:
793+
</para>
794+
795+
<variablelist>
796+
<varlistentry>
797+
<term><literal>configuration</literal></term>
798+
<listitem>
799+
Its value will be used to set the <literal>Configuration</literal> property of the
800+
<literal>RedisCache</literal> options (<literal>RedisCacheOptions</literal>).
801+
</listitem>
802+
</varlistentry>
803+
<varlistentry>
804+
<term><literal>instance-name</literal></term>
805+
<listitem>
806+
Its value will be used to set the <literal>InstanceName</literal> property of the
807+
<literal>RedisCache</literal> options (<literal>RedisCacheOptions</literal>).
808+
</listitem>
809+
</varlistentry>
810+
</variablelist>
811+
</section>
812+
813+
<section>
814+
<title>SQL Server distributed cache factory</title>
815+
816+
<para>
817+
<literal>NHibernate.Caches.CoreDistributedCache.SqlServer</literal> provides a SQL Server distributed cache factory.
818+
This factory yields a <literal>Microsoft.Extensions.Caching.SqlServer.SqlServerCache</literal>. For using it,
819+
reference the cache factory package and set the <literal>factory-class</literal> attribute of the
820+
<literal>coredistributedcache</literal> configuration section to
821+
<literal>NHibernate.Caches.CoreDistributedCache.SqlServer.SqlServerFactory, NHibernate.Caches.CoreDistributedCache.SqlServer</literal>.
822+
</para>
823+
<para>
824+
The following additional properties can be configured:
825+
</para>
826+
827+
<variablelist>
828+
<varlistentry>
829+
<term><literal>connection-string</literal></term>
830+
<listitem>
831+
Its value will be used to set the <literal>ConnectionString</literal> property of the
832+
<literal>SqlServerCache</literal> options (<literal>SqlServerCacheOptions</literal>).
833+
</listitem>
834+
</varlistentry>
835+
<varlistentry>
836+
<term><literal>schema-name</literal></term>
837+
<listitem>
838+
Its value will be used to set the <literal>SchemaName</literal> property of the
839+
<literal>SqlServerCache</literal> options (<literal>SqlServerCacheOptions</literal>).
840+
</listitem>
841+
</varlistentry>
842+
<varlistentry>
843+
<term><literal>table-name</literal></term>
844+
<listitem>
845+
Its value will be used to set the <literal>TableName</literal> property of the
846+
<literal>SqlServerCache</literal> options (<literal>SqlServerCacheOptions</literal>).
847+
</listitem>
848+
</varlistentry>
849+
<varlistentry>
850+
<term><literal>expired-items-deletion-interval</literal></term>
851+
<listitem>
852+
Its value will be used to set the <literal>ExpiredItemsDeletionInterval</literal> property of the
853+
<literal>SqlServerCache</literal> options (<literal>SqlServerCacheOptions</literal>). It can be
854+
provided either as an integer being a number of minutes or as a <literal>TimeSpan</literal> string
855+
representation.
856+
</listitem>
857+
</varlistentry>
858+
</variablelist>
859+
</section>
860+
861+
<section>
862+
<title>Memory distributed cache factory</title>
863+
864+
<para>
865+
<literal>NHibernate.Caches.CoreDistributedCache.Memory</literal> provides a memory "distributed" cache factory.
866+
This factory yields a <literal>Microsoft.Extensions.Caching.Memory.MemoryDistributedCache</literal>. For using it,
867+
reference the cache factory package and set the <literal>factory-class</literal> attribute of the
868+
<literal>coredistributedcache</literal> configuration section to
869+
<literal>NHibernate.Caches.CoreDistributedCache.Memory.MemoryFactory, NHibernate.Caches.CoreDistributedCache.Memory</literal>.
870+
</para>
871+
<para>
872+
As implied by its name, this cache is not actually distributed. It is meant for testing purpose. For other usages, consider
873+
using another memory cache provider, like <literal>CoreMemoryCache</literal>. Due to the distributed cache implementation, using
874+
the <literal>MemoryDistributedCache</literal> has some drawbacks compared to most other memory cache providers: it will
875+
serialize cached objects, incurring some overhead; it does not support clearing the cache. But due to the serialization of
876+
cached objects, it is able of computing its consumed memory size, thus the availability of the <literal>SizeLimit</literal>
877+
option.
878+
</para>
879+
<para>
880+
The following additional properties can be configured:
881+
</para>
882+
883+
<variablelist>
884+
<varlistentry>
885+
<term><literal>expiration-scan-frequency</literal></term>
886+
<listitem>
887+
Its value will be used to set the <literal>ExpirationScanFrequency</literal> property of the
888+
<literal>MemoryDistributedCache</literal> options (<literal>MemoryDistributedCacheOptions</literal>). It can be
889+
provided either as an integer being a number of minutes or as a <literal>TimeSpan</literal> string
890+
representation.
891+
</listitem>
892+
</varlistentry>
893+
<varlistentry>
894+
<term><literal>size-limit</literal></term>
895+
<listitem>
896+
Its value will be used to set the <literal>SizeLimit</literal> property of the
897+
<literal>MemoryDistributedCache</literal> options (<literal>MemoryDistributedCacheOptions</literal>).
898+
Its value is an integer, representing the maximal bytes count to be stored in the cache.
899+
</listitem>
900+
</varlistentry>
901+
</variablelist>
902+
</section>
903+
</section>
904+
704905
</chapter>

0 commit comments

Comments
 (0)