How to Format JSON in C#

How to Format JSON in C#

When working with JSON data in C#, it's often necessary to format it in a human-readable way, making it easier to debug, inspect, and share with others. This guide will show you how to format JSON in C# using the built-in System.Text.Json namespace.

Quick Example

Here's a minimal example that formats a JSON string:

using System;
using System.Text.Json;

class JsonFormatter
{
    public static string FormatJson(string jsonString)
    {
        var options = new JsonSerializerOptions { WriteIndented = true };
        var jsonDoc = JsonDocument.Parse(jsonString);
        return jsonDoc.ToString(options);
    }
}

string jsonString = "{\"name\":\"John\",\"age\":30,\"city\":\"New York\"}";
string formattedJson = JsonFormatter.FormatJson(jsonString);
Console.WriteLine(formattedJson);

This code defines a JsonFormatter class with a FormatJson method that takes a JSON string as input and returns the formatted JSON string.

Step-by-Step Breakdown

Let's walk through the code:

1. using System; imports the System namespace, which provides the Console class for writing output.
2. using System.Text.Json; imports the System.Text.Json namespace, which provides the JsonSerializerOptions and JsonDocument classes.
3. class JsonFormatter { ... } defines a new class called JsonFormatter.
4. public static string FormatJson(string jsonString) { ... } defines a static method called FormatJson that takes a JSON string as input and returns the formatted JSON string.
5. var options = new JsonSerializerOptions { WriteIndented = true }; creates a new instance of JsonSerializerOptions and sets the WriteIndented property to true, which enables pretty-printing of the JSON output.
6. var jsonDoc = JsonDocument.Parse(jsonString); parses the input JSON string into a JsonDocument object.
7. return jsonDoc.ToString(options); converts the JsonDocument object back to a string using the ToString method, passing the options object to enable pretty-printing.

Handling Edge Cases

Here are some common edge cases to consider:

Empty/Null Input

If the input JSON string is empty or null, the JsonDocument.Parse method will throw an exception. To handle this, you can add a simple null check:

public static string FormatJson(string jsonString)
{
    if (string.IsNullOrEmpty(jsonString))
    {
        return string.Empty;
    }
    // ...
}

Invalid Input

If the input JSON string is invalid, the JsonDocument.Parse method will throw a JsonException. To handle this, you can wrap the parsing code in a try-catch block:

public static string FormatJson(string jsonString)
{
    try
    {
        var jsonDoc = JsonDocument.Parse(jsonString);
        return jsonDoc.ToString(options);
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"Invalid JSON: {ex.Message}");
        return string.Empty;
    }
}

Large Input

If the input JSON string is very large, the JsonDocument.Parse method may throw an OutOfMemoryException. To handle this, you can use a streaming approach using the JsonDocument.ParseAsync method:

public static async Task<string> FormatJsonAsync(string jsonString)
{
    using var jsonDoc = await JsonDocument.ParseAsync(jsonString);
    return jsonDoc.ToString(options);
}

Unicode/Special Characters

If the input JSON string contains Unicode or special characters, the JsonDocument.Parse method may throw a JsonException. To handle this, you can use the JsonSerializerOptions class to specify the character encoding:

var options = new JsonSerializerOptions
{
    WriteIndented = true,
    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};

Common Mistakes

Here are some common mistakes developers make when formatting JSON in C#:

Mistake 1: Not using WriteIndented

Forgetting to set WriteIndented to true will result in a JSON string without indentation.

// Wrong
var options = new JsonSerializerOptions();
// Correct
var options = new JsonSerializerOptions { WriteIndented = true };

Mistake 2: Not handling invalid input

Not catching JsonException exceptions will result in unhandled exceptions.

// Wrong
var jsonDoc = JsonDocument.Parse(jsonString);
// Correct
try { var jsonDoc = JsonDocument.Parse(jsonString); } catch (JsonException ex) { ... }

Mistake 3: Not using streaming for large input

Not using JsonDocument.ParseAsync for large input may result in OutOfMemoryException exceptions.

// Wrong
var jsonDoc = JsonDocument.Parse(jsonString);
// Correct
using var jsonDoc = await JsonDocument.ParseAsync(jsonString);

Performance Tips

Here are some performance tips for formatting JSON in C#:

1. Use JsonDocument.ParseAsync for large input: This approach avoids loading the entire JSON string into memory.
2. Use JsonSerializerOptions to specify encoding: This approach avoids unnecessary encoding overhead.
3. Avoid using JsonConvert: This class is deprecated and may have performance issues.

FAQ

Q: What is the difference between JsonDocument and JObject?

A: JsonDocument is a lightweight, read-only JSON parser, while JObject is a mutable JSON object.

Q: How do I format JSON with comments?

A: Unfortunately, JSON does not support comments. You may need to use a different data format, such as YAML.

Q: Can I use JsonFormatter to format JSON arrays?

A: Yes, JsonFormatter can format JSON arrays.

Q: How do I handle JSON with circular references?

A: You can use the JsonSerializerOptions class to specify a custom resolver for circular references.

Q: Can I use JsonFormatter to format JSON with Unicode characters?

A: Yes, JsonFormatter can handle Unicode characters.