Management Operations on Cache

Note

This feature is only available in NCache Enterprise Edition.

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 Web 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.

Pre-Requisites

  • To utilize NCache Management APIs, include the following namespaces in your application:
    • Alachisoft.NCache.Client
    • Alachisoft.NCache.Runtime.Exceptions
  • To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Start Cache Using API calls

StartCache method enables the user to start an OutProc cache on the specified server.

Start Cache

Cache can be started using the StartCache method which starts a cache by getting provided with the server and cache name.

In this example, the user needs to specify cache and server name to start a node.

try
{
    // Initialize cache name and server info

    string cacheName = "myreplicatedcache";
    string serverip = "20.200.20.45";
    int port = 8250;

    // Provide server info to CacheConnection 
    var connection = new CacheConnection(serverip, port);

    // Use CacheConnection to start cache
    CacheManager.StartCache(cacheName, connection);
}
catch (SecurityException ex)
{
    // Permission will be denied if security is enabled
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (CacheException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ALREADY_RUNNING)
    {
        // The cache is already started
    }   
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ID_NOT_REGISTERED)
    {
        // If specified wrong cache name
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Start Cache with Security Enabled

In case security is enabled; the user needs to provide the user credentials to perform any management operations on the cache. StartCache method lets you start a cache with user credentials.

The following example starts a cache with security enabled on it. 

try
{
    // Initialize cache name and server info

    string cacheName = "myreplicatedcache";
    string serverip = "20.200.20.45";
    int port = 8250;

    // Initialize security credentials
    string username = "username";
    string password = "password";

    // Provide server info to CacheConnection 
    var connection = new CacheConnection(serverip, port);

    // Provide user credentials to CacheConnection
    connection.UserCredentials = new Credentials(username, password);

    // Start cache with the security credentials
    CacheManager.StartCache(cacheName, connection);
}
catch (SecurityException ex)
{
    // Permission will be denied if wrong userID or password is provided
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (CacheException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ALREADY_RUNNING)
    {
        // The cache is already started
    }   
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ID_NOT_REGISTERED)
    {
        // If specified wrong cache name
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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 called from the client node, the first server listed in the client configuration file associated with the cache will be stopped. You can stop a cache with enable as well as disabled security. Moreover, cache can also be stopped gracefully by setting the gracefullyShutDownNode flag as true.

Stop Cache

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

try
{
    // Initialize cache name and server info

    string cacheName = "myreplicatedcache";
    string serverip = "20.200.20.45";
    int port = 8250;

    // Provide server info to CacheConnection 
    var connection = new CacheConnection(serverip, port);

    // Stop the cache with the cache name and server
    CacheManager.StopCache(cacheName, connection);
}
catch (SecurityException ex)
{
    // Permission will be denied if wrong userID or password is provided
}
catch(OperationFailedException ex)
{
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (CacheException ex)
{  
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ID_NOT_REGISTERED)
    {
        // If specified wrong cache name
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Stop Cache With Enabled Security

The following example shows how to stop a cache on a particular server with enabled security by providing it with the user credentials.

try
{
    // Initialize cache name and server info

    string cacheName = "myreplicatedcache";
    string serverip = "20.200.20.45";
    int port = 8250;

    // Initialize security credentials
    string username = "username";
    string password = "password";

    // Provide server info to CacheConnection 
    var connection = new CacheConnection(serverip, port);

    // Provide user credentials to CacheConnection
    connection.UserCredentials = new Credentials(username, password);

    // Stop cache with the security credentials
    CacheManager.StopCache(cacheName, connection);
}
catch (SecurityException ex)
{
    // Permission will be denied if wrong userID or password is provided
}
catch (OperationFailedException ex)
{
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (CacheException ex)
{  
    if (ex.ErrorCode == NCacheErrorCodes.CACHE_ID_NOT_REGISTERED)
    {
        // If specified wrong cache name
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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.

You can specify the cache name, the server node and the management port to get the cache health information.

The following example gets the cache health for the cache myreplicatedcache, registered on the server node specified and listens on the port number 8250.

Note

Make sure that you have included the following namespace in your program: Alachisoft.NCache.Runtime.CacheManagement

try
{

    // Specify cache name and server info
    string cacheName = "myreplicatedcache";
    string serverip = "20.200.20.45";
    int port = 8250;

    // Provide server info to CacheConnection 
    var connection = new CacheConnection(serverip, port);

    // You can also specify the port where the cache service will listen
    // Get cache health of the specified
    CacheHealth cacheHealth = CacheManager.GetCacheHealth(cacheName, connection);

    // Shows the cache name, status and topology of the cache
}
catch (OperationFailedException ex)
{
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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.

Connect to Cache

The AppName is a process level unique identifier which can be assigned at the time of cache connection. For this purpose, before connecting to the cache, create an instance of CacheConnectionOptions 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.

try
{
    // Specify the cacheName
    string cacheName = "myPartitionedCache";

    // Create an instance of CacheConnectionOptions
    var options = new CacheConnectionOptions();

    // Assign the custom identifier
    options.AppName = "AssignedAppName";

    // Connect to cache with custom AppName property
    ICache cache = CacheManager.GetCache(cacheName, options);
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
    {
        // Make sure NCache Service is running
        // Make sure that the cache is running
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures: ErrorCode 17506
        // Operation Timeout: ErrorCode 35003
        // Operation performed during state transfer
    }
}
catch (ConfigurationException ex)
{
    if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
    {     
        // client.ncconf must have server information
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
    // Argument exception occurs in case of empty string name
}

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 -

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.MessagingService.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 ConnectedClientList property on the cache as:

IList<ClientInfo> connectedClients = cache.ConnectedClientList;

See Also

Start Cache
Stop Cache