[API Proposal]: Add Lock() and IsLocked methods to JsonSerializerOptions

[eiriktsarpalis]

Background and motivation

The JsonSerializerOptions class supports mutation of its settings, until first used in a serialization operation. After that, the class gets locked and any attempt to update settings will result in InvalidOperationException:

var options = new JsonSerializerOptions();
options.WriteIndented = true; // success, options is mutable
JsonSerializer.Serialize(someValue, options);
options.WriteIndented = true; // throws, options is locked

The issue with this design is that users have no clear indication of whether an options instance is locked or not. Often, users need to serialize a throwaway value just to make sure no further modification can take place. We want to make this state more transparent and controllable by users.

API Proposal

namespace System.Text.Json

public partial class JsonSerializerOptions
{
    public bool IsLocked { get; }
    public void Lock(); // idempotent lock operation
}

API Usage

var options = new JsonSerializerOptions { TypeInfoResolver = new MyFancyResolver(), WriteIndented = true };

Console.WriteLine(options.IsLocked); // False
var converter = options.GetConverter(typeof(MyPoco)); // Returns an uncached converter instance

options.Lock(); // lock the instance and initialize the metadata cache

Console.WriteLine(options.IsLocked); // True
converter = options.GetConverter(typeof(MyPoco)); // Returns a cached converter instance

Alternative Designs

We might want to consider exposing equivalent functionality to JsonTypeInfo and JsonPropertyInfo, whose design uses a similar locking design.

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The JsonSerializerOptions class supports mutation of its settings, until first used in a serialization operation. After that, the class gets locked and any attempt to update settings will result in InvalidOperationException:

var options = new JsonSerializerOptions();
options.WriteIndented = true; // success, options is mutable
JsonSerializer.Serialize(someValue, options);
options.WriteIndented = true; // throws, options is locked

The issue with this design is that users have no clear indication of whether an options instance is locked or not. Often, users need to serialize a throwaway value just to make sure no further modification can take place. We want to make this state more transparent and controllable by users.

API Proposal

namespace System.Text.Json

public partial class JsonSerializerOptions
{
    public bool IsLocked { get; }
    public void Lock(); // idempotent lock operation
}

API Usage

var options = new JsonSerializerOptions { TypeInfoResolver = new MyFancyResolver(), WriteIndented = true };

Console.WriteLine(options.IsLocked); // False
var converter = options.GetConverter(typeof(MyPoco)); // Returns an uncached converter instance

options.Lock(); // lock the instance and initialize the metadata cache

Console.WriteLine(options.IsLocked); // True
converter = options.GetConverter(typeof(MyPoco)); // Returns a cached converter instance

Alternative Designs

We might want to consider exposing equivalent functionality to JsonTypeInfo and JsonPropertyInfo, whose design uses a similar locking design.

Risks

No response

Author:	eiriktsarpalis
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json
Milestone:	8.0.0

[svick]

This has been previously discussed at #54482. I think one of the two issues should be closed.

Also, I stand by the comment I made there saying that Freeze would be a better name for this. (Especially since Lock in .Net usually implies mutual exclusion, and this is not that.)

[eiriktsarpalis]

Also, I stand by the comment I made there saying that Freeze would be a better name for this. (Especially since Lock in .Net usually implies mutual exclusion, and this is not that.)

That's a good point, although I've never heard of "Freeze" being used in this context. Any other alternatives? One that I can think of is IsImmutable/MakeImmutable().

This has been previously discussed at #54482.

That's my bad, I should have gone through the backlog before opening this.

[Clockwork-Muse]

Any other alternatives?

Build?

[eiriktsarpalis]

Closing as duplicate of #54482.