External Newtonsoft JsonConverter Support

NCache supports external Newtonsoft JsonConverter implementations for JSON serialization and deserialization. This feature allows you to define custom serialization behavior for specific object types when the default JSON serialization behavior is not enough for your application.

A custom JsonConverter is useful when your object model requires special handling during JSON conversion. For example, you may need to control how a specific class is written as JSON or how it is reconstructed when read from JSON.

Newtonsoft JSON serialization provides several configurable settings. In the NCache JSON serialization workflow, external support is available for custom converters. Converters are attached during the contract creation stage for the specific target type. This allows NCache to use Newtonsoft’s contract caching mechanism, so subsequent serialization calls use the cached contract with the converter already attached, instead of scanning the converter list on every serialization call.

Prerequisites

Before configuring external Newtonsoft JsonConverter support, make sure the following requirements are met:

.NET

Install the following NuGet package in your .NET client application:
- Enterprise: Alachisoft.NCache.SDK
Include the following namespaces in your application:
- Alachisoft.NCache.Client;
- Alachisoft.NCache.Runtime.Exceptions;
- Newtonsoft.Json;
The cache must be running.
Make sure that the data being added to the cache is serializable.
Make sure that your custom converter class is accessible to the application at runtime.
Use the fully qualified assembly name of both the target type and the converter class when specifying converter configuration.
For API details, refer to: ICache, CacheItem, Add, and Insert.

Using Custom JsonConverters

A custom converter is a class derived from the Newtonsoft JsonConverter abstract class. Usually, one converter handles one specific data type, or a group of related types that share a common parent class.

The converter defines two main operations:

How an object is read from JSON.
How an object is written as JSON.

The following example shows a custom converter for the Product class:

public class ProductConverter : JsonConverter
{
    public override bool CanConvert(Type objectType)
    {
        return typeof(Product).IsAssignableFrom(objectType);
    }

    public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
    {
        // Add logic for reading JSON.
    }

    public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
    {
        // Add logic for writing JSON.
    }
}

Get Fully Qualified Assembly Names for Types and Converters

To configure a converter, you need the fully qualified assembly name of both the target type and the converter type. You can get these values from the application itself by using the non-instance type reference:

var typeFqn = typeof(Product).AssemblyQualifiedName;
var converterFqn = typeof(ProductConverter).AssemblyQualifiedName;

Here, typeFqn represents the fully qualified assembly name of the target type for which the converter is configured, while converterFqn represents the fully qualified assembly name of the custom converter class.

Make sure this code is run in an application that uses the same target framework and dependencies as the final application that will use these converters.

Configure JsonConverter for Client-Side Features

Add the converter information in the appsettings.json file. The Converters array accepts a list of objects. Each object specifies the fully qualified assembly name of the target type and the fully qualified assembly name of the converter that should be used for that type.

{
  "NCacheSettings": {
    "JsonSerialization": {
      "Converters": [
        {
          "TypeFQN": "TestApplication.Data.Product, TestApplicationFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
          "ConverterFQN": "TestApplication.Converters.ProductConverter, TestApplicationFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
        }
      ]
    }
  }
}

Configure JsonConverters for Server-Side Features

NCache also supports external Newtonsoft JsonConverter implementations for server-side features that require payload serialization like Backing Source Providers, Cache Loader and Refresher. To use custom converters with server-side features, create a JSON file named nc-converters.json and place it in the deploy folder of the required cache. This nc-converters.json file uses the same JSON structure as the one used for configuring converters in a client application. The only difference is the file name.

{
  "NCacheSettings": {
    "JsonSerialization": {
      "Converters": [
        {
          "TypeFQN": "TestApplication.Data.Product, TestApplicationFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
          "ConverterFQN": "TestApplication.Converters.ProductConverter, TestApplicationFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
        }
      ]
    }
  }
}

Additionally, you will have to deploy the assembly that contains the custom converters to the cache and any dependent assemblies.