NReJSON

Overview

NReJSON is a series of extension methods for the StackExchange.Redis library that will enable you to interact with the Redis module RedisJSON. This is made possible by the Execute and ExecuteAsync methods already present in the SE.Redis library.

The following blog post by Marc Gravell was the inspiration behind this: StackExchange.Redis and Redis 4.0 Modules. He even has an example of how to call a command from the RedisJSON module!

Installation

PM> Install-Package NReJSON -Version 4.0.0

Usage

I'm assuming that you already have the RedisJSON module installed on your Redis server.

You can verify that the module is installed by executing the following command:

MODULE LIST

If RedisJSON is installed you should see output similar to the following:

1) 1) "name"
   2) "ReJSON"
   3) "ver"
   4) (integer) 10001

(The version of the module installed on your server obviously may vary.)

Major Changes in Version 4.0

• Requires RedisJson 2.0.

• All deprecated RedisJson commands have been removed.

• Introduced PathedResult<TResult> in order to handle commands which can return multiple results in the format of a JSON array based on a provided JSONPath specification.

• BREAKING CHANGE : The generic overloads for JsonGet and JsonGetAsync now return an instance of PathedResult<TResult>.

• BREAKING CHANGE : JsonIncrementNumber and JsonIncrementNumberAsync now return an instance of PathedResult<double?>.

• BREAKING CHANGE : JsonMultiplyNumber and JsonMultiplyNumberAsync now return an instance of PathedResult<double?>.

• BREAKING CHANGE : JsonAppendJsonString and JsonAppendJsonStringAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonStringLength and JsonStringLengthAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayAppend and JsonArrayAppendAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayIndexOf and JsonArrayIndexOfAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayInsert and JsonArrayInsertAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayLength and JsonArrayLengthAsync now return int?[] to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayPop and JsonArrayPopAsync now return string?[] or TResult[] for the generic overloads to support multiple JSONPath matches.

• BREAKING CHANGE : JsonArrayTrim and JsonArrayTrimAsync now return int?[] to support multiple JSONPath matches.

• Removed ability to associate a JSON object with an index using the JsonSet and JsonSetAsync methods.

• Changed param array in JsonArrayAppend and JsonArrayAppendAsync to be an array of type object.

• Changed jsonScalar parameter in JsonArrayIndexOf and JsonArrayIndexOfAsync to be of type object.

• Changed param array in JsonArrayInsert and JsonArrayInsertAsync to be an array of type object.

Major Changes in Version 3.0

In version 3.0 support for serialization and deserialization was added in the form of new generic overloads for the following extension methods:

• JsonGet/JsonGetAsync
• JsonMultiGet/JsonMultiGetAsync
• JsonSet/JsonSetAsync
• JsonArrayPop/JsonArrayPopAsync
• JsonIndexGet/JsonIndexGetAsync

In order to leverage the serialization/deserialization support you must create an implementation of the ISerializerProxy interface. The following is a sample implementation taken from the integration tests:

public sealed class TestJsonSerializer : ISerializerProxy
{
    public TResult Deserialize<TResult>(RedisResult serializedValue) =>
        JsonSerializer.Deserialize<TResult>(serializedValue.ToString());

    public string Serialize<TObjectType>(TObjectType obj) =>
        JsonSerializer.Serialize(obj);
}

Once that is implemented it can be assigned to the static property SerializerProxy found in the static class NReJSONSerializer. The following is an example of how to do this:

NReJSONSerializer.SerializerProxy = new TestJsonSerializer();

If this isn't setup before leveraging the extension methods that make use of it, an NReJSONException will be thrown in order to remind you that it needs to be done.

The result type for the following methods has change to OperationResult:

• JsonSet/JsonSetAsync
• JsonIndexAdd/JsonIndexAddAsync
• JsonIndexDelete/JsonIndexDeleteAsync

The OperationResult is a struct that will return and contain whether or not the operation was successful, and will also contain the raw response from Redis. This type is implicitly convertable to bool so it can be used in operations like:

var result = await db.JsonSetAsync(key, obj);

if (result)
{
   // Do something if there was success...
} 
else
{
   // Do something if there wasn't success...
}

Last but not least, we have a new result type called IndexedCollection which is now returned by the overload which deserializes results on the following method:

• JsonIndexGet/JsonIndexGetAsync

This type is generic and allows for dealing with the result of the JsonIndexGet and JsonIndexGetAsync as a dictionary and as a collection.

Examples

Sam Dzirasa has authored a blog post full of practical examples of how to use NReJSON in an application:

Using RedisJson

Also, in this repository there are a suite of integration tests that should be sufficent to serve as examples on how to use all supported RedisJSON commands.

Integration Tests