Table of Contents

Class CacheHelper

Namespace
CMS.Helpers
Assembly
CMS.Helpers.dll

Provides helper methods for caching.

public class CacheHelper : AbstractHelper<CacheHelper>
Inheritance
object
CacheHelper
Inherited Members
Extension Methods

Constructors

CacheHelper() 

public CacheHelper()

Fields

DefaultCacheItemPriority

Cache item priority.

public static CMSCacheItemPriority DefaultCacheItemPriority

Field Value

CMSCacheItemPriority

Properties

ClientCacheRequested

Gets if the client specified cache settings in request.

public static bool ClientCacheRequested { get; }

Property Value

bool

CurrentCachePrefix

Current context name

public static string CurrentCachePrefix { get; set; }

Property Value

string

Methods

Add(string, object, CMSCacheDependency, DateTimeOffset, TimeSpan)

Mirror to Cache.Add().

public static void Add(string key, object value, CMSCacheDependency dependencies, DateTimeOffset absoluteExpiration, TimeSpan slidingExpiration)

Parameters

key string

Cache key

value object

Cache value

dependencies CMSCacheDependency

Cache dependencies

absoluteExpiration DateTimeOffset

Cache absolute expiration

slidingExpiration TimeSpan

Cache sliding expiration

Add(string, object, CMSCacheDependency, DateTimeOffset, TimeSpan, CMSCacheItemPriority, CMSCacheItemRemovedCallback, bool)

Mirror to Cache.Add().

public static void Add(string key, object value, CMSCacheDependency dependencies, DateTimeOffset absoluteExpiration, TimeSpan slidingExpiration, CMSCacheItemPriority priority, CMSCacheItemRemovedCallback onCacheRemoveCallback = null, bool caseSensitive = false)

Parameters

key string

Cache key

value object

Cache value

dependencies CMSCacheDependency

Cache dependencies

absoluteExpiration DateTimeOffset

Cache absolute expiration

slidingExpiration TimeSpan

Cache sliding expiration

priority CMSCacheItemPriority

Cache priority

onCacheRemoveCallback CMSCacheItemRemovedCallback

Cache callback on remove

caseSensitive bool

Cache key is case sensitive

AddInternal(ICacheAccessor, string, object, CMSCacheDependency, DateTimeOffset, TimeSpan, CMSCacheItemPriority, CMSCacheItemRemovedCallback, bool, bool)

Mirror to Cache.Add().

protected virtual void AddInternal(ICacheAccessor cacheAccessor, string key, object value, CMSCacheDependency dependencies, DateTimeOffset absoluteExpiration, TimeSpan slidingExpiration, CMSCacheItemPriority priority, CMSCacheItemRemovedCallback onCacheRemoveCallback, bool caseSensitive, bool useFullKey)

Parameters

cacheAccessor ICacheAccessor

Cache into which the item is inserted.

key string

Cache key

value object

Cache value

dependencies CMSCacheDependency

Cache dependencies

absoluteExpiration DateTimeOffset

Cache absolute expiration

slidingExpiration TimeSpan

Cache sliding expiration

priority CMSCacheItemPriority

Cache priority

onCacheRemoveCallback CMSCacheItemRemovedCallback

Cache callback on remove

caseSensitive bool

Cache key is case sensitive

useFullKey bool

If true, the add operation uses the full cache key which includes the context prefix

BuildCacheItemName(IEnumerable, bool)

Builds the cache item name from the given parts

public static string BuildCacheItemName(IEnumerable parts, bool lowerCase = true)

Parameters

parts IEnumerable

Parts to build

lowerCase bool

Lower case the result

Returns

string

CacheAsync<TData>(Func<CacheSettings, CancellationToken, Task<TData>>, CacheSettings, CancellationToken)

Asynchronously loads data. If multiple threads are loading the same data, only one thread executes the load, stores the result into cache and the result is distributed to other waiting threads. If an exception is thrown during loadMethodAsync execution, the exception is distributed as well. No data are cached in such a case.

public static Task<TData> CacheAsync<TData>(Func<CacheSettings, CancellationToken, Task<TData>> loadMethodAsync, CacheSettings settings, CancellationToken cancellationToken)

Parameters

