Maintain compatibility with existing Newtonsoft.Json code

We recommend using System.Text.Json to serialize and deserialize JSON. It is the library used and configured by the Neos framework.

If existing business code uses Newtonsoft.Json, you can continue to use it. However, Newtonsoft.Json is no longer provided or configured by Neos.

The business assembly must reference the package explicitly.

Serialize and deserialize localizable strings

Neos configures System.Text.Json to serialize and deserialize LocalizableString values.

To make Newtonsoft.Json serialization and deserialization of LocalizableString values behave like System.Text.Json, use the following custom converter:

using System;
using System.Collections.Generic;
using GroupeIsa.Neos.Shared.Localization;
using Newtonsoft.Json;

public class LocalizableStringNewtonsoftJsonConverter : JsonConverter<LocalizableString>
{
    /// <inheritdoc/>
    public override LocalizableString? ReadJson(
        JsonReader reader,
        Type objectType,
        LocalizableString? existingValue,
        bool hasExistingValue,
        JsonSerializer serializer)
    {
        if (reader.TokenType == JsonToken.Null)
        {
            return null;
        }

        if (reader.TokenType != JsonToken.StartObject)
        {
            throw new JsonException("The JSON value is not a valid LocalizableString.");
        }

        Dictionary<string, string> values = [];
        string key = string.Empty;
        while (reader.Read())
        {
            switch (reader.TokenType)
            {
                case JsonToken.Null:
                    throw new JsonException("The JSON value is not a valid LocalizableString.");

                case JsonToken.PropertyName:
                    key = reader.Value!.ToString()!;
                    break;

                case JsonToken.String:
                    values.Add(key, reader.Value!.ToString()!);
                    break;

                case JsonToken.EndObject:
                    return new LocalizableString(values);
            }
        }

        throw new JsonException("The JSON value is not a valid LocalizableString.");
    }

    /// <inheritdoc/>
    public override void WriteJson(
        JsonWriter writer,
        LocalizableString? value,
        JsonSerializer serializer)
    {
        if (value == null)
        {
            writer.WriteNull();
            return;
        }

        writer.WriteStartObject();
        foreach (KeyValuePair<string, string> kvp in value.AsEnumerable())
        {
            writer.WritePropertyName(kvp.Key);
            writer.WriteValue(kvp.Value);
        }

        writer.WriteEndObject();
    }
}

Pass the converter when serializing:

JsonConverter[] converters = [new LocalizableStringNewtonsoftJsonConverter()];
string json = JsonConvert.SerializeObject(myObject, converters);

Pass the same converter when deserializing:

JsonConverter[] converters = [new LocalizableStringNewtonsoftJsonConverter()];
MyObject? myObject = JsonConvert.DeserializeObject<MyObject>(json, converters);

Handle untyped server method parameters

A server method parameter declared as object is received as a JsonElement. Business code that still needs a Newtonsoft.Json.Linq.JObject can convert the value explicitly:

using System.Text.Json;
using Newtonsoft.Json.Linq;

JsonElement value = (JsonElement)parameter;
JObject jsonObject = JObject.Parse(value.GetRawText());

Prefer using a typed server method parameter when the payload structure is known. This avoids coupling business logic to either JSON object model.