Cache Config
The cache configuration file contains information regarding all the registered caches/clusters. Modules that need to read the configurations first try to find config.ncconf in the application folder, i.e., alongside the Web.config. If config.ncconf is not found in the application folder, it then reads the configuration from the installation folder.
Note
This file is installed with NCache and is located at %NCHOME%\config in Windows and NCache Install dir/config in Linux.
Cache Config Syntax and Tags
The config.ncconf file is explained below:
<!--
The configuration file (config.ncconf) contains the details of all the registered caches. All cache configurations are enclosed in the <configuration></configuration> tag. Whereas each cache detail is enclosed in <cache-config></cache-config>.
-->
<cache-config cache-name="demoCache" alias="" store-type="Distributed-Cache" config-id="6a49d9ce-9aa7-4312-ada6-4fec37a6e729" config-version="1">
<cache-settings inproc="False" last-modified="" auto-start="False" data-format="Serialized" serialization="Binary">
...
</cache-settings>
</cache-config>
cache-name: The cache identifier. The cache will be known by whatever name you specify here. This is the same name as you specify while initializing the cache.
store-type: Specifies the purpose for which this cache will be used. Can have one of the following possible values:
Distributed-CacheDistributed-Cache-PersistencePub/Sub-MessagingDistributed-Lucene
inproc: Determines whether the cache will run as InProc (in your application process) or OutProc (in the NCache Service process). If set to "False", the cache will run as OutProc and if set to "True", then the cache will run as InProc.
config-version: Used to determine whether the configuration is modified or not.
config-id: Auto-generates unique Id for the modified configuration.
last-modified: Contains information related to the last modification in the cache configuration.
auto-start: Enables the auto start of cache on cache startup. (NCache Enterprise only)
data-format: The format with which data is stored in cache, can be Serialized or Object.
serialization: The serialization format for the cache. It can be either JSON or Binary.
<logging enable-logs="True" trace-errors="True" trace-notices="False" trace-warnings="False" trace-debug="False" log-path=""/>
NCache maintains a log file to write traces for information and debugging purposes. Using these tags user can enable or disable the various traces. By default, only the “Error” trace is enabled, rest of the traces are disabled. Error trace does not affect the cache performance but for other traces. We recommend not enabling them in a production environment as they affect the performance of NCache.
log-path: By default, log files for each cache are created at %NCHOME%\log-files in Windows and NCache Install dir/log-files in Linux. However, you can specify a custom path if you want to save the logs elsewhere.
<performance-counters enable-counters="True" snmp-port="0"/>
If this attribute is set to True, NCache will update the published PerfMon counters. If set to False, NCache will not update any of the published PerfMon counters.
<replication-strategy synchronous="False"/>
In the case of Partition-Replica, you will find this tag in the cache configuration. The replication strategy defines how data is replicated to the backup node.
synchronous: This attribute can be set to True/False. If set to False, then data operation will be replicated asynchronously on the backup node. If set to True, then data operation will be replicated synchronously on the backup node.
<pipelining enabled="False" batch-interval="250usec"/>
To enable pipelining, set the pipelining enabled tag as True and enter the time in microseconds(µs) for the batch interval. The default value is 250 µs and the minimum and maximum values are 50µs and 5000µs respectively.
<compression enable-compression="False" threshold="100kb"/>
This XML tag specifies whether the items greater than the specified threshold should be compressed/decompressed on the client side.
enable-compression: To enable compression, set this attribute to True, otherwise, set it to False.
threshold: Items greater than the value specified in the threshold attribute will only be compressed/decompressed on the client side if compression is enabled.
As per above mentioned compression tag example, only items greater than 100kb in size will be compressed/decompressed on the client side.
<client-activity-notification enabled="False" retention-period="5sec"/>
Enabled: Enable this option to allow clients to receive notifications if another client connects or disconnects.
retention-period: The Retention period is the time interval after which a disconnected client is considered as disconnected.
<cache-notifications item-remove="False" item-add="False" item-update="False"/>
notifications: XML tag specifies the registered event with the cache.
Item-add: This attribute can be set to True or False. If set to True, will notify when an item is added to the cache. Similarly if set to False, no notification will be fired if the item is added to the cache.
Item-remove: This attribute can be set to True or False. If set to True, will notify when an item is removed from the cache. Similarly if set to False, no notification will be fired if the item is removed from the cache.
Item-update: This attribute can be set to True or False. If set to True, will notify when an item is updated in the cache. Similarly if set to False, no notification will be fired if the item is updated in the cache.
<cleanup interval="15sec"/>
cleanup: XML tag specifies the periodic interval after which the item for expiration will be checked:
Interval: If set to "15 secs" this means the expiration check will be performed after every 15 sec.
<storage type="heap" cache-size="1024mb"/>
storage: XML tag specifies the storage-related details for cache:
Type: This attribute can only be set to "heap" as currently NCache only supports heap-based storage.
Cache-size: This attribute specifies the upper limit of cache size in MB.
<eviction-policy enabled-eviction="True" default-priority="normal" policy="lru" eviction-ratio="5%"/>
This XML tag specifies whether to perform the eviction or not. If eviction is enabled then the cache will remove the existing item to accommodate new ones. Exiting items will be removed based on the eviction strategy.
Enabled-eviction: To enable eviction set this attribute to True, otherwise set it to False.
Policy: This attribute specifies the eviction policy to be used. Eviction policy can be one of the following:
- LRU (Least recently used) (NCache Enterprise only)
- LFU (Least frequently used) (NCache Enterprise only)
- Priority based
Default-priority: Specifies the default priority that is associated with an item if no priority is specified for that item. This attribute can be set to the following:
- High
- Above-normal
- Normal
- Below-normal
- Low
This is only applicable in case of priority based eviction.
Eviction-ratio: Specifies how much percentage of data should be evicted when eviction is performed.
<expiration-policy enabled="True">
<absolute-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
<sliding-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
</expiration-policy>
enabled: Enables the expiration policy.
longer-enabled: Specifies whether Longer expiration is enabled. If True, the value should be provided.
longer-value: If longer-enabled is True, this value will be used for expiration.
default-enabled: Specifies whether Default expiration is enabled. If True, the value should be provided as well.
default-value: If default-enabled is True, this value will be used for expiration.
<security>
<user id="john_smith" dn="CN=John Smith,OU=admin,DC=yourdomain,DC=org"/>
<user id="david_watson" dn="CN=David Watson,OU=admin,DC=yourdomain,DC=org"/>
<group id="DEV" dn="CN=DEV,OU=admin,DC=yourdomain,DC=org"/>
</security>
user: This attribute specifies admin user credentials.
id: Specifies the ID of the user.dn: Specifies the user's distinguished name.
group: This attribute specifies the group detail.
id: Specifies the name of the group.dn: Specifies the group's distinguished name.
<cache-topology topology="partition-replica">
<cluster-settings operation-timeout="60sec" stats-repl-interval="2sec" use-heart-beat="True">
...
</cluster-settings>
</cache-topology>
This XML tag is used for specifying the in-cluster communication details, it also contains a subtag, channel, which further defines the communication details of the cluster:
Please note, that this tag will not be present in Local Cache.
topology: Specifies which topology the cluster follows, it can be either one of the following as provided by NCache:
- Partition-Replica Topology (NCache Enterprise only)
- Replicated Topology
- Partitioned Topology
- Mirror Topology
operation-timeout: Determines the timeout of a connection among the servers if a server in the cluster fails to respond.
stats-repl-interval: (Statistics Replication Interval) the interval provided to the cluster at which to synchronize their information among its servers.
use-heart-beat: HeartBeat is used to monitor the connectivity between nodes.
<data-persistence store-name="demoPersistenceCache_db">
<provider-settings provider-type="ncache-persistence" connection-string="lxxKK7Xqh0Tpm3rPvPOmYcCRYyeUV8f8NswyNRFum/uA0HXudbm6vWkXcnJ33GE9"/>
<operation-setting persistence-interval="1000ms" persistence-retries="3" persistence-interval-longer="60sec"/>
</data-persistence>
This tag data-persistence is used to determine the settings of your Distributed Cache with Persistence. It only appears if you've set your store-type as distributed-cache-persistence. It has the following parameters:
provider-type: This parameter indicates the type of persistence provider you are using in your distributed-cache-persistence. It has value ncache-persistence.
connection-string: A valid connection string that determines the connection with the provider-type specified.
persistence-interval: This is the interval after which the operations present in the persistence queue are applied to the persistence store.
persistence-retries: This is the number of retries in case of persistence batch failures after which the persistence-interval is shifted to persistence-interval-longer.
persistence-interval-longer: When several consecutive failures reach persistence-retries the interval is then set to persistence-interval-longer.
<caching-modules>
<module name="lucene-net-4.8" enable="True">
<parameters name="IndexPath" value="C:\ProgramData\ncache\lucene-index\lucene"/>
</module>
</caching-modules>
<caching-module>: This XML tag specifies all the modules and their respective parameters registered under a cache. It only appears if you've set your store-type as distributed-lucene.
Under the <module> tag, you have:
name: Specifies the name of the module. The module will be identified by whatever name you provide here. This name needs to be unique.
enable: Enables/disables the provided module.
Under the <parameters> tag, you have:
name: Specifies the list of parameters added against a module.
value: Specifies the value provided for the added parameter.
<cluster-connection-settings cluster-port="7806" port-range="1" connection-retries="2" connection-retry-interval="2secs" join_retry_count="24" join_retry_timeout="5"/>
<cluster-connection-settings>: This XML tag specifies the details of port connectivity and other communication options among the cluster servers:
cluster-port: Connection is channeled through a TCP port; this value defines the port which it occupies.
port-range: When initializing, if the port provided is taken by some other application then it will try to establish its connection on port incremented by 1, for this the range is provided, i.e., to what range should it search for an available TCP port.
connection-retries: If connection among the node(s) is failed, then this defines how many retries should be made to consider it a permanent failure.
connection-retry-interval: The interval between connection retries is defined in this value.
<alerts>
<email-notification email-notification-enabled="False" sender="" smtp-server="" smtp-port="0" ssl="False" authentication="False" sender-login="" sender-password=""/>
<alerts-types cache-stop="False" cache-start="False" node-left="False" node-joined="False" state-transfer-started="False" state-transfer-stop="False" state-transfer-error="False" cache-size="False"/>
</alerts>
If Event notifications through email (Enterprise feature only) are required, then information for its setup is configured here:
Email-notification: Contains all the information related to the email address.
Email-notification-enabled: Enables notification through email.
Sender: Specify the email account from whom the email notifications are sent.
Smtp-server: Specify the gateway to send email notifications.
Smtp-port: The port number used to forward emails.
SSL: Secure Socket Layer to enable SSL security.
Authentication: If any authentication is required, this is to be True.
Sender-login: If Authentication is required, specify the login name.
Sender-password: The authentication password is entered here.
Alert-Types: Specifies at which event an automated email is to be generated.
Cache-stop: If the cache is stopped at any moment, an email notification is generated.
Cache-start: At the start of the cache, an email notification is generated.
Node-left: When a server node leaves the cluster or if a server node is inaccessible for any reason, an email notification will be sent if this is enabled.
Node-joined: At the joining of any server node an email notification is generated.
State-Transfer-started: To notify whenever a state transfer has occurred which happens when Load balancing is performed, an email notification is generated.
Cache-size: Whenever cache size is changed using Hot Apply, an email notification is generated.
<sql-dependency use-default="False"/>
This XML tag specifies the queuing and service SQL notification architecture. (Enterprise only)
Use-default: The attribute can be set to True/False. If the attribute is set to True, then the default SQL Dependency service and queue will be created at run time. If the attribute is set to False, then the custom-defined SQL Dependency service and queue will be created and used by NCache.
