Cache.Insert Method

Definition

Namespace:

System.Web.Caching

Assembly:

System.Web.dll

Inserts an item into the Cache object. Use one of the versions of this method to overwrite an existing Cache item with the same key parameter.

Overloads

Insert(String, Object, CacheDependency, DateTime, TimeSpan, CacheItemPriority, CacheItemRemovedCallback)	Inserts an object into the Cache object with dependencies, expiration and priority policies, and a delegate you can use to notify your application when the inserted item is removed from the Cache.
Insert(String, Object, CacheDependency, DateTime, TimeSpan, CacheItemUpdateCallback)	Inserts an object into the Cache object together with dependencies, expiration policies, and a delegate that you can use to notify the application before the item is removed from the cache.
Insert(String, Object, CacheDependency)	Inserts an object into the Cache that has file or key dependencies.
Insert(String, Object)	Inserts an item into the Cache object with a cache key to reference its location, using default values provided by the CacheItemPriority enumeration.
Insert(String, Object, CacheDependency, DateTime, TimeSpan)	Inserts an object into the Cache with dependencies and expiration policies.

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

Inserts an object into the Cache object with dependencies, expiration and priority policies, and a delegate you can use to notify your application when the inserted item is removed from the Cache.

public:
 void Insert(System::String ^ key, System::Object ^ value, System::Web::Caching::CacheDependency ^ dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration, System::Web::Caching::CacheItemPriority priority, System::Web::Caching::CacheItemRemovedCallback ^ onRemoveCallback);

public void Insert (string key, object value, System.Web.Caching.CacheDependency dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration, System.Web.Caching.CacheItemPriority priority, System.Web.Caching.CacheItemRemovedCallback onRemoveCallback);

member this.Insert : string * obj * System.Web.Caching.CacheDependency * DateTime * TimeSpan * System.Web.Caching.CacheItemPriority * System.Web.Caching.CacheItemRemovedCallback -> unit

Public Sub Insert (key As String, value As Object, dependencies As CacheDependency, absoluteExpiration As DateTime, slidingExpiration As TimeSpan, priority As CacheItemPriority, onRemoveCallback As CacheItemRemovedCallback)

Parameters

key

String

The cache key used to reference the object.

value

Object

The object to be inserted in the cache.

dependencies

CacheDependency

The file or cache key dependencies for the item. When any dependency changes, the object becomes invalid and is removed from the cache. If there are no dependencies, this parameter contains null.

absoluteExpiration

DateTime

The time at which the inserted object expires and is removed from the cache. To avoid possible issues with local time such as changes from standard time to daylight saving time, use UtcNow rather than Now for this parameter value. If you are using absolute expiration, the slidingExpiration parameter must be NoSlidingExpiration.

slidingExpiration

TimeSpan

The interval between the time the inserted object was last accessed and the time at which that object expires. If this value is the equivalent of 20 minutes, the object will expire and be removed from the cache 20 minutes after it was last accessed. If you are using sliding expiration, the absoluteExpiration parameter must be NoAbsoluteExpiration.

priority

CacheItemPriority

The cost of the object relative to other items stored in the cache, as expressed by the CacheItemPriority enumeration. This value is used by the cache when it evicts objects; objects with a lower cost are removed from the cache before objects with a higher cost.

onRemoveCallback

CacheItemRemovedCallback

A delegate that, if provided, will be called when an object is removed from the cache. You can use this to notify applications when their objects are deleted from the cache.

Exceptions

ArgumentNullException

The key or value parameter is null.

ArgumentOutOfRangeException

You set the slidingExpiration parameter to less than TimeSpan.Zero or the equivalent of more than one year.

ArgumentException

The absoluteExpiration and slidingExpiration parameters are both set for the item you are trying to add to the Cache.

Examples

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

Note

For more information about how to use this method with the CacheItemRemovedCallback delegate, see How to: Notify an Application When an Item Is Removed from the Cache.

Cache.Insert("DSN", connectionString, null, DateTime.Now.AddMinutes(2), TimeSpan.Zero, CacheItemPriority.High, onRemove);

Cache.Insert("DSN", connectionString, Nothing, DateTime.Now.AddMinutes(2), TimeSpan.Zero, CacheItemPriority.High, onRemove)

Remarks

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

You cannot set both the absoluteExpiration and slidingExpiration parameters. If you intend the cache item to expire at a specific time, you set the absoluteExpiration parameter to the specific time, and the slidingExpiration parameter to NoSlidingExpiration.

