Why does NCache fail when caching an object with a Stream or Task?

NCache uses Newtonsoft.Json, which is a data-only format. Streams and Tasks represent live I/O and execution state; since these cannot be converted to static text, the serialization process will fail.

How do I prevent data loss with JSON serialization in NCache?

To prevent data loss with JSON serialization in NCache, ensure that objects are created as Data Transfer Objects (DTOs) containing only primitive types, collections, and simple POCOs. Do not add members representing behavior, memory pointers, or OS-level handles.

JSON Data Types and Properties Overview [Deprecated]

JSON is a human-readable lightweight syntax for sharing data. It is structured and formatted for machines to parse effortlessly and for data exchange to occur conveniently and seamlessly. JSON has the JsonObject (an unordered collection of name/value pairs represented as attributes) as a basic structure.

Additionally, using JSON requires JSON serialization and it is most commonly used for cross-platform, heterogeneous, and document-based data exchange. If you have a complete object, you can use a Newtonsoft.Json Serializer to generate a JSON string and add it as an object (which you can read more about in our Administrators' Guide). Alternatively, NCache provides an API to construct a JSON object. NCache lets you add data that represents JSON into your cache. However, if you are dealing with documents, as we've discussed previously, you can add the documents to the cache directly.

NCache provides the flexibility of retrieve custom class data from your cache as JSON. Moreover, data can be added as JSON data and fetched as a custom class, provided that the attributes represent the properties of the custom class. Data being JSON serialized, when retrieved by the user as JSON, is parsed by NCache and provided to you as either of the following according to your requirement:

JsonObject
JsonNull
JsonArray
JsonValue

These classes are derived from an abstract class called JsonValueBase.

Consider a .NET class Product containing data of products. When added with the JsonObject, the class attributes, e.g., ProductName and ProductID, etc., will be the attributes of the JsonObject. Given below is the data of a .NET class containing the following properties:

Product product = new Product();
product.ProductID = 1001;
product.ProductName = "Chai";
product.Category = "Beverages";

The JSON equivalent of the given data when added as JsonObject will be a string containing all the attributes and is displayed as follows:

{
    "ProductID" : 1001,
    "ProductName" : "Chai",
    "Category" : "Beverages"
}

Moreover, you can provide a string containing JSON data and parse it to get JsonValueBase in return. It will parse this string and identify the data type.

JSON Data Classes in NCache

Let us get a closer look at all these classes provided by NCache.

JsonObject

This class represents JObject in JSON standards in NCache’s domain. Just as a JObject contains name/value pairs (referring to the attribute). This class also contains the string and JsonValueBase key-value pairs. The JsonObject can be added with a CacheItem in the cache. The CacheItem is a class that represents a cached item, including its various properties. The CacheItem can provide JsonObject with many functionalities, such as:

Cache Dependencies (Enterprise only)
Tags (Enterprise only)
NamedTags (Enterprise only)
Groups (Enterprise only)
Expiration

JsonNull

This class represents a null value in JSON standards. It also maps null values in NCache’s domain to null values in JSON standards.

Various operations performed on the cache using the classes mentioned above are explained in the successive chapters.

JSON Serialization Limitations in NCache

When a cache is configured to use JSON serialization, NCache serializes and deserializes objects as JSON (commonly using Newtonsoft.Json in .NET environments). JSON is a data-centric format, therefore any .NET type or programming construct that represents behavior, runtime execution state, or live external resources cannot be reliably cached.

Warning

Caching unsupported members may lead to exceptions during runtime, silent data loss, or creation of "incomplete" objects that contain missing properties without raising any error or warning.

Why JSON Serialization Has Fundamental Limits

JSON is created to represent primitive data types, arrays, and structured key-value objects. It is not designed to represent:

Executable Code: Methods, logical code constructs, or pointers to functions.
Runtime State: Active execution threads or stack-only types.
Live Connections: Open database streams or network handles.

Non-Serializable .NET Constructs

The following table lists common .NET constructs that are not suitable for NCache JSON serialization, along with the reason.

Category	Examples	Failure Reason
I/O Resources	`Stream`, `FileStream`, `MemoryStream`	Represents live I/O, not data
Logic/Code	`Action`, `Func<T>`, `EventHandler`	Executable code cannot be stringified
Threading	`Thread`, `Task`, `CancellationToken`	Cannot be reconstructed meaningfully
Database	`DbConnection`, `DbCommand`, `DataReader`	Live external connections
Reflection	`Type`, `MethodInfo`, `Assembly`	Runtime metadata, not static data
Memory Types	`Span<T>`, `ReadOnlySpan<T>`, `ref struct`	Stack-only types
OS Handles	`FileInfo`, `DirectoryInfo`	Paths/metadata may serialize but are not reliably valid on restore

Sample Serializable vs. Non-Serializable Class

To ensure your objects are ready to be cached, create them as Data Transfer Objects (DTOs). Below is a comparison within a single class:

public class ComplexCacheObject
{
    // SERIALIZABLE (DTOs)
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedOn { get; set; }
    public List<string> Tags { get; set; }
    public Guid CorrelationId { get; set; }


    // NON-SERIALIZABLE (Behavior & Resources)
    // These should be ignored or removed before caching

    // Live I/O
    public Stream DataStream { get; set; } 

    // Executable code        
    public Func<int, int> Logic { get; set; }    

   // Live resource
    public DbConnection Connection { get; set; }   

    // Execution state
    public Task RunningTask { get; set; }          
}

Best Practices for NCache Serialization

The following are best practices to observe while serializing objects with JSON in NCache:

Design for Data: Cacheable objects should contain pure data only. Detach any runtime behavior or external handles before insertion.

Checklist Before Caching: Before caching objects please ensure that the following checks have been made:

Object does not contain any unmanaged resources.
No delegates, events, or threading primitives are present.
Ensure required properties are initialized (avoid nulls where your code expects values).
Serialization behavior has been tested with Newtonsoft.Json independently.

Avoid Silent Errors: Do not assume a successful Insert operation means all members were serialized. Use logging to verify complex object states upon retrieval.