Setting JSON Serialization Configuration At Runtime On A .NET Core API

I’m currently living the whole snake case vs camel case argument all over again. Me being a web developer, I prefer camel case (myVariable) as it fits nicely with any javascript code. Others, in what seems predominately iOS developers, prefer to use snake case (my_variable). Typically it’s going to be personal preference and on any internal API, you can do whatever floats your boat. But what about for public API’s? Can we find a way in which we can let the consumer of the API decide how they want the API to return payloads? Why yes, yes we can.

Serialization Settings In .NET Core

But first, let’s look at how we can control JSON serialization in .NET Core if we wanted to go one way over another.

We can override any particular property on a model to say always be serialized with a particular name. This is really heavy handed and I think is probably the worse case scenario. When you do this, it’s basically telling the global settings to get stuffed and you know better.

So for example if I have a model like so :

public class SerializedModel
{
    [JsonProperty("MyFirstProperty")]
    public int MyFirstProperty { get; set; }

    public int MySecondProperty { get; set; }
}

It will be serialized like :

{
	"MyFirstProperty": 123,
	"mySecondProperty": 123
}

So you’ll notice that the first property has the first letter capitalized (essentially PascalCase), but the second property without the JsonProperty attribute is using the default .NET Core serialization which is camelCase.

This may seem OK, but what if you then change the default serialization for .NET Core? What’s it going to look like then?

Let’s head over to our ConfigureServices method inside our Startup.cs. There we can change a couple of settings on our “AddMvc” call. Let’s say we now want to go with Snakecase for everything, so we change our JsonOptions to the following :

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().AddJsonOptions(opt =>
    {
        opt.SerializerSettings.ContractResolver = new DefaultContractResolver { NamingStrategy = new SnakeCaseNamingStrategy() };
    });
}

Running this, we now get :

{
	"MyFirstProperty": 123,
	"my_second_property": 123
}

Well… it did what we told it to do, but it’s definitely done us over a little bit. The property that we have overridden the naming of has won out against our “default” naming strategy. It’s what we expect to see, but often before people realize this it’s too late to go all the way back through the code and change it.

This will often become a problem when you’ve renamed a property not because of any naming strategy dogma, but because you actually want it to be called something else. So imagine the following :

public class SerializedModel
{
    [JsonProperty("userCount")]
    public int MyFirstProperty { get; set; }

    public int MySecondProperty { get; set; }
}

You’ve renamed it not because you wanted to override the naming strategy, but because you literally wanted it to be serialized under a different name. Usually because a name that makes sense internally may not make total sense to the outside world.

At this point there is no getting around this, you can make a completely custom attribute and have that handled in a custom contract resolver (Which we will investigate shortly!), but there is nothing inside the framework to help you be able to rename a property that will still respect the overall naming strategy.

Dynamic Serialization At Runtime

So far we have seen how to hard code a particular naming strategy at compile time, but nothing that can be dynamically changed. So let’s work that out!

Within JSON.net, there isn’t any ability for this to do it out of the box. In my case I’m looking to use a naming strategy based on a particular header being passed through an API. Without there being one, I had to roll my own. Now the next part of this will be sort of like a brain dump of how I got up and running. And to be fair, I worked this as a proof of concept on a small API I was working on, so it may not be great at scale, but it’s a great starting point.

So to begin with, we have to create a custom “naming” strategy that inherits from JSON.net’s abstract class “NamingStrategy”. Inside this we need to override the method called “ResolvePropertyName” to instead return the name we want to use based on an API header. Phew. OK, here’s how I went about that :

public class ApiHeaderJsonNamingStrategyOptions
{
    public string HeaderName { get; set; }
    public Dictionary<string, NamingStrategy> NamingStrategies { get; set; }
    public NamingStrategy DefaultStrategy { get; set; }
    public Func<IHttpContextAccessor> HttpContextAccessorProvider { get; set; }
}

public class ApiHeaderJsonNamingStrategy : NamingStrategy
{
    private readonly SnakeCaseNamingStrategy _snakeCaseNamingStrategy = new SnakeCaseNamingStrategy();
    private readonly CamelCaseNamingStrategy _camelCaseNamingStrategy = new CamelCaseNamingStrategy();
    private readonly ApiHeaderJsonNamingStrategyOptions _options;

    public ApiHeaderJsonNamingStrategy(ApiHeaderJsonNamingStrategyOptions options)
    {
        _options = options;
    }

    public string GetValidNamingStrategyHeader()
    {
        var httpContext = _options.HttpContextAccessorProvider().HttpContext;
        var namingStrategyHeader = httpContext.Request.Headers[_options.HeaderName].FirstOrDefault()?.ToLower();

        if (string.IsNullOrEmpty(namingStrategyHeader) || !_options.NamingStrategies.ContainsKey(namingStrategyHeader))
        {
            return string.Empty;
        }

        return namingStrategyHeader;
    }

    protected override string ResolvePropertyName(string name)
    {
        NamingStrategy strategy;

        var namingStrategyHeader = GetValidNamingStrategyHeader();

        //If the header is empty or it's a value we don't really know about. Use our default strategy. 
        if(string.IsNullOrEmpty(namingStrategyHeader))
        {
            strategy = _options.DefaultStrategy;
        }else
        {
            strategy = _options.NamingStrategies[namingStrategyHeader];
        }

        //This is actually bit of a bastardization because we shouldn't really be calling this method here. 
        //We want to actually just call the "ResolvePropertyName" method, but it's protected. This essentially ends up doing the same thing. 
        return strategy.GetPropertyName(name, false);
    }
}

