Cache.Add Method (System.Web.Caching)

.NET Framework Class Library

Cache..::.Add Method

Adds the specified item to 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.

Namespace: System.Web.Caching
Assembly: System.Web (in System.Web.dll)

Syntax

Visual Basic (Declaration)

Public Function Add ( _
    key As String, _
    value As Object, _
    dependencies As CacheDependency, _
    absoluteExpiration As DateTime, _
    slidingExpiration As TimeSpan, _
    priority As CacheItemPriority, _
    onRemoveCallback As CacheItemRemovedCallback _
) As Object

Visual Basic (Usage)

Dim instance As Cache
Dim key As String
Dim value As Object
Dim dependencies As CacheDependency
Dim absoluteExpiration As DateTime
Dim slidingExpiration As TimeSpan
Dim priority As CacheItemPriority
Dim onRemoveCallback As CacheItemRemovedCallback
Dim returnValue As Object

returnValue = instance.Add(key, value, _
    dependencies, absoluteExpiration, _
    slidingExpiration, priority, onRemoveCallback)

public Object Add(
    string key,
    Object value,
    CacheDependency dependencies,
    DateTime absoluteExpiration,
    TimeSpan slidingExpiration,
    CacheItemPriority priority,
    CacheItemRemovedCallback onRemoveCallback
)

Visual C++

public:
Object^ Add(
    String^ key, 
    Object^ value, 
    CacheDependency^ dependencies, 
    DateTime absoluteExpiration, 
    TimeSpan slidingExpiration, 
    CacheItemPriority priority, 
    CacheItemRemovedCallback^ onRemoveCallback
)

JScript

public function Add(
    key : String, 
    value : Object, 
    dependencies : CacheDependency, 
    absoluteExpiration : DateTime, 
    slidingExpiration : TimeSpan, 
    priority : CacheItemPriority, 
    onRemoveCallback : CacheItemRemovedCallback
) : Object

Parameters

key: Type: System..::.String
The cache key used to reference the item.

value: Type: System..::.Object
The item to be added to the cache.

dependencies: Type: System.Web.Caching..::.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 nullNothingnullptra null reference (Nothing in Visual Basic).

absoluteExpiration: Type: System..::.DateTime
The time at which the added object expires and is removed from the cache. If you are using sliding expiration, the absoluteExpiration parameter must be NoAbsoluteExpiration.

slidingExpiration: Type: System..::.TimeSpan
The interval between the time the added object was last accessed and the time at which 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. If you are using absolute expiration, the slidingExpiration parameter must be NoSlidingExpiration.

priority: Type: System.Web.Caching..::.CacheItemPriority
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.

onRemoveCallback: Type: System.Web.Caching..::.CacheItemRemovedCallback
A delegate that, if provided, is called when an object is removed from the cache. You can use this to notify applications when their objects are deleted from the cache.

Return Value

Type: System..::.Object
An object that represents the item that was added if the item was previously stored in the cache; otherwise, nullNothingnullptra null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
ArgumentNullException	The key or value parameter is set to nullNothingnullptra null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException	The slidingExpiration parameter is set to less than TimeSpan.Zero or more than one year.
ArgumentException	The absoluteExpiration and slidingExpiration parameters are both set for the item you are trying to add to the Cache.

Remarks

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

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 item was last accessed, you set the slidingExpiration parameter to the expiration interval, and the absoluteExpiration parameter to NoAbsoluteExpiration.

Examples

The following example creates an AddItemToCache method. When this method is called, it sets an itemRemoved property to false and registers an onRemove method with a new instance of the CacheItemRemovedCallback delegate. The delegate's signature is used in the RemovedCallback method. The AddItemToCache method then checks the value associated with the Key1 key in the cache. If the value is nullNothingnullptra null reference (Nothing in Visual Basic), the Add method places an item in the cache with a key of Key1, a value of Value 1, an absolute expiration of 60 seconds, and a high cache priority. It also uses the onRemove method as an argument. This allows the RemovedCallback method to be called when this item is removed from the cache.

Note:
For examples of how to use the CacheDependency class and the CacheItemRemovedCallback delegate, see Caching Application Data.

Visual Basic

Public Sub AddItemToCache(sender As Object, e As EventArgs)
    itemRemoved = false

    onRemove = New CacheItemRemovedCallback(AddressOf Me.RemovedCallback)

    If (IsNothing(Cache("Key1"))) Then
      Cache.Add("Key1", "Value 1", Nothing, DateTime.Now.AddSeconds(60), Cache.NoSlidingExpiration, CacheItemPriority.High, onRemove)
    End If
End Sub

public void AddItemToCache(Object sender, EventArgs e) {
    itemRemoved = false;

    onRemove = new CacheItemRemovedCallback(this.RemovedCallback);

    if (Cache["Key1"] == null)
      Cache.Add("Key1", "Value 1", null, DateTime.Now.AddSeconds(60), Cache.NoSlidingExpiration, CacheItemPriority.High, onRemove);
}

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information