As a full-stack developer well-versed in C# and modern web programming, JSON is a format I work with daily when building web APIs and integrated systems. In this comprehensive, 2600+ word guide, we will dive deep into the capabilities C# provides for translating objects to and from JSON strings.

Why JSON in C# Matters

JSON has become the ubiquitous data format for web and mobile applications due to its built-in support in JavaScript, simplicity, and great readability compared to XML.

As a C# developer, sending and receiving JSON-encoded data is critical when:

  • Building ASP.NET web APIs for mobile/SPA frontend apps
  • Consuming third-party web services like the Twitter or Facebook API
  • Storing object data in JSON document databases like MongoDB
  • Streaming JSON events through real-time frameworks like SignalR

C#‘s great support for JSON serialization and deserialization makes our lives much easier when dealing with these scenarios.

Leveraging System.Text.Json

The System.Text.Json namespace is the modern JSON library for .NET, introduced in .NET Core 3. It provides high-performance APIs for translating between C# objects and JSON strings.

Let‘s explore a simple serialization example:

Product product = new Product
{
    Id = 123,
    Name = "Gizmo",
    Price = 9.99m,
    Tags = new [] { "Widget", "Gadget" } 
};

string json = JsonSerializer.Serialize(product);
// {"Id":123,"Name":"Gizmo","Price":9.99,"Tags":["Widget","Gadget"]}

And deserialization:

string json = @"{""Id"":456,...}"; // JSON 

Product product = JsonSerializer.Deserialize<Product>(json);

Behind its simple API, the C# JSON serializer handles all the complex details like:

  • Recursively encoding object references
  • Automatically formatting JSON
  • Mapping JSON element names to C# properties
  • Parsing primitive values like numbers, booleans, and strings

This frees us up as developers to focus on higher-level application logic instead of data parsing minutiae.

Controlling JSON Output

When serializing objects, we often need to customize how the JSON output is structured. Thankfully the serializer provides many helpful options and callbacks.

For example, we can change the casing style of property names: 

public class Product
{
    [JsonPropertyName("productID")] 
    public int Id {get; set;}

    [JsonPropertyName("unitPrice")]
    public decimal Price {get; set;} 
}

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

string json = JsonSerializer.Serialize(product, options);
// {"productId":123,"unitPrice":9.99}

Other naming policies include kebab-case and snake_case.

We can condense large JSON payloads by setting a custom reference handler. The handler will replace object references with metadata like $id and $ref:

{
  "$id": "1",
  "Name": "Gizmo",
  "Price": 9.99,
  "Reviews": {
    "$id": "2",
    "Title": "Luv it"    
  }
}

Customizing maximum depth and other advanced behaviors are also available via options we pass to serialize/deserialize calls.

Serialization Callbacks

For ultimate control over generated JSON, we can hook serialization callback events like OnSerializing() and OnSerialized():

public class Product
{
    [OnSerializing()]
    internal void OnSerializing(StreamingContext context)
    {
        // Execute custom logic before serialization
    }

    [OnSerialized()]
    internal void OnSerialized(StreamingContext context)
    {
        // Execute custom logic after serialization 
    }
}

These events allow injecting custom handling at different points in the pipeline.

Deserialization with Robust Handling

On the deserialization side, properly handling invalid input or unparsable values is important to avoid crashing our applications.

By default, deserialization will throw a JsonException if the JSON is malformed or incompatible with the target type. However, we can setup custom error handling rules via the deserialize options:

var options = new JsonSerializerOptions();
options.NumberHandling = JsonNumberHandling.AllowReadingFromString; 

try 
{
    Product product = JsonSerializer.Deserialize<Product>(json, options);
}
catch (JsonException ex)
{
    // Log error  
    return null; 
}

This will allow an invalid numeric value like "Price": "invalid" to get set to 0 instead of throwing.

We can also provide default values in case a JSON property is missing or null:

public class Product
{
    [JsonPropertyName("id")]
    public int Id { get; set; }