If you intend the cache item to expire after a certain amount of time has passed since the last access to the item, you set the slidingExpiration parameter to the expiration interval, and the absoluteExpiration parameter to NoAbsoluteExpiration.

See also

• DateTime
• TimeSpan
• CacheItemPriority
• CacheItemRemovedCallback
• Caching Application Data

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

Inserts an object into the Cache object together with dependencies, expiration policies, and a delegate that you can use to notify the application before the item is removed from the cache.

public:
 void Insert(System::String ^ key, System::Object ^ value, System::Web::Caching::CacheDependency ^ dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration, System::Web::Caching::CacheItemUpdateCallback ^ onUpdateCallback);

public void Insert (string key, object value, System.Web.Caching.CacheDependency dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration, System.Web.Caching.CacheItemUpdateCallback onUpdateCallback);

member this.Insert : string * obj * System.Web.Caching.CacheDependency * DateTime * TimeSpan * System.Web.Caching.CacheItemUpdateCallback -> unit

Public Sub Insert (key As String, value As Object, dependencies As CacheDependency, absoluteExpiration As DateTime, slidingExpiration As TimeSpan, onUpdateCallback As CacheItemUpdateCallback)

Parameters

key

String

The cache key that is used to reference the object.

value

Object

The object to insert into the cache.

dependencies

CacheDependency

The file or cache key dependencies for the item. When any dependency changes, the object becomes invalid and is removed from the cache. If there are no dependencies, this parameter contains null.

absoluteExpiration

DateTime

The time at which the inserted object expires and is removed from the cache. To avoid possible issues with local time such as changes from standard time to daylight saving time, use UtcNow instead of Now for this parameter value. If you are using absolute expiration, the slidingExpiration parameter must be set to NoSlidingExpiration.

slidingExpiration

TimeSpan

The interval between the time that the cached object was last accessed and the time at which that object expires. If this value is the equivalent of 20 minutes, the object will expire and be removed from the cache 20 minutes after it was last accessed. If you are using sliding expiration, the absoluteExpiration parameter must be set to NoAbsoluteExpiration.

onUpdateCallback

CacheItemUpdateCallback

A delegate that will be called before the object is removed from the cache. You can use this to update the cached item and ensure that it is not removed from the cache.

Exceptions

ArgumentNullException

The key, value, or onUpdateCallback parameter is null.

ArgumentOutOfRangeException

You set the slidingExpiration parameter to less than TimeSpan.Zero or the equivalent of more than one year.

ArgumentException

The absoluteExpiration and slidingExpiration parameters are both set for the item you are trying to add to the Cache.

-or-

The dependencies parameter is null, and the absoluteExpiration parameter is set to NoAbsoluteExpiration, and the slidingExpiration parameter is set to NoSlidingExpiration.

Remarks

The Insert method enables you to insert a new item in the cache and provide a delegate that is called before the item is removed from the cache. In the delegate, you can update the cached item and thereby prevent it from being removed from the cache.

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

You cannot set both the absoluteExpiration and slidingExpiration parameters. If you intend the cache item to expire at a specific time, you set the absoluteExpiration parameter to the specific time, and the slidingExpiration parameter to NoSlidingExpiration.

If you intend the cache item to expire after a set period of time since the item was last accessed, you set the slidingExpiration parameter to the expiration interval, and you set the absoluteExpiration parameter to NoAbsoluteExpiration.

See also

• CacheItemUpdateCallback

Insert(String, Object, CacheDependency)

Inserts an object into the Cache that has file or key dependencies.

public:
 void Insert(System::String ^ key, System::Object ^ value, System::Web::Caching::CacheDependency ^ dependencies);

public void Insert (string key, object value, System.Web.Caching.CacheDependency dependencies);

member this.Insert : string * obj * System.Web.Caching.CacheDependency -> unit

Public Sub Insert (key As String, value As Object, dependencies As CacheDependency)

Parameters

key

String

The cache key used to identify the item.

value

Object

The object to be inserted in the cache.

dependencies

CacheDependency

The file or cache key 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 null.

Exceptions

ArgumentNullException

The key or value parameter is null.

Examples

The following example demonstrates how to insert an item into an application's cache with a cache dependency on an XML configuration file.

Cache.Insert("DSN", connectionString, new CacheDependency(Server.MapPath("myconfig.xml")));