OK so it’s kinda big, so let’s break it down into chunks.

First we have our settings class :

public class ApiHeaderJsonNamingStrategyOptions
{
    public string HeaderName { get; set; }
    public Dictionary<string, NamingStrategy> NamingStrategies { get; set; }
    public NamingStrategy DefaultStrategy { get; set; }
    public Func<IHttpContextAccessor> HttpContextAccessorProvider { get; set; }
}

This contains a HeaderName for what the header is going to be called, a dictionary called NamingStrategies where the keys are the header values we might expect, and their corresponding naming strategies (More on this later). We also have our DefaultStrategy incase someone doesn’t pass a header at all. Next we have a func that will return an HttpContextAccessor. We need this because in .NET Core, HttpContext is no longer an application wide static property available everywhere, it actually needs to be injected. Because we aren’t actually using DI here, we instead need to pass in a “function” that will return an HttpContextAccessor. We’ll delve more into this when we get to our configuration.

The rest of the code should be pretty straight forward. We get the header, we check if it’s valid (Matches anything in our dictionary), and if it does, we use that strategy to get the property name. If it doesn’t we then just use the default naming strategy.

Now, at this point I actually thought I was done. But as it turns out, JSON.net has aggressive caching so it doesn’t have to work out how to serialize that particular type every single request. From what I’ve seen so far, this is more about the actual custom serialization of the values, not the names, but the naming sort of gets caught up in it all anyway. The caching itself is done in what’s called a “ContractResolver”. Usually you end up using the “DefaultContractResolver” 99% of the time, but you can actually create your own and within that, setup your own caching.

Here’s mine that I created to try and overcome this caching issue:

public class ApiHeaderJsonContractResolver : DefaultContractResolver
{
    private readonly ApiHeaderJsonNamingStrategy _apiHeaderJsonNamingStrategy;
    private readonly Func<IMemoryCache> _memoryCacheProvider;
       
    public ApiHeaderJsonContractResolver(ApiHeaderJsonNamingStrategyOptions namingStrategyOptions, Func<IMemoryCache> memoryCacheProvider)
    {
        _apiHeaderJsonNamingStrategy = new ApiHeaderJsonNamingStrategy(namingStrategyOptions);
        NamingStrategy = _apiHeaderJsonNamingStrategy;
        _memoryCacheProvider = memoryCacheProvider;
    }

    public override JsonContract ResolveContract(Type type)
    {
        if (type == null)
        {
            throw new ArgumentNullException(nameof(type));
        }

        string cacheKey = _apiHeaderJsonNamingStrategy.GetValidNamingStrategyHeader() + type.ToString();
        JsonContract contract = _memoryCacheProvider().GetOrCreate(cacheKey, (entry) =>
        {
            entry.AbsoluteExpiration = DateTimeOffset.MaxValue;
            return CreateContract(type);
        });
          
        return contract;
    }
}

So what does this actually do? Well because we inherited from the DefaultContractResolver, for the most part it actually does everything the same. With some key differences, let’s start at the top.

When we construct the resolver, we pass in our naming strategy options (Truth be told, I’m not sure I like it this way, but I wasn’t originally intending to have to do a resolver so the options are for the “namingstrategy” not the resolver. Bleh). And we also pass in a “function” that can return a memory cache, again in .NET Core, memory caches are not side wide. JSON.NET actually just uses a static dictionary which also seemed OK, but I like MemoryCache’s wrappers a bit more.

The only thing we override is the ResolveContract method which is where it’s doing the aggressive caching. We actually want to cache things too! But instead of caching based purely on the type (Which is what the default does), we want to also find what the header was that was passed in. This way we cache for the combination of both the header value and the type. To get the header name, I actually reach out to the naming strategy which I probably shouldn’t be doing, but it was an easy way to “share” the logic of getting a valid header

Now it’s time to set everything up. Here’s how it looks inside our ConfigureServices method of our startup.cs :

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().AddJsonOptions(opt =>
    {
        opt.SerializerSettings.ContractResolver = new ApiHeaderJsonContractResolver(new ApiHeaderJsonNamingStrategyOptions
        {
            DefaultStrategy = new CamelCaseNamingStrategy(),
            HeaderName = "json-naming-strategy",
            HttpContextAccessorProvider = services.BuildServiceProvider().GetService<IHttpContextAccessor>,
            NamingStrategies = new Dictionary<string, NamingStrategy>
                {
                    {"camelcase", new CamelCaseNamingStrategy() },
                    {"snakecase", new SnakeCaseNamingStrategy() }
                }

        }, services.BuildServiceProvider().GetService<IMemoryCache>);
    });
}

A bit of a dogs breakfast but it works. We set up the contract resolver to use our new ApiHeaderJsonContractResolver.  We pass in our naming strategy options,  saying that the default should be CamelCase, the header should be “json-naming-strategy”, for our HttpContextAccessorProvider we tell it to use our ServiceCollection to get the service, we pass in a list of valid naming strategies. Finally we also pass in our function that should be used to pull the memory cache.

Let’s test it out!

First let’s try calling it with no header at all :

Cool, it used our default camelcase naming strategy.

Let’s tell it to use snake case now!

Perfect!

And forcing things back to camel case again!

Awesome!

So here we have managed to create our own resolver and naming strategy to allow clients to specify which naming convention they want. To be honest, it’s still a work of progress and this thing is definitely at the proof of concept stage, I’m still getting to grips on the internal workings of JSON.net, but it’s definitely a good start and OK to use on any small project you have going!