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
[TargetMethod(1)]
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 CacheItemVersion
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 incase 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
[TargetMethod(2)]
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 CacheItemVersion
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 incase 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.Add("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.

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
[TargetMethod(3)]
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 CacheItemVersion
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 incase 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.Add("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.

Add(String, Object, String, String)

Adds a value to the cache

Declaration
[TargetMethod(4)]
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 CacheItemVersion
Examples
Cache cache = NCache.InitializeCache("myCache");
cache.Add("DSN", 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 paramter contains a null reference (Nothing in Visual Basic).

Declaration
[TargetMethod(5)]
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 CacheItemVersion
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 incase of failure.

Examples

The following example demonstrates how to add an item to the cache with no abolute expiration, a sliding expiration of 5 minutes and with a priority of high.

Cache cache = NCache.InitializeCache("myCache");
cache.Add("timestamp", timeStamp, null, 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)

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

Add(String, CacheItem)

Add a CacheItem to the cache

Declaration
[TargetMethod(7)]
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 CacheItemVersion
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

Declaration
[TargetMethod(8)]
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 CacheItemVersion
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.

Declaration
[TargetMethod(9)]
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 CacheItemVersion