Nexus and JSON

Nexus uses System.Text.Json by default to serialize persisted messages, job parameters, function arguments, instance events, and other state. Applications using Newtonsoft.Json converters can install CommerceMind.Nexus.NewtonsoftJson and call AddNexus().AddNewtonsoftJson() instead. Choose the serializer deliberately and check existing persisted data before switching.

Customizing serialization

Nexus serialization is controlled by its serialization interfaces and options. ASP.NET Core controls the outer HTTP API models, while Nexus controls the queue-message JSON inside them. For example, the outer model can use camelCase while the message retains PascalCase:

{
  "id": 4823771,
  "status": "Processed",
  "retryCount": 0,
  "message": {
    "Id": null,
    "SomeProperty": null,
    "ExampleEnum": "Value1"
  }
}

Configure Nexus's System.Text.Json converters through:

builder.Services.AddNexus().ConfigureJsonOptions(options =>
{
    options.SerializerOptions.Converters.Add(new MyCustomConverter());
});

Specialized interfaces such as IQueueMessageSerializer, IJobParametersSerializer, and INexusFunctionArgumentsSerializer can be replaced when different formats are required. Operational serializers are scoped and may use scoped application dependencies; see dependency injection.

Interfaces, abstract types, and type hashes

When polymorphic data needs a concrete .NET type at deserialization time, Nexus can write $type metadata and a $typehash. This is not required on every ordinary queue message; the queue's known message contract normally supplies its type.

In v3, JsonOptions.WriteTypeHash and RequireTypeHash both default to true. When the System.Text.Json polymorphic converter reads explicit type metadata, it requires a matching hash. Custom writers must place $typehash before $type, and both before ordinary properties. Use the Nexus serializer to produce this metadata rather than constructing it manually.

Keep the same TypeHashSalt on every host reading the same data. Changing it invalidates existing hashes. If a salt change is necessary, use a compatible ISerializationTypeHashCalculator during the transition so old and new data can both be read.

ISerializationBinder controls the mapping between .NET types and their serialized names. ISerializationTypeHashCalculator calculates hashes for those names. Preserve these mappings when renaming application types used in persisted data.

Older JSON without hashes

Default v2 System.Text.Json writers already included hashes. Older or customized JSON may have $type without $typehash, particularly data from v1 or Newtonsoft-compatible writers. Process or migrate that data before enabling the v3 requirement, or temporarily configure:

builder.Services.AddNexus().ConfigureJsonOptions(options =>
{
    options.RequireTypeHash = false;
    // Leave WriteTypeHash enabled so new System.Text.Json data has hashes.
});

This relaxes validation for the STJ polymorphic converter; it is not a fix for unreadable renamed types or a serializer switch. Enable RequireTypeHash again after the old data has been removed or migrated. Do not disable hash writing while requiring it on reads, as that can make newly written polymorphic data unreadable.