Migrating from System.Text.Json to Json.NET: Step-by-Step

Building Fast and Reliable APIs with Json.NET

Summary

Use Json.NET (Newtonsoft.Json) to efficiently handle JSON serialization/deserialization in .NET APIs, focusing on performance, reliability, and maintainability.

Key practices

• Choose correct serializer settings: set NullValueHandling, DefaultValueHandling, and Formatting to reduce payload size.
• Use JsonConverter for custom types: implement JsonConverter for nonstandard types (e.g., polymorphic objects, custom date formats) to control parsing and reduce errors.
• Avoid reflection-heavy patterns at runtime: prefer attributes ([JsonProperty], [JsonConverter]) and compile-time contracts to reduce overhead.
• Use TypeNameHandling carefully: only enable when necessary and validate incoming payloads to avoid security risks.
• Buffering and streaming: use JsonTextReader/JsonTextWriter for large payloads to stream rather than fully materialize objects in memory.
• Asynchronous IO: combine async reads/writes (StreamReader/StreamWriter with async) with Json.NET to keep threads free under load.
• Configure maximum depth: set MaxDepth to prevent stack/DoS attacks from deeply nested JSON.
• Cache contracts and converters: reuse JsonSerializer instances with preconfigured settings to avoid repeated allocations.
• Validation and schema: validate incoming JSON (manually or with JSON Schema libraries) and return clear error responses.
• Testing and benchmarks: include unit tests for serialization behavior and benchmark common payloads to identify bottlenecks.

Example patterns (conceptual)

• Reuse a single JsonSerializerSettings and JsonSerializer across requests.
• Stream large uploads:
  • Read with JsonTextReader over request stream and process tokens incrementally.
• Custom converter for polymorphic message types to avoid expensive reflection on each request.

Common pitfalls

• Enabling TypeNameHandling without validation (remote code execution risk).
• Creating a new JsonSerializerSettings per request (performance and memory overhead).
• Fully deserializing very large payloads into memory (OOM risk).
• Not constraining MaxDepth or missing input validation (DoS/vector).

Quick checklist before deployment

1. Reuse configured serializer instances.
2. Stream large payloads; use async IO.
3. Set MaxDepth and size limits.
4. Limit or validate TypeNameHandling usage.
5. Add serialization unit tests and benchmarks.

If you want, I can produce code examples for any pattern above (reused serializer, streaming reader, custom JsonConverter).