loadMethodAsync Func<CacheSettings, CancellationToken, Task<TData>>

Function accepting cache settings and a cancellation token and returning the asynchronous data loading task.

settings CacheSettings

Settings configuring the cache.

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<TData>

Returns a task returning the loaded data.

Type Parameters

TData

Type of data to be loaded.

Remarks

Based on the settings the data is stored into cache. If Cached is set to false, no caching is performed and fresh data are retrieved.

If both progressive load is allowed (both AllowProgressiveCaching and CMS.Helpers.CacheHelper.ProgressiveCaching are set to true), the fresh data retrieval is subject to progressive load (i.e. only one threads executes the load and the result is distributed to other waiting threads). Otherwise, the loadMethodAsync is always executed.

No assumptions must be made on which thread executes the loadMethodAsync. The thread creating the underlying load item is not necessarily the one executing the item. Any of the waiting threads can execute the item.

IProgressiveCache can be used to avoid a dependency on this static method.

Exceptions

ArgumentNullException

Thrown when loadMethodAsync or settings is null.

InvalidOperationException

Thrown when multiple threads are loading the same item (identified by CacheItemName) with incompatible TData.

CacheAsync<TData>(Func<CacheSettings, Task<TData>>, CacheSettings)

Asynchronously loads data. If multiple threads are loading the same data, only one thread executes the load, stores the result into cache and the result is distributed to other waiting threads. If an exception is thrown during loadMethodAsync execution, the exception is distributed as well. No data are cached in such a case.

public static Task<TData> CacheAsync<TData>(Func<CacheSettings, Task<TData>> loadMethodAsync, CacheSettings settings)

Parameters

loadMethodAsync Func<CacheSettings, Task<TData>>

Function accepting cache settings and returning the asynchronous data loading task.

settings CacheSettings

Settings configuring the cache.

Returns

Task<TData>

Returns a task returning the loaded data.

Type Parameters

TData

Type of data to be loaded.

Remarks

Based on the settings the data is stored into cache. If Cached is set to false, no caching is performed and fresh data are retrieved.

If both progressive load is allowed (both AllowProgressiveCaching and CMS.Helpers.CacheHelper.ProgressiveCaching are set to true), the fresh data retrieval is subject to progressive load (i.e. only one threads executes the load and the result is distributed to other waiting threads). Otherwise, the loadMethodAsync is always executed.

No assumptions must be made on which thread executes the loadMethodAsync. The thread creating the underlying load item is not necessarily the one executing the item. Any of the waiting threads can execute the item.

IProgressiveCache can be used to avoid a dependency on this static method.

Exceptions

ArgumentNullException

Thrown when loadMethodAsync or settings is null.

InvalidOperationException

Thrown when multiple threads are loading the same item (identified by CacheItemName) with incompatible TData.

CacheAsync<TData>(Func<CancellationToken, Task<TData>>, CacheSettings, CancellationToken)

Asynchronously loads data. If multiple threads are loading the same data, only one thread executes the load, stores the result into cache and the result is distributed to other waiting threads. If an exception is thrown during loadMethodAsync execution, the exception is distributed as well. No data are cached in such a case.

public static Task<TData> CacheAsync<TData>(Func<CancellationToken, Task<TData>> loadMethodAsync, CacheSettings settings, CancellationToken cancellationToken)

Parameters

loadMethodAsync Func<CancellationToken, Task<TData>>

Function accepting a cancellation token and returning the asynchronous data loading task.

settings CacheSettings

Settings configuring the cache.

cancellationToken CancellationToken

The cancellation instruction.

Returns

Task<TData>

Returns a task returning the loaded data.

Type Parameters

TData

Type of data to be loaded.

Remarks

Based on the settings the data is stored into cache. If Cached is set to false, no caching is performed and fresh data are retrieved.

If both progressive load is allowed (both AllowProgressiveCaching and CMS.Helpers.CacheHelper.ProgressiveCaching are set to true), the fresh data retrieval is subject to progressive load (i.e. only one threads executes the load and the result is distributed to other waiting threads). Otherwise, the loadMethodAsync is always executed.

No assumptions must be made on which thread executes the loadMethodAsync. The thread creating the underlying load item is not necessarily the one executing the item. Any of the waiting threads can execute the item.

