AustinHarris.JsonRpc.SystemTextJson 2.0.1

AustinHarris.JsonRpc.SystemTextJson

AustinHarris.JsonRpc.SystemTextJson adds System.Text.Json serialization to AustinHarris.JsonRpc 2.0. Choose it when your application already uses JsonSerializerOptions and System.Text.Json converters.

Request parameters arrive as the raw UTF-8 bytes of one JSON value and go straight into JsonSerializer.Deserialize, with no transcoding and no copies. Results are written with a per-thread cached Utf8JsonWriter directly into the response buffer.

Install

dotnet add package AustinHarris.JsonRpc.SystemTextJson

Targets netstandard2.0, netstandard2.1, net8.0 and net10.0; depends on System.Text.Json 10.0.3 and the AustinHarris.JsonRpc core package.

Use

Process-wide default:

using AustinHarris.JsonRpc;
using AustinHarris.JsonRpc.SystemTextJson;

Config.SetSerializer(new SystemTextJsonRpcSerializer());
// or with your own options
Config.SetSerializer(new SystemTextJsonRpcSerializer(options));

Per session:

Config.SetSerializer(sessionId, new SystemTextJsonRpcSerializer(options));

Per call (overrides both the session and the process-wide default):

var serializer = new SystemTextJsonRpcSerializer(options);
string response = JsonRpcProcessor.ProcessSync(sessionId, json, context, serializer);
// the byte-based overloads take the same trailing argument:
JsonRpcProcessor.Process(sessionId, requestBytes, outputWriter, context, serializer);

When each level is the right one is covered in docs/serializers.md.

Create one instance and reuse it. The options it actually uses (EffectiveOptions) are read-only; the object you passed is never changed.

Default options

new SystemTextJsonRpcSerializer() uses SystemTextJsonRpcSerializer.DefaultOptions, a single immutable JsonSerializerOptions that reproduces the wire conventions of the built-in and Json.NET serializers for the envelope, primitives, dates and plain objects. The serializers are still not interchangeable for every request: System.Text.Json refuses some coercions the other two accept (a JSON number sent for a string parameter, for example), the CLR types each supports differ, and so does the object model handed to handlers. Test client-visible requests and responses before switching.

Converters

Registered by JsonRpcConverters.AddMissing(options); each is public so it can be used on its own.

Nullable variants (double?, DateTime?, ...) are covered automatically by System.Text.Json's nullable wrapping. Because these converters replace the built-in numeric ones, JsonNumberHandling.WriteAsString and AllowNamedFloatingPointLiterals are not applied to the primitive numeric types.

Supplying your own options

new SystemTextJsonRpcSerializer(options) honours the options as given (naming policy, encoder, extra converters, TypeInfoResolver, ...). The only adjustment is the converter set:

• If options.Converters already contains every JsonRpcConverters type, the instance is used as-is (it is made read-only, as System.Text.Json would do on first use anyway).
• Otherwise the options are copied with new JsonSerializerOptions(options) and the missing converters are appended to the copy, which is then made read-only. The object you passed is never mutated, so it is safe to share with other code. The converters are appended after yours, so a converter you registered for the same type keeps precedence.

Options returns what you passed (null for the defaults); EffectiveOptions returns the instance actually used. To start from the library defaults and tweak them:

var options = SystemTextJsonRpcSerializer.CreateDefaultOptions();   // a mutable copy of DefaultOptions
options.Converters.Add(new JsonStringEnumConverter());
options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
Config.SetSerializer(new SystemTextJsonRpcSerializer(options));

If you build options from scratch, remember that the wire conventions above (IncludeFields, UnsafeRelaxedJsonEscaping, PropertyNameCaseInsensitive) are then up to you; only the converters are added.

Object model

Pre/post-process handlers receive JsonRequest.Params as a JsonElement (the result of deserializing the params to object), and Handler.Handle(JsonRequest) accepts a JsonElement back.

A client value that cannot be converted to the parameter's type throws JsonException, which the core reports as -32602 Invalid params with data naming the parameter and the expected type; the value sent is never echoed. System.Text.Json is stricter than the other two serializers here: a JSON number sent for a string parameter is refused. An unsupported CLR type or an internal serialization failure remains -32603 Internal error.