NCache Management API

NCache Management API is a set of programmable method calls that enable the user to perform basic management operations on out-proc caches without using either NCache Manager or NCache tools. The Management API in some cases relies on the client configuration files to perform an operation, whereas in some cases it is self-sufficient to execute a request.

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

Start Cache Using API calls

StartCache methods enable the user to start an OutProc cache on the specified server. In case of failure, ManagementException is thrown by the cache. In this example, the user need to specify cache and server name to start a node.

//precondition: Cache has been registered but not initialized.
string cacheName = "mycache";
string serverName = "...."; // specify the server where cache is registered
try
{
    CacheManager.StartCache(cacheName, serverName);
}
catch (ManagementException ex)
{
    //thrown if no cache exists or server name is invalid
}

Important

In case you have security enabled, please refer to the section Security Configuration of Administrator Guide to stop and start cache cluster.

Stop Cache Using API calls

StopCache method is used to stop a cache on a particular server. If no server is specified, the method would read information from client configuration file. If the method fails to stop the cache or fails to find information regarding the cache, ManagementException is thrown. If called from the client node, the first server listed in the client configuration file associated with the cache will be stopped.

This example stops cache on an already started node. Cache and server name to stop cache on given node need to be specified.

try
{
    CacheManager.StopCache(cacheName, serverName);
}
catch (ManagementException ex)
{
    // handle exception
}

Important

In case you have security enabled, please refer to the section Security Configuration of Administrator Guide to stop and start cache cluster.

Viewing Cache Status Using API calls

GetCacheHealth method enables the user to view the status of cache server nodes. This method call returns a CacheHealth object against every call.

try
{
    CacheHealth cacheHealth = CacheManager.GetCacheHealth(cacheName);
}
catch (ManagementException)
{
    // handle exception
}

Monitoring Clients Connected to Cache

NCache provides the feature of enabling Client Activity Events. Using these events, each client that is connected to a clustered cache can subscribe to be notified about the connect/disconnect events of other clients. Each client can also specify a process level custom identifier which will be returned to the subscriber in case the client which specified it connects to or disconnects from a clustered cache.

Client Activity Events are fired when a client connects to or disconnects from a specified cache. These events are registered against the specified cache and will be handled in a user defined callback method.

Note

Make sure that client events have been enabled through NCache Manager before proceeding to use them.

To utilize the APIs, include the following namespaces in your application: -Alachisoft.NCache.Web.dll -Alachisoft.NCache.Runtime.dll

Create Event Callback Method

The callback method is user defined and is called once the clients are connected/disconnected from the cache. The method is registered against the CacheClientConnectivityChanged event property of CacheClientConnectivityChangedCallback type in a specific cache. Hence, the method created should match the signature of the delegate:

public delegate void CacheClientConnectivityChangedCallback(string cacheId, ClientInfo client, ConnectivityStatus status);

The method created contains the following parameters:

//user defined event callback method
static void MyClientConnectivityCallback(string cacheName, ClientInfo clientInfo, ConnectivityStatus status)
{
    //handle event
}

Parameters	Description
cacheName	Name of the cache with which the clients are connected or disconnected. This acts as the sender of the event.
status	Enum which determines the connectivity status of the client: Disconnected = 0 Connected =1
clientInfo	An object of the ClientInfo class containing information regarding the client which caused the event to fire.

Client Info class

Member	Description	Default Value
AppName	User assigned, process-level, unique identifier	Client process ID
ClientID	Unique client identifier	-
IPAddress	IP through which the client is connected	-
MachineName	Machine Name of the client	-
ProcessID	Process ID of the client	-

Initialize Cache

The AppName is a process level unique identifier which can be assigned at the time of initialization. For this purpose, before initializing the cache client, create an instance of CacheInitParams and assign a custom identifier string to its AppName property.

Thus, if this client connects or disconnects, the callbacks of all the clients which subscribed to the Client will get this AppName in their ClientInfo instance.

string cacheName = "myPartitionedCache";

CacheInitParams initParams = new CacheInitParams();
initParams.AppName = "AssignedAppName"; //assign custom identifier

//initialize cache with custom AppName property
Cache cache = NCache.InitializeCache(cacheName, initParams);

Register Event

The method is registered by appending it to the CacheClientConnectivityChanged property as an event callback. This enables the client to listen for connect/disconnect events of other clients. If another client connects to or disconnects from the specified cache, the callback method is called.

//register method to event
cache.CacheClientConnectivityChanged += MyClientConnectivityCallback;

Monitor Client Info of Connected Clients

The ClientInfo of each connected client is available locally in the form of cache.ClientInfo property.

ClientInfo info = cache.ClientInfo;
string AppName = info.AppName;
string clientID = info.ClientID;
System.Net.IPAddress ip = info.IPAddress;
string machineName = info.MachineName;
int processID = info.ProcessID;

View List of Connected Clients

To get information of all the clients connected to the cache on demand, use the GetConnectedClientsList() method on the cache as:

IList<ClientInfo> connectedClients = cache.GetConnectedClientsList();