    [JsonPropertyName("price")]
    [DefaultValue(9.99)]
    public decimal Price { get; set; }
}

// {"id":123} -> Price will be 9.99

These examples demonstrate the flexibility the built-in deserializer provides – it meets all common requirements of JSON consumption without extra complexity.

Advanced Usage with Custom Converters

While the stock JSON serializer handles most needs, more advanced scenarios call for customization using converter delegates. These converters give us extremely granular control over how values flow to and from JSON.

Some example use cases:

  • Encrypting/decrypting serialized values
  • Serializing private class members
  • Integrating with non-C# model objects like NumPy arrays
  • Parsing domain-specific formats

Here is how to define and implement a custom converter:

public class Base64StringConverter : JsonConverter<string>
{
    public override string Read(ref Utf8JsonReader reader, 
                                Type typeToConvert, 
                                JsonSerializerOptions options)
    {
        // Decode base64 string 
    }

    public override void Write(Utf8JsonWriter writer, 
                               string value, 
                               JsonSerializerOptions options)
    {
        // Encode as base64 string
    }
}

And applying on a model property:

public class Message
{
    [JsonConverter(typeof(Base64StringConverter))]
    public string Text { get; set; }
}

For complex scenarios with special performance/memory needs, building out custom converters lets us squeeze every ounce of control possible out of serialization.

Comparing System.Text.Json Performance

A driving goal behind System.Text.Json was achieving best-in-class serializer performance vs popular libraries like Newtonsoft‘s Json.NET.

Benchmarks published by Microsoft using synthetic JSON documents showed up to 5-6x faster serialization and deserialization speeds:

System.Text.Json Json.NET
Serialize Complex 610 ms 3,450 ms
Deserialize 125 ms 635 ms

Source: Introducing System.Text.Json

However, exact gains depend heavily on structure and size of objects being processed.

In practice, System.Text.Json excels at CPU bound workflows – it uses blittable types allowing efficient memory usage. But tasks involving lots of small objects may run faster with Json.NET.

So while publish benchmarks give us optimistic baseline targets, real world use cases need custom profiling.

Thankfully both libraries are available side-by-side in .NET allowing us to evaluate and pick the right tool per system constraints.

Integrating with Web Frameworks

When building web APIs, JSON serialization becomes even easier by integrating with web output pipelines.

For example in ASP.NET Core MVC, we can configure custom media type formatters using System.Text.Json: 

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddJsonOptions(options => 
        {
            options.JsonSerializerOptions.DefaultIgnoreCondition = 
                JsonIgnoreCondition.WhenWritingNull;   
        });
}

Then controller actions can directly return object instances, with framework handling JSON conversion automatically:

[HttpGet]
public Product GetProduct() 
{
    Product p = ...;
    return p; 
}

This leverages the JSON APIs for seamless serialization without extra boilerplate each request.

Key Takeaways

After reviewing capabilities for serializing, deserializing, and customizing JSON in C#, some key top-level takeaways:

Performance

  • System.Text.Json provides fast, low allocation JSON translation compared to alternatives
  • Great for high-throughput web APIs and messaging pipelines

Productivity

  • Concise pipeline for encoding C# objects into web-ready JSON responses
  • Little code needed for basic serialization thanks to sensible defaults

Control

  • Highly configurable options for tweaking JSON structure
  • Callbacks allow injecting handling logic at each stage
  • Custom converters handle unique use cases

JSON and C# combine into a powerful stack for building robust systems integrated with modern web and mobile applications.

Related posts:

  1. C# URL Encoding and Decoding: A Comprehensive, In-Depth Guide
  2. Associating Enums with Strings in C#: A Complete Expert Guide
  3. How To Effectively Use Pair in C#
  4. Iterating Over C# Dictionaries with Foreach
  5. Mastering Arrays of Objects in C
  6. C# Arrays vs Lists: A Comprehensive, In-depth Comparison
  7. How to Convert String from Uppercase to Lowercase in C
  8. C# Getters and Setters: A Comprehensive Guide for Experts

Similar Posts