{"id":2245,"date":"2025-04-30T18:08:51","date_gmt":"2025-04-30T18:08:51","guid":{"rendered":"https:\/\/www.w3computing.com\/articles\/?p=2245"},"modified":"2025-04-30T18:08:55","modified_gmt":"2025-04-30T18:08:55","slug":"building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader","status":"publish","type":"post","link":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/","title":{"rendered":"Building Custom JSON Serialization Logic Using Utf8JsonWriter and Utf8JsonReader"},"content":{"rendered":"\n

1. Introduction to JSON Serialization in .NET<\/h2>\n\n\n\n

JSON has become the lingua franca of modern software systems. Whether you’re building APIs, consuming web services, or storing configuration data, chances are you’re dealing with JSON. In the .NET ecosystem, handling JSON has become increasingly streamlined\u2014thanks to the evolution of System.Text.Json<\/code>, which provides a high-performance, low-allocation alternative to older libraries like Newtonsoft.Json.<\/p>\n\n\n\n

At a glance, serialization (converting an object into JSON) and deserialization (converting JSON back into an object) seem straightforward. For many standard use cases, using JsonSerializer.Serialize()<\/code> and JsonSerializer.Deserialize<T>()<\/code> will get the job done with minimal effort. But real-world applications often introduce complexity: custom data formats, performance constraints, conditional fields, or models that don\u2019t match the exact JSON schema you’re working with.<\/p>\n\n\n\n

That\u2019s where lower-level tools like Utf8JsonWriter<\/code> and Utf8JsonReader<\/code> come in. They give you precise control over the serialization process\u2014letting you manually write and read JSON tokens in a highly optimized way. Instead of relying on reflection and automatic mapping, you define exactly how data flows to and from JSON, one token at a time.<\/p>\n\n\n\n

This tutorial is for developers who are ready to go beyond the default serializer and need fine-tuned control over their JSON logic. Whether you’re building a high-throughput system, interfacing with third-party APIs with non-standard formats, or just want to squeeze every drop of performance out of your app, understanding Utf8JsonWriter<\/code> and Utf8JsonReader<\/code> can be a game-changer.<\/p>\n\n\n\n

In the sections that follow, we\u2019ll break down how to use these tools from the ground up, starting with how to write basic JSON manually, and moving toward full custom serialization and deserialization logic for complex .NET objects.<\/p>\n\n\n\n

2. Overview of Utf8JsonWriter and Utf8JsonReader (\u2248250 words)<\/h2>\n\n\n\n

When working with JSON in .NET, the System.Text.Json<\/code> namespace gives you more than just high-level serialization methods\u2014it also includes two powerful low-level APIs: Utf8JsonWriter<\/code> and Utf8JsonReader<\/code>. These are designed for developers who need full control over JSON input and output, especially in performance-critical or non-standard scenarios.<\/p>\n\n\n\n

Utf8JsonWriter<\/h3>\n\n\n\n

Utf8JsonWriter<\/code> is a forward-only, high-performance writer that emits JSON directly to a Stream<\/code> or IBufferWriter<byte><\/code>. It writes UTF-8 encoded text, which makes it particularly efficient for web applications and microservices where every millisecond and byte counts. You use it by explicitly writing each JSON token\u2014start object, property name, value, array start, and so on. This approach avoids reflection, unnecessary allocations, and the overhead of generic serialization.<\/p>\n\n\n\n

Utf8JsonReader<\/h3>\n\n\n\n

On the flip side, Utf8JsonReader<\/code> is a forward-only reader that parses UTF-8 JSON data into a stream of tokens. Instead of deserializing an entire object automatically, you manually navigate through the tokens and extract values as needed. This gives you unmatched flexibility\u2014for example, you can skip irrelevant fields, handle unexpected data gracefully, or map flat JSON into deeply nested models.<\/p>\n\n\n\n

These two classes are intentionally low-level and minimal by design. They don\u2019t manage state for you, nor do they build object graphs. But that\u2019s exactly what makes them so powerful\u2014they give you raw access to the data and trust you to manage the logic.<\/p>\n\n\n\n

3. Setting Up the Development Environment (\u2248150 words)<\/h2>\n\n\n\n

Before diving into code, let\u2019s set up a clean development environment to experiment with Utf8JsonWriter<\/code> and Utf8JsonReader<\/code>.<\/p>\n\n\n\n

Prerequisites<\/h3>\n\n\n\n

Make sure you have the following installed:<\/p>\n\n\n\n

    \n
  • .NET 6.0 or later<\/strong> \u2013 These APIs are available in System.Text.Json<\/code>, which ships with .NET Core 3.0 and above, but .NET 6+ is recommended for improved performance and features.<\/li>\n\n\n\n
  • Visual Studio 2022<\/strong>, Rider<\/strong>, or VS Code<\/strong> \u2013 Any modern IDE that supports C# will work.<\/li>\n<\/ul>\n\n\n\n

    Creating the Project<\/h3>\n\n\n\n

    Open your terminal or IDE and create a new console application:<\/p>\n\n\n

    dotnet new<\/span> console<\/span> -n JsonSerializationDemo\ncd JsonSerializationDemo\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    No additional NuGet packages are required since System.Text.Json<\/code> is part of the base class library.<\/p>\n\n\n\n
    Optional Setup<\/h3>\n\n\n\n
    To make testing easier, you can add the following NuGet package for debugging output:<\/p>\n\n\n
    dotnet<\/span> add<\/span> package<\/span> Microsoft<\/span>.Extensions<\/span>.Logging<\/span>.Console<\/span>\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    This setup gives you a clean slate to focus on hands-on examples. Next, we’ll get into the basics of writing JSON manually using Utf8JsonWriter<\/code>.<\/p>\n\n\n\n
    4. Understanding Utf8JsonWriter<\/h2>\n\n\n\n
    At first glance, manually writing JSON might sound tedious\u2014but Utf8JsonWriter<\/code> makes it surprisingly straightforward. It\u2019s a low-level, high-performance API that lets you build JSON directly, token by token, with full control over structure, formatting, and data types.<\/p>\n\n\n\n
    How It Works<\/h3>\n\n\n\n
    Utf8JsonWriter<\/code> writes JSON to an IBufferWriter<byte><\/code>, commonly backed by a MemoryStream<\/code>. It\u2019s forward-only and writes raw UTF-8 encoded bytes, which keeps it fast and efficient. You don\u2019t deal with strings unless you want to, and there\u2019s no reflection overhead.<\/p>\n\n\n\n
    Basic Setup<\/h3>\n\n\n\n
    Here\u2019s a minimal example of using Utf8JsonWriter<\/code> to serialize a simple object:<\/p>\n\n\n
    using System;\nusing System.IO;\nusing System.Text.Json;\n\nvar<\/span> stream = new<\/span> MemoryStream();\nvar<\/span> writer = new<\/span> Utf8JsonWriter(stream, new<\/span> JsonWriterOptions { Indented = true<\/span> });\n\nwriter.WriteStartObject();\nwriter.WriteString(\"name\"<\/span>, \"Alice\"<\/span>);\nwriter.WriteNumber(\"age\"<\/span>, 30<\/span>);\nwriter.WriteBoolean(\"isActive\"<\/span>, true<\/span>);\nwriter.WriteEndObject();\nwriter.Flush();\n\nstring json = System.Text.Encoding.UTF8.GetString(stream.ToArray());\nConsole.WriteLine(json);\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Output:<\/strong><\/p>\n\n\n
    {\n  \"name\"<\/span>: \"Alice\"<\/span>,\n  \"age\"<\/span>: 30<\/span>,\n  \"isActive\"<\/span>: true<\/span>\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
    This example shows how each field is explicitly written using a method tailored to its type.<\/p>\n\n\n\n
    Writing Arrays<\/h3>\n\n\n\n
    You can also write arrays easily:<\/p>\n\n\n
    writer<\/span>.WriteStartArray<\/span>(\"tags<\/span>\");\nwriter<\/span>.WriteStringValue<\/span>(\"developer<\/span>\");\nwriter<\/span>.WriteStringValue<\/span>(\"blogger<\/span>\");\nwriter<\/span>.WriteEndArray<\/span>();\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
    This would result in:<\/p>\n\n\n
    \"tags\"<\/span>: [\"developer\"<\/span>, \"blogger\"<\/span>]\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Nesting Objects<\/h3>\n\n\n\n
    Nested structures are handled by chaining calls:<\/p>\n\n\n
    writer.WriteStartObject(\"address\"<\/span>);\nwriter.WriteString(\"city\"<\/span>, \"Seattle\"<\/span>);\nwriter.WriteString(\"zip\"<\/span>, \"98101\"<\/span>);\nwriter.WriteEndObject();\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Which produces:<\/p>\n\n\n
    \"address\"<\/span>: {\n  \"city\"<\/span>: \"Seattle\"<\/span>,\n  \"zip\"<\/span>: \"98101\"<\/span>\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Key Takeaways<\/h3>\n\n\n\n
      \n
    • Use the correct WriteX<\/code> methods based on data type.<\/li>\n\n\n\n
    • Always match WriteStartObject<\/code> with WriteEndObject<\/code>, and WriteStartArray<\/code> with WriteEndArray<\/code>.<\/li>\n\n\n\n
    • Call Flush()<\/code> to ensure all data is written to the output stream.<\/li>\n<\/ul>\n\n\n\n
      5. Understanding Utf8JsonReader<\/h2>\n\n\n\n
      Just as Utf8JsonWriter<\/code> gives you precise control over writing JSON, Utf8JsonReader<\/code> offers a fast and memory-efficient way to read and parse JSON. It\u2019s a forward-only, read-only parser that processes UTF-8 encoded text as a stream of tokens. This design makes it ideal for high-performance scenarios where allocating full object graphs isn\u2019t necessary\u2014or even possible.<\/p>\n\n\n\n
      How It Works<\/h3>\n\n\n\n
      Utf8JsonReader<\/code> reads a ReadOnlySpan<byte><\/code> or ReadOnlySequence<byte><\/code> containing JSON text. It doesn’t create objects or deserialize types for you\u2014instead, it exposes a sequence of tokens (e.g., StartObject<\/code>, PropertyName<\/code>, String<\/code>, EndObject<\/code>) that you can read and act on manually.<\/p>\n\n\n\n
      Basic Usage Example<\/h3>\n\n\n\n
      Let\u2019s say we want to read the following JSON:<\/p>\n\n\n
      {\n  \"name\"<\/span>: \"Alice\"<\/span>,\n  \"age\"<\/span>: 30<\/span>,\n  \"isActive\"<\/span>: true<\/span>\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
      Here\u2019s how we could parse it:<\/p>\n\n\n
      using System;\nusing System.Text;\nusing System.Text.Json;\n\nvar<\/span> json = \"{\\\"name\\\":\\\"Alice\\\",\\\"age\\\":30,\\\"isActive\\\":true}\"<\/span>;\nvar<\/span> jsonBytes = Encoding.UTF8.GetBytes(json);\n\nvar<\/span> reader = new<\/span> Utf8JsonReader(jsonBytes);\n\nwhile<\/span> (reader.Read())\n{\n    if<\/span> (reader.TokenType == JsonTokenType.PropertyName)\n    {\n        string propertyName = reader.GetString();\n        reader.Read(); \/\/ Move to the value<\/span>\n\n        switch<\/span> (propertyName)\n        {\n            case<\/span> \"name\"<\/span>:\n                string name = reader.GetString();\n                Console.WriteLine($\"Name: {name}\"<\/span>);\n                break<\/span>;\n            case<\/span> \"age\"<\/span>:\n                int age = reader.GetInt32();\n                Console.WriteLine($\"Age: {age}\"<\/span>);\n                break<\/span>;\n            case<\/span> \"isActive\"<\/span>:\n                bool isActive = reader.GetBoolean();\n                Console.WriteLine($\"Active: {isActive}\"<\/span>);\n                break<\/span>;\n        }\n    }\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
      Token Types<\/h3>\n\n\n\n
      Utf8JsonReader<\/code> exposes many token types:<\/p>\n\n\n\n
        \n
      • StartObject<\/code>, EndObject<\/code><\/li>\n\n\n\n
      • StartArray<\/code>, EndArray<\/code><\/li>\n\n\n\n
      • PropertyName<\/code><\/li>\n\n\n\n
      • String<\/code>, Number<\/code>, Boolean<\/code>, Null<\/code><\/li>\n<\/ul>\n\n\n\n
        You must carefully manage state as you read\u2014there\u2019s no “back” button. Think of it like a JSON cursor that always moves forward.<\/p>\n\n\n\n
        Advantages<\/h3>\n\n\n\n
          \n
        • Minimal allocations<\/li>\n\n\n\n
        • Fast, especially for large payloads<\/li>\n\n\n\n
        • Full control over structure and validation<\/li>\n<\/ul>\n\n\n\n
          6. Implementing Custom Serialization Logic<\/h2>\n\n\n\n
          Now that you\u2019ve got a handle on Utf8JsonWriter<\/code>, it\u2019s time to go beyond basic examples and look at how to serialize more complex objects manually. Custom serialization is particularly useful when you need to:<\/p>\n\n\n\n
            \n
          • Rename or omit certain fields<\/li>\n\n\n\n
          • Reorder properties for readability or compatibility<\/li>\n\n\n\n
          • Handle polymorphic data<\/li>\n\n\n\n
          • Serialize non-standard types (like DateTimeOffset<\/code>, enums as strings, etc.)<\/li>\n<\/ul>\n\n\n\n
            Let\u2019s walk through a real-world scenario.<\/p>\n\n\n\n
            Example Model<\/h3>\n\n\n\n
            Suppose we have a class like this:<\/p>\n\n\n
            public class<\/span> Product<\/span>\n<\/span>{\n    public int Id { get<\/span>; set<\/span>; }\n    public string Name { get<\/span>; set<\/span>; }\n    public decimal Price { get<\/span>; set<\/span>; }\n    public string? Description { get<\/span>; set<\/span>; }\n    public List<string> Tags { get<\/span>; set<\/span>; } = new();\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
            Custom Serialization Function<\/h3>\n\n\n\n
            Here\u2019s how you could write a method to serialize this manually using Utf8JsonWriter<\/code>:<\/p>\n\n\n
            public<\/span> static<\/span> void WriteProduct(Utf8JsonWriter writer, Product product)\n{\n    writer.WriteStartObject();\n\n    writer.WriteNumber(\"id\"<\/span>, product.Id);\n    writer.WriteString(\"name\"<\/span>, product.Name);\n    writer.WriteNumber(\"price\"<\/span>, product.Price);\n\n    if<\/span> (!string.IsNullOrWhiteSpace(product.Description))\n    {\n        writer.WriteString(\"description\"<\/span>, product.Description);\n    }\n\n    writer.WriteStartArray(\"tags\"<\/span>);\n    foreach<\/span> (var<\/span> tag in product.Tags)\n    {\n        writer.WriteStringValue(tag);\n    }\n    writer.WriteEndArray();\n\n    writer.WriteEndObject();\n}\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
            Customizing Output<\/h3>\n\n\n\n
            With manual control, you can choose:<\/p>\n\n\n\n
              \n
            • To omit null or empty properties (Description<\/code> in this case)<\/li>\n\n\n\n
            • To write arrays even when they\u2019re empty, or skip them entirely<\/li>\n\n\n\n
            • To include metadata like timestamps or version fields dynamically<\/li>\n<\/ul>\n\n\n\n
              Want to serialize enums as strings instead of numbers? Easy:<\/p>\n\n\n
              writer<\/span>.WriteString<\/span>(\"status<\/span>\", product<\/span>.Status<\/span>.ToString<\/span>());\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
              You can even nest objects:<\/p>\n\n\n
              writer<\/span>.WriteStartObject<\/span>(\"manufacturer<\/span>\");\nwriter<\/span>.WriteString<\/span>(\"name<\/span>\", product<\/span>.Manufacturer<\/span>.Name<\/span>);\nwriter<\/span>.WriteString<\/span>(\"country<\/span>\", product<\/span>.Manufacturer<\/span>.Country<\/span>);\nwriter<\/span>.WriteEndObject<\/span>();\n<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
              Formatting Tips<\/h3>\n\n\n\n
              You can optionally configure the writer for indentation if you want human-readable output:<\/p>\n\n\n
              var<\/span> options = new<\/span> JsonWriterOptions\n{\n    Indented = true<\/span>\n};\nvar<\/span> writer = new<\/span> Utf8JsonWriter(stream, options);\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
              Why This Matters<\/h3>\n\n\n\n
              Manual serialization allows you to meet third-party API contracts that don’t align with your model, reduce payload size by excluding default or redundant values, and ensure your output is exactly what your system or client expects.<\/p>\n\n\n\n
              7. Implementing Custom Deserialization Logic<\/h2>\n\n\n\n
              While writing JSON manually gives you control over output, custom deserialization is where things really get interesting\u2014and occasionally tricky. With Utf8JsonReader<\/code>, you handle incoming JSON token by token, building objects from the ground up. This is powerful when dealing with irregular schemas, partial updates, or performance-critical workloads where object instantiation needs to be lean and precise.<\/p>\n\n\n\n
              Let\u2019s look at how to deserialize the Product<\/code> class we used earlier.<\/p>\n\n\n\n
              Sample JSON<\/h3>\n\n\n
              {\n  \"id\"<\/span>: 101<\/span>,\n  \"name\"<\/span>: \"Laptop\"<\/span>,\n  \"price\"<\/span>: 1299.99<\/span>,\n  \"description\"<\/span>: \"A high-end ultrabook\"<\/span>,\n  \"tags\"<\/span>: [\"electronics\"<\/span>, \"portable\"<\/span>]\n}\n<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
              Custom Deserialization Method<\/h3>\n\n\n
              public<\/span> static<\/span> Product ReadProduct(ref Utf8JsonReader reader)\n{\n    var<\/span> product = new<\/span> Product();\n\n    if<\/span> (reader.TokenType != JsonTokenType.StartObject)\n        throw<\/span> new<\/span> JsonException(\"Expected StartObject token\"<\/span>);\n\n    while<\/span> (reader.Read())\n    {\n        if<\/span> (reader.TokenType == JsonTokenType.EndObject)\n            return<\/span> product;\n\n        if<\/span> (reader.TokenType == JsonTokenType.PropertyName)\n        {\n            string propertyName = reader.GetString();\n            reader.Read(); \/\/ Move to value<\/span>\n\n            switch<\/span> (propertyName)\n            {\n                case<\/span> \"id\"<\/span>:\n                    product.Id = reader.GetInt32();\n                    break<\/span>;\n                case<\/span> \"name\"<\/span>:\n                    product.Name = reader.GetString() ?? \"\"<\/span>;\n                    break<\/span>;\n                case<\/span> \"price\"<\/span>:\n                    product.Price = reader.GetDecimal();\n                    break<\/span>;\n                case<\/span> \"description\"<\/span>:\n                    product.Description = reader.TokenType == JsonTokenType.Null<\/span> ? null<\/span> : reader.GetString();\n                    break<\/span>;\n                case<\/span> \"tags\"<\/span>:\n                    if<\/span> (reader.TokenType == JsonTokenType.StartArray)\n                    {\n                        while<\/span> (reader.Read() && reader.TokenType != JsonTokenType.EndArray)\n                        {\n                            product.Tags.Add(reader.GetString() ?? \"\"<\/span>);\n                        }\n                    }\n                    break<\/span>;\n                default<\/span>:\n                    reader.Skip(); \/\/ Safely ignore unknown fields<\/span>\n                    break<\/span>;\n            }\n        }\n    }\n\n    throw<\/span> new<\/span> JsonException(\"Incomplete JSON object\"<\/span>);\n}\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
              Key Concepts<\/h3>\n\n\n\n
                \n
              • Ref Parameter<\/strong>: The reader must be passed by reference (ref Utf8JsonReader<\/code>) because it\u2019s a struct.<\/li>\n\n\n\n
              • Validation<\/strong>: You\u2019re responsible for checking token types to ensure the JSON structure is valid.<\/li>\n\n\n\n
              • Fallbacks<\/strong>: If a value is missing or null, provide sensible defaults.<\/li>\n\n\n\n
              • Skipping Unknowns<\/strong>: Use reader.Skip()<\/code> to move past unexpected properties gracefully.<\/li>\n<\/ul>\n\n\n\n
                Benefits of Custom Deserialization<\/h3>\n\n\n\n
                  \n
                • You can handle flexible or evolving JSON formats without breaking<\/li>\n\n\n\n
                • You can selectively read only relevant fields, reducing overhead<\/li>\n\n\n\n
                • You can layer validation or transformation into the parsing logic<\/li>\n<\/ul>\n\n\n\n
                  This is especially useful when consuming third-party APIs where field names may differ, optional properties may appear inconsistently, or nested structures require conditional logic.<\/p>\n\n\n\n
                  8. Putting It All Together: Full Serialization\/Deserialization Example<\/h2>\n\n\n\n
                  Now that you\u2019ve learned how to manually write and read JSON using Utf8JsonWriter<\/code> and Utf8JsonReader<\/code>, let\u2019s walk through a complete example to reinforce everything.<\/p>\n\n\n\n
                  We\u2019ll use the Product<\/code> class again, perform both serialization and deserialization, and show how the two processes work seamlessly together.<\/p>\n\n\n\n
                  Full Round-Trip Example<\/h3>\n\n\n
                  using System;\nusing System.IO;\nusing System.Text;\nusing System.Text.Json;\nusing System.Collections.Generic;\n\n\/\/ Product class defined earlier...<\/span>\n\n\/\/ Serialize<\/span>\nvar<\/span> product = new<\/span> Product\n{\n    Id = 42<\/span>,\n    Name = \"Mechanical Keyboard\"<\/span>,\n    Price = 109.95<\/span>m,\n    Description = \"RGB backlit with hot-swappable switches\"<\/span>,\n    Tags = new<\/span> List<\/span><string> { \"electronics\"<\/span>, \"input-device\"<\/span> }\n};\n\nusing var<\/span> stream = new<\/span> MemoryStream();\nvar<\/span> writer = new<\/span> Utf8JsonWriter(stream, new<\/span> JsonWriterOptions { Indented = true<\/span> });\nWriteProduct(writer, product);\nwriter.Flush();\n\nstring json = Encoding.UTF8.GetString(stream.ToArray());\nConsole.WriteLine(\"Serialized JSON:\"<\/span>);\nConsole.WriteLine(json);\n\n\/\/ Deserialize<\/span>\nvar<\/span> jsonBytes = Encoding.UTF8.GetBytes(json);\nvar<\/span> reader = new<\/span> Utf8JsonReader(jsonBytes);\nProduct parsedProduct = ReadProduct(ref reader);\n\nConsole.WriteLine(\"\\nDeserialized Product:\"<\/span>);\nConsole.WriteLine($\"ID: {parsedProduct.Id}\"<\/span>);\nConsole.WriteLine($\"Name: {parsedProduct.Name}\"<\/span>);\nConsole.WriteLine($\"Price: {parsedProduct.Price:C}\"<\/span>);\nConsole.WriteLine($\"Tags: {string.Join(\"<\/span>, \", parsedProduct.Tags)}\"<\/span>);\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
                  Why This Matters<\/h3>\n\n\n\n
                  This round-trip shows how you can:<\/p>\n\n\n\n
                    \n
                  • Fully control what gets serialized and how it\u2019s formatted<\/li>\n\n\n\n
                  • Build an object safely and predictably from incoming JSON<\/li>\n\n\n\n
                  • Avoid unnecessary overhead from reflection or third-party libraries<\/li>\n<\/ul>\n\n\n\n
                    This approach is perfect for performance-critical systems, custom APIs, or interoperable services with strict formatting needs.<\/p>\n\n\n\n
                    9. Error Handling and Edge Cases<\/h2>\n\n\n\n
                    When working with JSON manually, you need to account for the messiness of real-world data. Unlike JsonSerializer<\/code>, which throws structured exceptions, Utf8JsonReader<\/code> and Utf8JsonWriter<\/code> leave error handling up to you. That\u2019s both a responsibility and a benefit\u2014you get to decide how strict or flexible your logic should be.<\/p>\n\n\n\n
                    Common Pitfalls<\/h3>\n\n\n\n
                      \n
                    • Unexpected Token Types<\/strong>: Always check TokenType<\/code> before calling GetString()<\/code>, GetInt32()<\/code>, etc. Accessing the wrong method will throw an exception.<\/li>\n\n\n\n
                    • Missing or Extra Fields<\/strong>: If a required property is missing, decide whether to use a default, throw an error, or log and continue.<\/li>\n\n\n\n
                    • Null Values<\/strong>: Handle JsonTokenType.Null<\/code> explicitly when reading strings or nested objects.<\/li>\n\n\n\n
                    • Malformed JSON<\/strong>: Wrap deserialization in a try-catch block to detect corruption or incomplete input.<\/li>\n<\/ul>\n\n\n\n
                      Defensive Patterns<\/h3>\n\n\n
                      if<\/span> (!reader.TryGetInt32(out int value))\n{\n    \/\/ fallback or log<\/span>\n}\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
                      Being cautious in your parsing logic ensures your application won\u2019t crash on malformed data or future changes to JSON shape.<\/p>\n\n\n\n
                      10. Performance Considerations<\/h2>\n\n\n\n
                      One of the key reasons to use Utf8JsonWriter<\/code> and Utf8JsonReader<\/code> is performance. Compared to high-level serializers like JsonSerializer<\/code>, these low-level APIs offer:<\/p>\n\n\n\n
                        \n
                      • Fewer allocations<\/strong>: No boxing, reflection, or object instantiation unless you explicitly choose to.<\/li>\n\n\n\n
                      • Stream-based processing<\/strong>: Ideal for large payloads or streaming scenarios.<\/li>\n\n\n\n
                      • Precise control<\/strong>: Read only the data you need; skip the rest.<\/li>\n<\/ul>\n\n\n\n
                        In benchmarks, manual JSON parsing using these APIs often outperforms traditional serializers\u2014especially when you’re dealing with large volumes of data, partial updates, or constrained environments like microservices.<\/p>\n\n\n\n
                        However, with great power comes great responsibility. You trade off convenience and readability for control and speed. That makes these APIs better suited for hot paths (e.g. request\/response processing, logging pipelines) rather than general-purpose data handling.<\/p>\n\n\n\n
                        Pro Tip<\/h3>\n\n\n\n
                        To further reduce overhead, reuse buffers and streams when possible, and avoid unnecessary conversions (like UTF-16 string decoding) unless needed.<\/p>\n\n\n\n
                        Here is Section 11: Conclusion and Next Steps (\u2248100 words)<\/strong>:<\/p>\n\n\n\n
                        \n\n\n\n
                        11. Conclusion and Next Steps<\/h2>\n\n\n\n
                        You\u2019ve now seen how Utf8JsonWriter<\/code> and Utf8JsonReader<\/code> give you full control over JSON serialization and deserialization in .NET. From writing primitive values to handling complex object graphs and navigating JSON token streams, you\u2019ve learned how to bypass the limitations of automatic serialization with a more hands-on, performant approach.<\/p>\n\n\n\n
                        These tools are perfect for high-throughput APIs, custom integrations, and scenarios where efficiency and structure control are critical.<\/p>\n","protected":false},"excerpt":{"rendered":"
                        1. Introduction to JSON Serialization in .NET JSON has become the lingua franca of modern software systems. Whether you’re building APIs, consuming web services, or storing configuration data, chances are you’re dealing with JSON. In the .NET ecosystem, handling JSON has become increasingly streamlined\u2014thanks to the evolution of System.Text.Json, which provides a high-performance, low-allocation alternative […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_genesis_hide_title":false,"_genesis_hide_breadcrumbs":false,"_genesis_hide_singular_image":false,"_genesis_hide_footer_widgets":false,"_genesis_custom_body_class":"","_genesis_custom_post_class":"","_genesis_layout":"","_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[8,4],"tags":[],"class_list":["post-2245","post","type-post","status-publish","format-standard","category-csharp","category-programming-languages","entry"],"yoast_head":"\nUtf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#<\/title>\n<meta name=\"description\" content=\"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Utf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#\" \/>\n<meta property=\"og:description\" content=\"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/\" \/>\n<meta property=\"article:published_time\" content=\"2025-04-30T18:08:51+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2025-04-30T18:08:55+00:00\" \/>\n<meta name=\"author\" content=\"w3compadmin\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"w3compadmin\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"8 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"TechArticle\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/\"},\"author\":{\"name\":\"w3compadmin\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/#\\\/schema\\\/person\\\/a550b3e20d78bb4f79b7c6b7b53f0561\"},\"headline\":\"Building Custom JSON Serialization Logic Using Utf8JsonWriter and Utf8JsonReader\",\"datePublished\":\"2025-04-30T18:08:51+00:00\",\"dateModified\":\"2025-04-30T18:08:55+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/\"},\"wordCount\":1820,\"articleSection\":[\"C#\",\"Programming Languages\"],\"inLanguage\":\"en-US\"},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/\",\"url\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/\",\"name\":\"Utf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/#website\"},\"datePublished\":\"2025-04-30T18:08:51+00:00\",\"dateModified\":\"2025-04-30T18:08:55+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/#\\\/schema\\\/person\\\/a550b3e20d78bb4f79b7c6b7b53f0561\"},\"description\":\"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Articles Home\",\"item\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Programming Languages\",\"item\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/programming-languages\\\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Building Custom JSON Serialization Logic Using Utf8JsonWriter and Utf8JsonReader\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/#website\",\"url\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/\",\"name\":\"Developer Articles Hub\",\"description\":\"\",\"alternateName\":\"Developer Articles\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/#\\\/schema\\\/person\\\/a550b3e20d78bb4f79b7c6b7b53f0561\",\"name\":\"w3compadmin\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/wp-content\\\/litespeed\\\/avatar\\\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266\",\"url\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/wp-content\\\/litespeed\\\/avatar\\\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266\",\"contentUrl\":\"https:\\\/\\\/www.w3computing.com\\\/articles\\\/wp-content\\\/litespeed\\\/avatar\\\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266\",\"caption\":\"w3compadmin\"},\"sameAs\":[\"http:\\\/\\\/w3computing.com\\\/articles\"]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Utf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#","description":"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/","og_locale":"en_US","og_type":"article","og_title":"Utf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#","og_description":"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.","og_url":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/","article_published_time":"2025-04-30T18:08:51+00:00","article_modified_time":"2025-04-30T18:08:55+00:00","author":"w3compadmin","twitter_card":"summary_large_image","twitter_misc":{"Written by":"w3compadmin","Est. reading time":"8 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"TechArticle","@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/#article","isPartOf":{"@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/"},"author":{"name":"w3compadmin","@id":"https:\/\/www.w3computing.com\/articles\/#\/schema\/person\/a550b3e20d78bb4f79b7c6b7b53f0561"},"headline":"Building Custom JSON Serialization Logic Using Utf8JsonWriter and Utf8JsonReader","datePublished":"2025-04-30T18:08:51+00:00","dateModified":"2025-04-30T18:08:55+00:00","mainEntityOfPage":{"@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/"},"wordCount":1820,"articleSection":["C#","Programming Languages"],"inLanguage":"en-US"},{"@type":"WebPage","@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/","url":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/","name":"Utf8JsonWriter and Utf8JsonReader Tutorial for Custom JSON Serialization in C#","isPartOf":{"@id":"https:\/\/www.w3computing.com\/articles\/#website"},"datePublished":"2025-04-30T18:08:51+00:00","dateModified":"2025-04-30T18:08:55+00:00","author":{"@id":"https:\/\/www.w3computing.com\/articles\/#\/schema\/person\/a550b3e20d78bb4f79b7c6b7b53f0561"},"description":"Full guide to Utf8JsonWriter and Utf8JsonReader\u2014create custom JSON logic in .NET with full control and better speed.","breadcrumb":{"@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.w3computing.com\/articles\/building-custom-json-serialization-logic-using-utf8jsonwriter-and-utf8jsonreader\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Articles Home","item":"https:\/\/www.w3computing.com\/articles\/"},{"@type":"ListItem","position":2,"name":"Programming Languages","item":"https:\/\/www.w3computing.com\/articles\/programming-languages\/"},{"@type":"ListItem","position":3,"name":"Building Custom JSON Serialization Logic Using Utf8JsonWriter and Utf8JsonReader"}]},{"@type":"WebSite","@id":"https:\/\/www.w3computing.com\/articles\/#website","url":"https:\/\/www.w3computing.com\/articles\/","name":"Developer Articles Hub","description":"","alternateName":"Developer Articles","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.w3computing.com\/articles\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/www.w3computing.com\/articles\/#\/schema\/person\/a550b3e20d78bb4f79b7c6b7b53f0561","name":"w3compadmin","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/www.w3computing.com\/articles\/wp-content\/litespeed\/avatar\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266","url":"https:\/\/www.w3computing.com\/articles\/wp-content\/litespeed\/avatar\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266","contentUrl":"https:\/\/www.w3computing.com\/articles\/wp-content\/litespeed\/avatar\/bd481d404e42caa2763662a3bfe825f8.jpg?ver=1780141266","caption":"w3compadmin"},"sameAs":["http:\/\/w3computing.com\/articles"]}]}},"featured_image_src":null,"featured_image_src_square":null,"author_info":{"display_name":"w3compadmin","author_link":"https:\/\/www.w3computing.com\/articles\/author\/w3compadmin\/"},"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/posts\/2245","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/comments?post=2245"}],"version-history":[{"count":3,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/posts\/2245\/revisions"}],"predecessor-version":[{"id":2248,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/posts\/2245\/revisions\/2248"}],"wp:attachment":[{"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/media?parent=2245"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/categories?post=2245"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.w3computing.com\/articles\/wp-json\/wp\/v2\/tags?post=2245"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}