[toc]
Overview
Telligent's caching framework offers a configuration model that grants users the ability to define how their cache is defined. A cache consists of one or more layers that, together, form one logical structure.
For more information, see Caching.
Caching in a Web farm
When items are placed into cache, they usually do not give an explicit timeout stating how long they should be cached. In these cases, the current default timeout is used.
Default timeouts are used extensively throughout Telligent Community Server. If left unmodified, the default timeout is 1 minute and 40 seconds. Default timeouts give us a very simple way to adjust our caching tolerance for stale items. Having a high default timeout means that performance will be better at the cost of increased staleness for items.
When a site runs on a single server, staleness usually isn't a problem because all data operations are executed at the same location items are being cached. This allows for the cache to be closely in sync with the underlying data.
On sites with multiple servers utilizing cache, you are not guaranteed that the operation executed on one server is reflected in another. This means that cached items will be stale on any machine that didn't execute the action. In this case, we would want to lower the default timeout on all servers so that any one server doesn't hold items in cache for too long.
See the <overrides> node below for details on how to adjust the default timeout.
Runtime adjustments
There may be instances when you want to cache specific items longer or shorter (or not at all). You can modify these values by adding an override that defines how a particular piece of data can be cached. You can target items by their key, object type, or other attributes.
See the Override section below to learn more.
Distributed caching support
Included in Community Server's caching system is a built-in provider for consuming AppFabric distributed caches. This new provider can be used to reduce database pressure and improve overall performance.
For more information on using AppFabric in your site, see Install, configure, and enable AppFabric caching.
How to
The following information describes how to configure your site's cache using XML. By default, Community Server uses the file caching.config to store this information.
Configuration
To use XML configuration, ensure a section called <telligent.caching> can be retrieved from the configuration source.
This section must be registered inside web.config (or the expected application configuration file type) or caching will not function.
<configSections>
<section name="telligent.caching"
type="Telligent.Caching.Configuration.CachingConfigurationSection, Telligent.Caching" />
</configSections>
<telligent.caching> root node
The root node for caching is named <telligent.caching>. This node specifies how the cache is configured.
<telligent.caching>
</telligent.caching>
<hierarchy> node
The <hierarchy> node specifies the order in which the caches appear. There can only be one <hierarchy> node in a cache system. This node is not required, but without it you cannot specify any implemented caches.
The hierarchy is ordered from top to bottom, where the highest level is the first child of <hierarchy>. Each child <cache> node specifies a new cache layer in the stack.
<telligent.caching>
<hierarchy>
</hierarchy>
</telligent.caching>
<cache> node
The <cache> node is used to create objects that implement the caching interfaces. There can be many <cache> nodes in a cache system. This node is not required, but without at least one <cache> node, items will not be cached.
<telligent.caching>
<hierarchy>
<cache />
.
.
</hierarchy>
</telligent.caching>
<cache> node attributes and defaults
Attribute Name | Required | Default | Description |
name | false | (null) | A System.String; The name assigned to the cache instance. |
type | true | - | The cache System.Type to create. |
cacheFactor | false | 1.0 | A System.Double; The factor to apply to timeout values when items are placed into cache. This value must be larger than or equal to 0.0. |
Overrides
<overrides> node
The <overrides> node specifies any runtime overrides that are applied. There can only be one <overrides> node in a cache system. This node is not required.
<telligent.caching>
<overrides>
</overrides>
</telligent.caching>
<overrides> node attributes and defaults
Attribute Name | Required | Default | Description |
defaultTimeout | false | 00:01:40 | A System.Timespan; The value to use when items are placed into cache without specifying a timeout value explicitly. |
<override> node
The <override> node defines conditions that, when met, trigger the override adjustments. There can be many <override> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override />
.
.
</overrides>
</telligent.caching>
<override> node attributes and defaults
Attribute Name | Required | Default | Description |
allowedScope | false | (null) | A CacheScope; The allowed scope when placing the item into the cache. This value ensures that only the scopes listed may contain the cached item. This will never add scopes to an operation; it can only restrict scopes. |
timeout | false | (null) | A System.TimeSpan; The timeout value for the item. |
cacheFactor | false | (null) | A double; The factor to apply to the item's timeout value. This value must be larger than or equal to 0.0. |
Conditional overrides are only applied when the conditions specified are met for a cache operation. Conditions include:
Condition | Description |
startsWith | A condition that attempts to match keys or tags against a starting pattern. |
endsWith | A condition that attempts to match keys or tags against an ending pattern. |
regex | A condition that attempts to match keys or tags against a regular expression. |
object | A condition that attempts to match the cached item's type against the specified object type. |
By default, override conditions are OR'ed together. If you want to change this behavior, you can explore the different composite conditions values offered by the override system. See the section Composite nodes below for more information.
<startsWith> node
The <startsWith> node is used to specify a starting block of text to match against. The pattern to match should be placed as the node's value (e.g., <startsWith>pattern_to_use</startsWith>). There can be many <startsWith> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<startsWith />
.
.
</override>
</overrides>
</telligent.caching>
<startsWith> node attributes and defaults
Attribute Name | Required | Default | Description |
mode | false | Key | An AliasConditionMode; Specifies the value to match against: Key will match the pattern against a cache request's key. AnyTags is true when one or more cache tags match the starting pattern. AllTags is true when all cache tags match the starting pattern. NoTags is true when none of the cache tags match the starting pattern. |
<endsWith> node
The <endsWith> node is used to specify a ending block of text to match against. The pattern to match should be placed as the node's value (e.g., <endsWith>pattern_to_use</endsWith>). There can be many <endsWith> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<endsWith />
.
.
</override>
</overrides>
</telligent.caching>
<endsWith> node attributes and defaults
Attribute Name | Required | Default | Description |
mode | false | Key | An AliasConditionMode; Specifies the value to match against: Key will match the pattern against a cache request's key. AnyTags is true when one or more cache tags match the starting pattern. AllTags is true when all cache tags match the starting pattern. NoTags is true when none of the cache tags match the starting pattern. |
<contains> node
The <contains> node is used to specify a substring to match against. The pattern to match should be placed as the node's value (e.g., <contains>pattern_to_use</contains>). There can be many <contains> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<contains />
.
.
</override>
</overrides>
</telligent.caching>
<contains> node attributes and defaults
Attribute Name | Required | Default | Description |
mode | false | Key | An AliasConditionMode; Specifies the value to match against: Key will match the pattern against a cache request's key. AnyTags is true when one or more cache tags match the starting pattern. AllTags is true when all cache tags match the starting pattern. NoTags is true when none of the cache tags match the starting pattern. |
<regex> node
The <regex> node is used to specify a regular expression pattern to match against. The pattern to match should be placed as the node's value (e.g., <regex>^pattern_to_use$</regex>). There can be many <regex> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<regex />
.
.
</override>
</overrides>
</telligent.caching>
<regex> node attributes and defaults
Attribute Name | Required | Default | Description |
mode | false | Key | An AliasConditionMode; Specifies the value to match against: Key will match the pattern against a cache request's key. AnyTags is true when one or more cache tags match the starting pattern. AllTags is true when all cache tags match the starting pattern. NoTags is true when none of the cache tags match the starting pattern. |
<object> node
The <object> node is used to specify a particular object type to match against. The type to match should be placed as the node's value (e.g., <object>System.String</object>). There can be many <object> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<object />
.
.
</override>
</overrides>
</telligent.caching>
<true> node
The <true> node is used to specify a true condition. This node is useful for debugging purposes. There can be many <true> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<true />
.
.
</override>
</overrides>
</telligent.caching>
<false> node
The <false> node is used to specify a false condition. This node is useful for debugging purposes. There can be many <false> nodes in a cache system. This node is not required.
<telligent.caching>
<overrides>
<override>
<false />
.
.
</override>
</overrides>
</telligent.caching>
Composite nodes
Conditions can be combined to form composite conditions. Composite conditions include:
Node | Description |
<and> | All child conditions must match in order for this composite to match. |
<or> | Any child condition must match in order for this composite to match. |
<not> | A special case composite that must contain exactly one child condition. The child condition must be false in order for this composite to match. |
<telligent.caching>
<overrides>
<override>
<and>
<condition-1 />
<condition-2 />
.
.
</and>
<or>
<condition-1 />
<condition-2 />
.
.
</or>
<not>
<condition />
</not>
<override>
</overrides>
</telligent.caching>