Cache.Insert("DSN", connectionString, New CacheDependency(Server.MapPath("myconfig.xml")))

Remarks

This method will overwrite an existing cache item whose key matches the key parameter. The object added to the cache using this overload of the Insert method is inserted with a priority of Default, a sliding expiration value of NoSlidingExpiration, and an absolute expiration value of NoAbsoluteExpiration.

See also

• CacheDependency

Insert(String, Object)

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

public:
 void Insert(System::String ^ key, System::Object ^ value);

public void Insert (string key, object value);

member this.Insert : string * obj -> unit

Public Sub Insert (key As String, value As Object)

Parameters

key

String

The cache key used to reference the item.

value

Object

The object to be inserted into the cache.

Exceptions

ArgumentNullException

The key or value parameter is null.

Examples

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

Cache.Insert("DSN", connectionString);

Cache.Insert("DSN", connectionString)

Remarks

This method will overwrite an existing cache item whose key matches the key parameter. The object added to the cache using this overload of the Insert method is inserted with no file or cache dependencies, a priority of Default, a sliding expiration value of NoSlidingExpiration, and an absolute expiration value of NoAbsoluteExpiration.

See also

• Caching Application Data

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

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

public:
 void Insert(System::String ^ key, System::Object ^ value, System::Web::Caching::CacheDependency ^ dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration);

public void Insert (string key, object value, System.Web.Caching.CacheDependency dependencies, DateTime absoluteExpiration, TimeSpan slidingExpiration);

member this.Insert : string * obj * System.Web.Caching.CacheDependency * DateTime * TimeSpan -> unit

Public Sub Insert (key As String, value As Object, dependencies As CacheDependency, absoluteExpiration As DateTime, slidingExpiration As TimeSpan)

Parameters

key

String

The cache key used to reference the object.

value

Object

The object to be inserted in the cache.

dependencies

CacheDependency

The file or cache key 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 null.

absoluteExpiration

DateTime

The time at which the inserted object expires and is removed from the cache. To avoid possible issues with local time such as changes from standard time to daylight saving time, use UtcNow rather than Now for this parameter value. If you are using absolute expiration, the slidingExpiration parameter must be NoSlidingExpiration.

slidingExpiration

TimeSpan

The interval between the time the inserted object is last accessed and the time at which that object expires. If this value is the equivalent of 20 minutes, the object will expire and be removed from the cache 20 minutes after it was last accessed. If you are using sliding expiration, the absoluteExpiration parameter must be NoAbsoluteExpiration.

Exceptions

ArgumentNullException

The key or value parameter is null.

ArgumentOutOfRangeException

You set the slidingExpiration parameter to less than TimeSpan.Zero or the equivalent of more than one year.

ArgumentException

The absoluteExpiration and slidingExpiration parameters are both set for the item you are trying to add to the Cache.

Examples

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

Note

Since this form of the Insert method supports cache dependencies, if the item has no dependencies, you must declare the dependency parameter as null (Nothing in Visual Basic) in the comma-delimited list of parameters.

Cache.Insert("DSN", connectionString, null, DateTime.Now.AddMinutes(2), Cache.NoSlidingExpiration);

Cache.Insert("DSN", connectionString, Nothing, DateTime.Now.AddMinutes(2), Cache.NoSlidingExpiration)

The following example demonstrates how to insert an item into the cache with a sliding expiration.

Cache.Insert("DSN", connectionString, null, Cache.NoAbsoluteExpiration, TimeSpan.FromSeconds(10));

Cache.Insert("DSN", connectionString, Nothing, Cache.NoAbsoluteExpiration, TimeSpan.FromSeconds(10))

Remarks

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

If the slidingExpiration parameter is set to NoSlidingExpiration, sliding expiration is disabled. If you set the slidingExpiration parameter to greater than Zero, the absoluteExpiration parameter is set to Now plus the value contained in the slidingExpiration parameter. If the item is requested from the cache before the amount of time specified by the absoluteExpiration parameter, the item will be placed in the cache again, and absoluteExpiration will again be set to DateTime.Now plus the value contained in the slidingExpiration parameter. If the item is not requested from the cache before the date in the absoluteExpiration parameter, the item is removed from the cache. The item added to the cache using this overload of the insert method is inserted with a priority of Default.

See also

• DateTime
• TimeSpan
• Caching Application Data