Method Add

Add(String, Object)

Adds 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 Add(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

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");
cache.Add("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.

Add(String, Object, Tag[])

Adds an item into the Cache object 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 Add(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("myPartitionedCache");
Tag[] tags = new Tag[1];
tags[0] = new Tag("tag-name");
string key = "Product0";
Product product = new Product(key);
cache.Add(key, product, 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.

Add(String, Object, NamedTagsDictionary)

Adds an item into the Cache object 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 Add(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("myPartitionedCache");
NamedTagsDictionary namedTags = new NamedTagsDictionary();
namedTags.Add("Attribute", "value");
string key = "Product0";
Product product = new Product(key);
cache.Add(key, product, 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.

Add(String, Object, String, String)

Adds a value to the cache

Declaration
public virtual CacheItemVersion Add(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

An instance of

Examples
Cache cache = NCache.InitializeCache("myCache");
string key = "Product0";
Product product = new Product(key);
cache.Add(key, value, "CONNECTIONS", null);

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

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).

Declaration
public virtual CacheItemVersion Add(string key, object value, CacheDependency dependency, DateTime absoluteExpiration, TimeSpan slidingExpiration, CacheItemPriority priority)
Parameters
Type Name Description
System.String key
System.Object value
CacheDependency dependency
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

An instance of

Remarks

Calls to this method will fail if an item with the same key parameter is already in the Cache. To overwrite an existing Cache item using the same key parameter, use the Insert method.

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown. If you set the slidingExpiration parameter to less than 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 add an item to the cache with no absolute expiration, a sliding expiration of 5 minutes and with a priority of high.

Cache cache = NCache.InitializeCache("myPartitionedCache");
cache.Add("product0", new Product("product0"));
CacheDependency keyDependency = new KeyDependency("product0");
cache.Add("product1", new Product("product1"), keyDependency, Cache.NoAbsoluteExpiration, new TimeSpan(0,5,0), 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.

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

Adds an object in cache having some expiration or priority.

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

Key of the item to be added
System.Object value

value of the item to be added
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

An instance of

Remarks

Calls to this method will fail if an item with the same key parameter is already in the Cache. To overwrite an existing Cache item using the same key parameter, use the Insert method.

Note: If the key or value parameter is null, an System.ArgumentNullException is thrown. If you set the slidingExpiration parameter to less than 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 add an item to the cache with no absolute expiration, a sliding expiration of 5 minutes and with a priority of high.

Cache cache = NCache.InitializeCache("myCache");
cache.Add("timestamp", timeStamp, Cache.NoAbsoluteExpiration, new TimeSpan(0,5,0), 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.

Add(String, CacheItem)

Add a CacheItem to the cache

Declaration
public virtual CacheItemVersion Add(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 an absolute expiration of 2 minutes from now, a priority of high, and that notifies the application when the item is removed from the cache.

First create a CacheItem.

object someData = new object();
CacheItem item = new CacheItem(someData);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(2);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

OnDataSourceItemAdded(IDictionary result)
{
...
}
Cache cache = NCache.InitializeCache("myCache");
cache.Add("someData", item);

Add(String, CacheItem, DSWriteOption, DataSourceItemsAddedCallback)

Add a CacheItem to the cache. Also lets you set DSWriteOption and specify callback that triggers whenever an item is added in the data source.

Declaration
public virtual CacheItemVersion Add(string key, CacheItem item, DSWriteOption dsWriteOption, DataSourceItemsAddedCallback onDataSourceItemAdded)
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
DataSourceItemsAddedCallback onDataSourceItemAdded

A delegate that, if provided, is called when item is added to 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 an absolute expiration of 2 minutes from now, a priority of high, and that notifies the application when the item is removed from the cache.

First create a CacheItem.

object someData = new object();
CacheItem item = new CacheItem(someData);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(2);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

OnDataSourceItemAdded(IDictionary result)
{
...
}
Cache cache = NCache.InitializeCache("myCache");
cache.Add("someData", item, DSWriteOption.WriteBehind, new DataSourceItemsAddedCallback(OnDataSourceItemAdded));

Add(String, CacheItem, DSWriteOption, String, DataSourceItemsAddedCallback)

Add a CacheItem to the cache. You can specify the DSWriteOption along with the data source provider name. Callback can also be registered that will be triggered every time an item is added in data source.

Declaration
public virtual CacheItemVersion Add(string key, CacheItem item, DSWriteOption dsWriteOption, string providerName, DataSourceItemsAddedCallback onDataSourceItemAdded)
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
System.String providerName

A unique identifier for the data source
DataSourceItemsAddedCallback onDataSourceItemAdded

A delegate that, if provided, is called when item is added to data source
Returns
Type Description
CacheItemVersion

An instance of

Examples

The following example demonstrates how to add an item to the cache with DSWriteOption specified.

First create a CacheItem.

object someData = new object();
CacheItem item = new CacheItem(someData);
item.AbsoluteExpiration = DateTime.Now.AddMinutes(2);
item.Priority = CacheItemPriority.High;
item.ItemRemoveCallback = onRemove;

Then add CacheItem to the cache

OnDataSourceItemAdded(IDictionary result)
{
...
}
Cache cache = NCache.InitializeCache("myCache");
cache.Add("someData", item, DSWriteOption.WriteBehind, "ProdDataSource1", new DataSourceItemsAddedCallback(OnDataSourceItemAdded));