IProgressiveCache can be used to avoid a dependency on this static method.

Exceptions

ArgumentNullException

Thrown when loadMethodAsync or settings is null.

InvalidOperationException

Thrown when multiple threads are loading the same item (identified by CacheItemName) with incompatible TData.

CacheAsync<TData>(Func<Task<TData>>, CacheSettings)

Asynchronously loads data. If multiple threads are loading the same data, only one thread executes the load, stores the result into cache and the result is distributed to other waiting threads. If an exception is thrown during loadMethodAsync execution, the exception is distributed as well. No data are cached in such a case.

public static Task<TData> CacheAsync<TData>(Func<Task<TData>> loadMethodAsync, CacheSettings settings)

Parameters

loadMethodAsync Func<Task<TData>>

Function returning the asynchronous data loading task.

settings CacheSettings

Settings configuring the cache.

Returns

Task<TData>

Returns a task returning the loaded data.

Type Parameters

TData

Type of data to be loaded.

Remarks

Based on the settings the data is stored into cache. If Cached is set to false, no caching is performed and fresh data are retrieved.

If both progressive load is allowed (both AllowProgressiveCaching and CMS.Helpers.CacheHelper.ProgressiveCaching are set to true), the fresh data retrieval is subject to progressive load (i.e. only one threads executes the load and the result is distributed to other waiting threads). Otherwise, the loadMethodAsync is always executed.

No assumptions must be made on which thread executes the loadMethodAsync. The thread creating the underlying load item is not necessarily the one executing the item. Any of the waiting threads can execute the item.

IProgressiveCache can be used to avoid a dependency on this static method.

Exceptions

ArgumentNullException

Thrown when loadMethodAsync or settings is null.

InvalidOperationException

Thrown when multiple threads are loading the same item (identified by CacheItemName) with incompatible TData.

CacheImageAllowed(int)

Checks if the file is below the maximum file size used for caching.

public static bool CacheImageAllowed(int filesize)

Parameters

filesize int

File size in bytes

Returns

bool

CacheImageEnabled()

Returns true if the image caching is enabled.

public static bool CacheImageEnabled()

Returns

bool

CacheImageMinutes()

Cache image minutes.

public static int CacheImageMinutes()

Returns

int

CacheMinutes()

Cache content minutes.

public static int CacheMinutes()

Returns

int

Cache<TData>(Func<CacheSettings, TData>, CacheSettings)

Wraps the operation to a cached section. This method supports progressive caching and is able to distribute unhandled exceptions to other simultaneously running threads.

public static TData Cache<TData>(Func<CacheSettings, TData> loadMethod, CacheSettings settings)

Parameters

loadMethod Func<CacheSettings, TData>

Method that loads the data

settings CacheSettings

Cache settings

Returns

TData

Type Parameters

TData

Remarks

IProgressiveCache can be used to avoid a dependency on this static method.

Cache<TData>(Func<TData>, CacheSettings)

Wraps the operation to a cached section. This method supports progressive caching and is able to distribute unhandled exceptions to other simultaneously running threads.

public static TData Cache<TData>(Func<TData> loadMethod, CacheSettings settings)

Parameters

loadMethod Func<TData>

Method that loads the data

settings CacheSettings

Cache settings

Returns

TData

Type Parameters

TData

Remarks

IProgressiveCache can be used to avoid a dependency on this static method.

ClearCache()

Clears the entire system cache.

public static void ClearCache()

ClearCache(string, bool, bool)

Clears the cache content starting with given string. Clears also full page cache (including persistent) when called on website.

public static void ClearCache(string startsWith, bool caseSensitive = false, bool logTask = true)

Parameters

startsWith string

If null, removes all cache items, if set, remove only items starting with given string

caseSensitive bool

Case sensitivity indicator.

logTask bool

Log web farm task

ClientCacheMinutes()

Client cache minutes for the processed content (both files and pages).

public static int ClientCacheMinutes()

Returns

int

CompactCache(double)

Tries to remove the specified percentage of items from the underlying cache. The return value indicates whether compacting was performed (i.e. whether the underlying cache supports compacting).

