Method Insert

Insert(String, Object)

Inserts an item into the Cache object with a cache key to reference its location and using default values provided by the CacheItemPriority enumeration.

Declaration
public virtual CacheItemVersion Insert(string key, object value)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The item to be added to the cache.
Returns
Type Description
CacheItemVersion
Remarks

This method will overwrite an existing Cache item with the same key parameter.

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception in case of failure.

Examples

The following example demonstrates how to insert an item into an application's cache.

Cache cache = NCache.InitializeCache("myCache");
cache.Insert("DSN", connectionString);
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

Insert(String, Object, String, String)

Insert a value to the cache

Declaration
public virtual CacheItemVersion Insert(string key, object value, string group, string subGroup)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The value that is to be stored
System.String group

The data group of the item
System.String subGroup

The data group of the item
Returns
Type Description
CacheItemVersion
Examples
Cache cache = NCache.InitializeCache("myCache");
cache.Insert("DSN", value, "CONNECTIONS", null);

Insert(String, Object, NamedTagsDictionary)

Inserts an item into the Cache with a cache key to reference its location and using default values provided by the CacheItemPriority enumeration. It also enables associating named tags with the object.

Declaration
public virtual CacheItemVersion Insert(string key, object value, NamedTagsDictionary namedTags)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The item to be added to the cache.
NamedTagsDictionary namedTags

A NamedTagsDictionary to associate with the object.
Returns
Type Description
CacheItemVersion

An instance of

Remarks

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception in case of failure.

Examples

The following example demonstrates how to add an item into an application's cache.

Cache cache = NCache.InitializeCache("myCache");
NamedTagsDictionary namedTags = new NamedTagsDictionary();
namedTags.Add("Attribute", "value");
cache.Insert("DSN", connectionString, namedTags);
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

Insert(String, Object, Tag[])

Inserts an item into the Cache with a cache key to reference its location and using default values provided by the CacheItemPriority enumeration. It also enables the associating tags with the object.

Declaration
public virtual CacheItemVersion Insert(string key, object value, Tag[] tags)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The item to be added to the cache.
Tag[] tags

An array of Tag to associate with the object.
Returns
Type Description
CacheItemVersion

An instance of

Remarks

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception in case of failure.

Examples

The following example demonstrates how to add an item into an application's cache.

Cache cache = NCache.InitializeCache("myCache");
Tag[] tags = new Tag[1];
tags[0] = new Tag("tag-name");
cache.Insert("DSN", connectionString, tags);
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

Insert(String, Object, CacheDependency, DateTime, TimeSpan, CacheItemPriority)

Inserts an object into the Cache with dependencies, expiration and priority policies.

