CacheManager.Core API Usage

The NCache CacheManager.Core integration allows .NET applications to use the ICacheManager<T> API while storing distributed cache entries in NCache. The integration maps CacheManager.Core operations to NCache cache operations through the NCache cache handle.

This page provides getting-started examples for common CacheManager.Core operations such as adding, retrieving, and removing cache entries with NCache. For the complete CacheManager.Core API reference, see the official CacheManager.Core API documentation.

Note

This feature is supported only in the NCache OpenSource edition.

Prerequisites

Before using CacheManager.Core APIs with NCache, make sure the following prerequisites are fulfilled:

  • Install the following NuGet package in your .NET application:
  • Include the following namespaces in your application:
    • CacheManager.Core
    • NCache.OSS.CacheManager.Core
  • The NCache cache must already exist and must be running.
  • Configure the NCache cache handle by using NCacheOptions.
  • Make sure that the data being cached is serializable.

Add an Item

The Add operation is used when an application wants to insert a new cache entry only if the specified key does not already exist. This is useful for scenarios where duplicate entries should be avoided, such as adding reference data, product details, or session-related information for the first time.

When NCache is configured as a CacheManager.Core cache handle, the NCache handle maps the Add request to the corresponding NCache add operation. If the key already exists, the operation does not overwrite the existing value and returns false.

The following example adds a product entry to the cache using a unique key.

bool added = cache.Add("product:1", "Gaming Laptop");

if (added)
{
    Console.WriteLine("Item added to cache.");
}
else
{
    Console.WriteLine("Item already exists.");
}

The following example adds a product entry to the products region. Regions allow related cache entries to be grouped logically through CacheManager.Core region-based overloads.


bool added = cache.Add("product:1", "Gaming Laptop", "products");

if (added)
{
    Console.WriteLine("Item added to the products region.");
}
else
{
    Console.WriteLine("Item already exists.");
}

Add an Item with Per-Item Expiration

CacheManager.Core also allows applications to add a full CacheItem<T> instead of passing only a key and value. A CacheItem<T> is useful when the application needs to define item-level metadata, such as absolute or sliding expiration, while adding the entry to the cache.

When NCache is configured as a CacheManager.Core cache handle, the NCache handle uses the expiration metadata from the CacheItem<T> and applies the corresponding expiration behavior to the entry stored in NCache.

The following example adds an item with sliding expiration.

var item = new CacheItem<string>(
    "product:1",
    "Gaming Laptop",
    ExpirationMode.Sliding,
    TimeSpan.FromMinutes(30));

bool added = cache.Add(item);

if (added)
{
    Console.WriteLine("Item added with sliding expiration.");
}

Get an Item

The Get operation is used to retrieve a cached value by key. CacheManager.Core checks the configured cache handles in order, starting from the highest-priority handle. If the value is found in an upper-level cache, it is returned immediately. If the value is not found there, CacheManager.Core continues searching the next configured handle, which can include the NCache distributed cache handle.

When NCache is part of the cache handle pipeline, it acts as the distributed cache layer for shared cached data. If the item exists in NCache, the value is returned to the application through the same ICacheManager<T> API.

The following example retrieves a product entry from the cache and checks whether the value exists before using it.

string product = cache.Get("product:1");

if (product != null)
{
    Console.WriteLine(product);
}
else
{
    Console.WriteLine("Item not found in cache.");
}

The following example retrieves a product entry from the products region.

string product = cache.Get("product:1", "products");

if (product != null)
{
    Console.WriteLine(product);
}
else
{
    Console.WriteLine("Item not found in the products region.");
}

Remove an Item

The Remove operation is used to delete a cached item by key. This is useful when cached data is no longer valid, has been updated in the source system, or should no longer be available to the application.

When NCache is configured as a CacheManager.Core cache handle, CacheManager.Core processes the removal through the configured cache handles, and the NCache handle maps the request to the corresponding NCache remove operation.

The following example removes a product entry from the cache and verifies whether the removal operation succeeded.

bool removed = cache.Remove("product:1");

if (removed)
{
    Console.WriteLine("Item removed from cache.");
}
else
{
    Console.WriteLine("Item not found in cache.");
}

The following example removes a product entry from the products region.

bool removed = cache.Remove("product:1", "products");

if (removed)
{
    Console.WriteLine("Item removed from the products region.");
}
else
{
    Console.WriteLine("Item not found in the products region.");
}
Note

Regions are a CacheManager.Core abstraction. Applications should use CacheManager.Core region APIs for grouped cache operations instead of using NCache tags directly.

Other Supported CacheManager.Core APIs

CacheManager.Core provides additional APIs for inserting or replacing entries, checking key existence, clearing cache data, managing expiration, updating cached values, and observing cache lifecycle events. These APIs are available through the same ICacheManager<T> abstraction and are executed through the configured cache handles, including the NCache cache handle.

The following table summarizes other commonly used CacheManager.Core APIs. For complete method signatures, overloads, and advanced usage details, refer to the official CacheManager.Core API documentation.

API Purpose
Put Inserts or replaces a cache item.
Exists Checks whether a key exists without retrieving the cached value.
Clear Removes all items from the configured cache handles.
ClearRegion Removes all items associated with a specific region.
GetCacheItem Retrieves the full CacheItem metadata for a cached entry.
GetOrAdd Retrieves an existing value or adds a value if the key is missing.
TryGetOrAdd Retrieves or adds a value and returns a success flag instead of only returning the cached value.
AddOrUpdate Adds a value if the key is missing, or updates the existing value.
Update Updates an existing cached value.
TryUpdate Updates an existing cached value and returns a success flag.
Expire Applies absolute or sliding expiration to a cached item.
RemoveExpiration Removes expiration from a cached item.
OnAdd, OnPut, OnGet, OnRemove, OnClear Provides event hooks for cache lifecycle operations.
Dispose Releases cache handles and related resources.

For complete method signatures and overloads, see the following CacheManager.Core API references:

See Also

CacheManager.Core with NCache
NCache as CacheManager.Core Provider