public static bool CompactCache(double percentage)

Parameters

percentage double

Percentage by which to reduce the cache size.

Returns

bool

Returns false if the underlying cache does not support compacting. Otherwise returns true.

Remarks

In a web site environment (IsWebSite) on the .NET Framework platform the underlying cache is the HTTP runtime cache, which does not support compacting.

CreateCacheDependencyInternal(string[], string[])

Creates the cache dependency with specified parameters

protected virtual CMSCacheDependency CreateCacheDependencyInternal(string[] files, string[] keys)

Parameters

files string[]

Dependency files

keys string[]

Dependency cache keys

Returns

CMSCacheDependency

EnsureDummyKey(string)

Ensures the dummy key with the given name

public static void EnsureDummyKey(string key)

Parameters

key string

Key to ensure

GetBaseCacheKey(bool, bool)

Returns the base cache key (created with all parameters considered to be valid for proper caching).

public static string GetBaseCacheKey(bool userName, bool cultureCode)

Parameters

userName bool
cultureCode bool

Returns

string

GetCacheDependency(ICollection<string>)

Creates the cache dependency from the given keys.

public static CMSCacheDependency GetCacheDependency(ICollection<string> keys)

Parameters

keys ICollection<string>

Cache keys

Returns

CMSCacheDependency

GetCacheDependency(string)

Creates the cache dependency from the given keys.

public static CMSCacheDependency GetCacheDependency(string keys)

Parameters

keys string

Cache keys

Returns

CMSCacheDependency

GetCacheDependency(string[])

Creates the cache dependency from the given keys.

public static CMSCacheDependency GetCacheDependency(string[] keys)

Parameters

keys string[]

Cache keys

Returns

CMSCacheDependency

GetCacheItemName(string, params object[])

Gets the cache item string.

public static string GetCacheItemName(string customName, params object[] parts)

Parameters

customName string

Custom cache item name

parts object[]

Parts of the key if the custom name is empty or null

Returns

string

GetEnumeratorInternal()

Gets the enumerator for the cache items.

protected virtual IDictionaryEnumerator GetEnumeratorInternal()

Returns

IDictionaryEnumerator

GetFileCacheDependency(string)

Creates the cache dependency from the given file path.

public static CMSCacheDependency GetFileCacheDependency(string path)

Parameters

path string

File path

Returns

CMSCacheDependency

GetFullKeyInternal(string)

Gets the full cache key with the prefix

protected virtual string GetFullKeyInternal(string key)

Parameters

key string

Cache key

Returns

string

GetInternal(string, bool)

Gets the item from the cache.

protected virtual object GetInternal(string key, bool useFullKey)

Parameters

key string

Cache key

useFullKey bool

If true, the full cache key is used

Returns

object

GetItem(string, bool)

Gets item from cache.

public static object GetItem(string key, bool caseSensitive = false)

Parameters

key string

Cache key

caseSensitive bool

Cache key is case sensitive

Returns

object

object from cache

InsertInternal(ICacheAccessor, string, object, CMSCacheDependency, DateTimeOffset, TimeSpan, CMSCacheItemPriority, CMSCacheItemRemovedCallback, bool)

Inserts the item into the cache.

protected virtual void InsertInternal(ICacheAccessor cacheAccessor, string key, object value, CMSCacheDependency dependencies, DateTimeOffset absoluteExpiration, TimeSpan slidingExpiration, CMSCacheItemPriority priority, CMSCacheItemRemovedCallback onRemoveCallback, bool useFullKey)

Parameters

cacheAccessor ICacheAccessor

Cache into which the item is inserted.

key string

Cache key

value object

Value to cache

dependencies CMSCacheDependency

Cache dependencies

absoluteExpiration DateTimeOffset

Absolute expiration time

slidingExpiration TimeSpan

Sliding expiration interval

priority CMSCacheItemPriority

Cache priority

onRemoveCallback CMSCacheItemRemovedCallback

Callback called on the removal of the item

useFullKey bool

If true, the full cache key is used

RegisterDependencyCallback<TTarget>(string, CMSCacheDependency, TTarget, Action<TTarget, object>, object, bool)

Registers a cache callback for given list of cache dependencies