Declaration
public virtual CacheItemVersion Insert(string key, object value, CacheDependency dependency, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The item to be added to the cache.
CacheDependency dependency

The file dependencies for the inserted object. When any dependency changes, the object becomes invalid and is removed from the cache. If there are no dependencies, this parameter contains a null reference (Nothing in Visual Basic).
System.DateTime absoluteExpiration

The time at which the added object expires and is removed from the cache.
System.TimeSpan slidingExpiration

The interval between the time the added object was last accessed and when that object expires. If this value is the equivalent of 20 minutes, the object expires and is removed from the cache 20 minutes after it is last accessed.
CacheItemPriority priority

The relative cost of the object, as expressed by the CacheItemPriority enumeration. The cache uses this value when it evicts objects; objects with a lower cost are removed from the cache before objects with a higher cost.
Returns
Type Description
CacheItemVersion
Remarks

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown. If you set the slidingExpiration parameter to less than System.TimeSpan.Zero, or the equivalent of more than one year, an System.ArgumentOutOfRangeException is thrown. You cannot set both sliding and absolute expirations on the same cached item. If you do so, an System.ArgumentException is thrown.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception in case of failure.

Examples

The following example demonstrates how to assign an item high priority when you insert it into your application's Cache object.

Cache cache = NCache.InitializeCache("myCache");
cache.Insert("DSN", connectionString, null, DateTime.Now.AddMinutes(2), TimeSpan.Zero, CacheItemPriority.High);
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

Insert(String, Object, DateTime, TimeSpan, CacheItemPriority)

Inserts an object into the Cache with dependencies, expiration and priority policies.

Declaration
public virtual CacheItemVersion Insert(string key, object value, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
System.Object value

The item to be added to the cache.
System.DateTime absoluteExpiration

The time at which the added object expires and is removed from the cache.
System.TimeSpan slidingExpiration

The interval between the time the added object was last accessed and when that object expires. If this value is the equivalent of 20 minutes, the object expires and is removed from the cache 20 minutes after it is last accessed.
CacheItemPriority priority

The relative cost of the object, as expressed by the CacheItemPriority enumeration. The cache uses this value when it evicts objects; objects with a lower cost are removed from the cache before objects with a higher cost.
Returns
Type Description
CacheItemVersion
Remarks

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown. If you set the slidingExpiration parameter to less than System.TimeSpan.Zero, or the equivalent of more than one year, an System.ArgumentOutOfRangeException is thrown. You cannot set both sliding and absolute expirations on the same cached item. If you do so, an System.ArgumentException is thrown.

Note: If exceptions are enabled through the ExceptionsEnabled setting, this property throws exception in case of failure.

Examples

The following example demonstrates how to assign an item high priority when you insert it into your application's Cache object.

Cache cache = NCache.InitializeCache("myCache");
cache.Insert("DSN", connectionString, null, DateTime.Now.AddMinutes(2), TimeSpan.Zero, CacheItemPriority.High);
Exceptions
Type Condition
System.ArgumentNullException

key or value contains a null reference (Nothing in Visual Basic).
System.ArgumentException

key or value is not serializable.

Insert(String, CacheItem)

Add a CacheItem to the cache

Declaration
public virtual CacheItemVersion Insert(string key, CacheItem item)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
CacheItem item

The item that is to be stored
Returns
Type Description
CacheItemVersion

An instance of

Remarks

If CacheItem contains invalid values the related exception is thrown. See CacheItem for invalid property values and related exceptions

Examples

The following example demonstrates how to add an item to the cache with a sliding expiration of 5 minutes and a priority of high, and that notifies the application when the item is removed from the cache.

First create a CacheItem.

CacheItem item = new CacheItem(timeStamp);
item.SlidingExpiration = new TimeSpan(0,5,0);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

Cache cache = NCache.InitializeCache("myCache");
cache.Insert("timestamp", item);

Insert(String, CacheItem, DSWriteOption, DataSourceItemsUpdatedCallback)

Update a CacheItem in the cache. If item does not exist in cache then it is added. You can specify a delegate for notifying whenever an item is updated in cache.

Declaration
public virtual CacheItemVersion Insert(string key, CacheItem item, DSWriteOption dsWriteOption, DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
CacheItem item

The item that is to be stored
DSWriteOption dsWriteOption

Options regarding updating data source
DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback

A delegate that, if provided, is called when item is updated in data source.
Returns
Type Description
CacheItemVersion

An instance of

Remarks

If CacheItem contains invalid values the related exception is thrown. See CacheItem for invalid property values and related exceptions

Examples

The following example demonstrates how to add an item to the cache with a sliding expiration of 5 minutes, a priority of high, and that notifies the application when the item is removed from the cache.

First create a CacheItem.

CacheItem item = new CacheItem(timeStamp);
item.SlidingExpiration = new TimeSpan(0,5,0);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

Cache cache = NCache.InitializeCache("myCache");
cache.Insert("timestamp", item, DSWriteOption.WriteThru, new DataSourceItemsUpdatedCallback(OnDSItemsUpdated));

Insert(String, CacheItem, DSWriteOption, String, DataSourceItemsUpdatedCallback)

Inserts a CacheItem to the cache if not already existing. Otherwise updates an existing item. Notifies if the item is updated in data source.

Declaration
public virtual CacheItemVersion Insert(string key, CacheItem item, DSWriteOption dsWriteOption, string providerName, DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback)
Parameters
Type Name Description
System.String key

Specifies the key of the object.
CacheItem item

Specifies what is being added in cache.
DSWriteOption dsWriteOption

Enum for setting DSWriteOption
System.String providerName

Specifies the provider name of the data source.
DataSourceItemsUpdatedCallback onDataSourceItemUpdatedCallback

Specifies if notification is to be enabled if item is updated in data source.
Returns
Type Description
CacheItemVersion

CacheItemVersion; the version of the item being updated in cache.

Insert(String, CacheItem, LockHandle, Boolean)

Inserts a CacheItem to the cache if not already existing. Otherwise updates an existing item if it not already locked or if the correct lock-id is specified.

Declaration
public virtual CacheItemVersion Insert(string key, CacheItem item, LockHandle lockHandle, bool releaseLock)
Parameters
Type Name Description
System.String key

The cache key used to reference the item.
CacheItem item

The item that is to be stored
LockHandle lockHandle

An instance of . If the item is locked, then it can be updated only if the correct lockHandle is specified.
System.Boolean releaseLock

A flag to determine whether or not release lock after operation is performed.
Returns
Type Description
CacheItemVersion

The object item added to the Cache.
Remarks

If lockId does not match with the lockId associated with cached item, an exception will be thrown.

Examples

The following example demonstrates how to update a locked item in the cache.

First create a CacheItem.

Cache theCache = NCache.InitializeCache("myreplicatedcache");

Add an item int the cache.

theCache.Add("cachedItemKey", new CacheItem("cachedItemValue"));

Create the objects for lockid and lockdate.

LockHandle lockHandle = new LockHandle();

Get the added item from cache and acquire a lock.

object cachedItem = theCache.Get("cachedItemKey", Cache.NoLockingExpiration, ref lockHandle, true);
if (cachedItem != null)
{
    try
    {
        theCache.Insert("cachedItemKey", new CacheItem("someothervalue"), lockHandle, true);
        string cachedValue = (string)theCache.Get("cachedItemKey");
    }
    catch (OperationFailedException ex)
    {
        //Do something
    }
}