Serializing Enumerations as Strings in JSON with .NET Technologies

Introduction

In many applications, it is essential to serialize objects into a JSON format for data interchange between systems or for storing structured data. One common challenge arises when dealing with enumerations (enums) within these objects: by default, they are serialized as their integer values rather than the string names that can be more meaningful and human-readable in a JSON context.

This tutorial will cover how to serialize enums as strings using various .NET technologies, including JavaScriptSerializer, Newtonsoft.Json (Json.NET), and System.Text.Json. We’ll explore attribute-based approaches for both property-level and enum-level configurations, as well as global settings that can be applied across an application.

Serialization with Newtonsoft.Json

Using StringEnumConverter

Json.NET is a popular library in the .NET ecosystem for JSON serialization and deserialization. It provides built-in functionality to serialize enums as strings via the StringEnumConverter.

Attribute-Based Configuration

You can use attributes to specify that an enum should be serialized as its name:

using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

[JsonConverter(typeof(StringEnumConverter))]
public class Person
{
    public int Age { get; set; }
    
    [JsonConverter(typeof(StringEnumConverter))]
    public Gender Gender { get; set; }
}

enum Gender 
{
    Male, 
    Female
}

By decorating the Gender property with [JsonConverter(typeof(StringEnumConverter))], Json.NET will serialize it as a string.

Enum-Level Configuration

If you want to apply this behavior to all usages of an enum without specifying attributes for each property, annotate the enum itself:

[JsonConverter(typeof(StringEnumConverter))]
enum Gender 
{
    Male,
    Female
}

Global Settings with Json.NET

For applications that require consistent serialization settings across multiple enums and objects, you can configure global settings. This approach is especially useful in larger projects or when using dependency injection frameworks.

In a Global.asax file or during application startup:

JsonConvert.DefaultSettings = () =>
{
    var settings = new JsonSerializerSettings();
    settings.Converters.Add(new StringEnumConverter { CamelCaseText = true });
    return settings;
};

This configuration ensures that all enums are serialized as strings throughout the application.

Serialization with System.Text.Json

Starting from .NET Core 3.0 and available as a NuGet package for earlier versions, System.Text.Json provides built-in support for serializing enums as strings using JsonStringEnumConverter.

Using JsonStringEnumConverter

Attribute-Based Configuration

Similar to Newtonsoft.Json, you can use attributes:

using System.Text.Json.Serialization;

public class Person
{
    public int Age { get; set; }
    
    [JsonConverter(typeof(JsonStringEnumConverter))]
    public Gender Gender { get; set; }
}

enum Gender 
{
    Male,
    Female
}

Enum-Level Configuration

Alternatively, apply the configuration at the enum level:

[JsonConverter(typeof(JsonStringEnumConverter))] 
enum Gender 
{
    Male,
    Female
}

Configuring JsonSerializerOptions Globally

In Program.cs or a similar startup file, configure JsonSerializerOptions for application-wide settings:

var options = new JsonSerializerOptions();
options.Converters.Add(new JsonStringEnumConverter());
// Use these options wherever you serialize objects to JSON.

Conclusion

Serializing enums as strings in JSON provides more readable and meaningful data interchange formats. Whether using Newtonsoft.Json or the built-in System.Text.Json, .NET offers flexible configurations through attributes and global settings. Choose the approach that best fits your project’s structure and requirements, ensuring consistent and clear serialization across your application.