public static void RegisterDependencyCallback<TTarget>(string key, CMSCacheDependency cd, TTarget target, Action<TTarget, object> handler, object parameter, bool useManagedThread = true) where TTarget : class

Parameters

key string

Cache key to use

cd CMSCacheDependency

Cache dependency to which bind the handler

target TTarget

Target object for the callback

handler Action<TTarget, object>

Callback handler

parameter object

Callback parameter

useManagedThread bool

If true, managed thread (CMSThread) is used for the callback

Type Parameters

TTarget

Remove(string, bool, bool)

Removes object from cache.

public static void Remove(string key, bool caseSensitive = false, bool logTask = true)

Parameters

key string

Cache key

caseSensitive bool

Cache key is case sensitive

logTask bool

Log web farm task

RemoveDependencyCallback(string)

Registers a cache callback for given list of cache dependencies

public static void RemoveDependencyCallback(string key)

Parameters

key string

Cache key to use

RemoveInternal(string, bool)

Removes the item from the cache.

protected virtual object RemoveInternal(string key, bool useFullKey)

Parameters

key string

Cache key

useFullKey bool

If true, the full cache key is used

Returns

object

RevalidateClientCache()

Returns whether the client cache should be revalidated by the call to the server.

public static bool RevalidateClientCache()

Returns

bool

TouchKey(string)

Touches the cache key to drop the dependencies.

public static void TouchKey(string key)

Parameters

key string

Key to touch

TouchKey(string, bool, bool)

Touches the cache key to drop the dependencies.

public static void TouchKey(string key, bool logTask, bool ensureKey)

Parameters

key string

Key to touch

logTask bool

Log web farm task

ensureKey bool

If true, the keys must be present in the cache, if false, the non-existing key is not touched

TouchKey(string, bool, bool, DateTime)

Touches the cache key to drop the dependencies.

public static void TouchKey(string key, bool logTask, bool ensureKey, DateTime expiration)

Parameters

key string

Key to touch

logTask bool

Log web farm task

ensureKey bool

If true, the keys must be present in the cache, if false, the non-existing key is not touched

expiration DateTime

Expiration time

TouchKeyInternal(string, bool, bool, DateTime)

Touches the cache key to drop the dependencies.

protected virtual void TouchKeyInternal(string key, bool logTask, bool ensureKey, DateTime expiration)

Parameters

key string

Key to touch

logTask bool

Log web farm task

ensureKey bool

If true, the keys must be present in the cache, if false, the non-existing key is not touched

expiration DateTime

Expiration time

TouchKeys(IEnumerable<string>)

Touches the cache key to drop the dependencies.

public static void TouchKeys(IEnumerable<string> keys)

Parameters

keys IEnumerable<string>

Key array to touch

TouchKeys(IEnumerable<string>, bool, bool)

Touches the cache key to drop the dependencies.

public static void TouchKeys(IEnumerable<string> keys, bool logTasks, bool ensureKeys)

Parameters

keys IEnumerable<string>

Key array to touch

logTasks bool

Log web farm tasks

ensureKeys bool

If true, the keys must be present in the cache, if false, the non-existing key is not touched

TouchKeysInternal(IEnumerable<string>, bool, bool)

Touches the cache key to drop the dependencies.

protected virtual void TouchKeysInternal(IEnumerable<string> keys, bool logTasks, bool ensureKeys)

Parameters

keys IEnumerable<string>

Key array to touch

logTasks bool

Log web farm tasks

ensureKeys bool

If true, the keys must be present in the cache, if false, the non-existing key is not touched

TryGetItem<OutputType>(string, bool, out OutputType)

Returns true if the cache contains the item with specified key.

public static bool TryGetItem<OutputType>(string key, bool caseSensitive, out OutputType output)

Parameters

key string

Cache key

caseSensitive bool

Cache key is case sensitive

output OutputType

Returning the value of the object

Returns

bool

Type Parameters

OutputType

TryGetItem<OutputType>(string, out OutputType)

Returns true if the cache contains the item with specified key.

public static bool TryGetItem<OutputType>(string key, out OutputType value)

Parameters

key string

Cache key

value OutputType

Returning the value of the object

Returns

bool

Type Parameters

OutputType