Named Tags

You can associate one or more keywords with cache items in NCache. These keywords will act as an identifying mark for cache items. You can retrieve that data later on the basis of specified keywords through "Tags". But if you require a higher level of tagging where your tags can have types or names, and your requirement is to query data related to specific type of tag, then you need “Named Tags”. The “Named Tags" feature set is the enhancement of the "Tags" feature set.

Consider a scenario where user needs to store an object in textual form such as "XML", he will not be able to search that object using tags. The limitation of tags is that it can only have text values and only one attribute i.e. Tag. With named tags user will be able to store additional information (of any type) required to query the object stored as string.

Here users are required to provide the list of named tags, each having two parameters, "key" (name of a tag) as string and "value" (assigned value) as any primitive type. NCache then allows you to search your objects through these named tags.

Creating Named Tags

To utilize the APIs, include the following namespace in your application: Alachisoft.NCache.Web.Caching.

A NamedTagsDictionary is a class provided by NCache so you can associate these tags with a particular data.

NamedTagsDictionary productNamedTag = new NamedTagsDictionary();
productNamedTag.Add("UnitsAvailable", 4);
productNamedTag.Add("Category", 25);
productNamedTag.Add("Supplier", "Alex");

Adding item to cache with Named Tags

In this example, Add Operation overload is used to associate named tags previously created.

Product product = new Product();
product.ProductID = 1001;
product.ProductName = "Chai";
string key = "Product:" + product.ProductID;
try
{
    cache.Add(key, product, productNamedTag);
}
catch (OperationFailedException ex)
{
    // handle exception
}

Adding Named Tags through CacheItem

In the following example named tags are set by assigning them as a property of CacheItem.

CacheItem cacheItem = new CacheItem(product);
cacheItem.NamedTags = productNamedTag;
try
{
    cache.Add(key, cacheItem);
}
catch (OperationFailedException ex)
{
    // handle exception
}

Querying Cache Items with respect to Named Tags

In the following code example please specify the fully qualified name of your custom class instead of 'Product' in the query string.

string query = "SELECT Product WHERE this.Supplier = ?";
Hashtable values = new Hashtable();
values.Add("UnitsInStock", 4);
values.Add("Supplier", "Alex");
try
{
    ICacheReader queryResult = cache.ExecuteReader(query, values, true);
    //queryResult contains all keys related to both tags.
if (queryResult.FieldCount > 0)
{
       while (queryResult.Read())
       {
            //perform operations
       }
    }
    else{
        //no record exists
    }
}
catch (OperationFailedException ex){
    //handle exception
}

Note

If you have multiple applications that are sharing the same cache and all of them are supposed to add named tags, then make sure that same named tags have homogenous data types. E.g. If one client is adding named tag ProductID with String data type then all other clients should add values of ProductID only in String format for same cache.

Troubleshooting

IndexNotDefinedException

In case no Named Tag has been added to a cache and the cache is searched with ExecuteReader for Named Tag values, you get IndexNotDefinedException. If you want that no such exception should be thrown even if you have not added any Named Tag to your cache, NCache now provides a way to disable this exception.

Workaround

You can suppress this exception by following these steps:

• Go to Alachisoft.NCache.Service.exe.config located at [InstallDir]/bin/service/.

• Add the following line in the configuration file:

  <add key = "NCacheServer.DisableIndexNotDefinedException" value = "true" />

The value true indicates that no IndexNotDefinedException will be thrown, whereas, the value false means that the exception will be thrown.

• Restart the NCache service for these changes to take effect.