Support ignoring property only on (de)serialization

[Symbai]

Background and Motivation

Sometimes we want to obsolete/replace properties but we don't want existing serialized content to fail. Having the ability to mark something specifically as "include this property but not on (de)serialization" would be nice. Since we already have System.Text.Json.JsonSerializerOptions.JsonIgnoreCondition it makes the most sense to just add two more enum values to it, instead of relying on something more complex.

Proposed API

public enum JsonIgnoreCondition
{
	//
	// Summary:
	//     Property will always be serialized and deserialized, regardless of System.Text.Json.JsonSerializerOptions.IgnoreNullValues
	//     configuration.
	Never = 0,
	//
	// Summary:
	//     Property will always be ignored.
	Always = 1,
	//
	// Summary:
	//     Property will only be ignored if it is null.
	WhenWritingDefault = 2,
	//
	// Summary:
	//     If the value is null, the property is ignored during serialization. This is applied
	//     only to reference-type properties and fields.
	WhenWritingNull = 3,
+	//
+	// Summary:
+	//     The property is ignored during serialization. This is applied
+	//     only to reference-type properties and fields.
+	OnSerialization = 4,
+	//
+	// Summary:
+	//     The property is ignored during deserialization. This is applied
+	//     only to reference-type properties and fields.
+	OnDeserialization = 5
}

Usage Examples

In this example we had previously used a property of type string called Number. Now we decided to use a type of INT so we created a second property. We marked the first property to be ignored on serialization. So when we receive "old" serialized content with a string number, it still gets deserialized without any issue and the number is automatically "converted" into our new property. However the old string property is no longer included when we serialize the class again.

[JsonIgnore(JsonIgnoreCondition.OnSerialization)]
public string Number
{
    get => string.Empty;
    set => NewNumber = int.Parse(value);
}

int _NewNumber;
public int NewNumber
{
    get => _NewNumber;
    set
    {
        if (value == _NewNumber) return;
        _NewNumber = value;
        OnPropertyChanged(nameof(NewNumber));
    }
}

[ghost]

Tagging subscribers to this area: @eiriktsarpalis, @layomia
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

Sometimes we want to obsolete/replace properties but we don't want existing serialized content to fail. Having the ability to mark something specifically as "include this property but not on (de)serialization" would be nice. Since we already have System.Text.Json.JsonSerializerOptions.JsonIgnoreCondition it makes the most sense to just add two more enum values to it, instead of relying on something more complex.

Proposed API

public enum JsonIgnoreCondition
{
	//
	// Summary:
	//     Property will always be serialized and deserialized, regardless of System.Text.Json.JsonSerializerOptions.IgnoreNullValues
	//     configuration.
	Never = 0,
	//
	// Summary:
	//     Property will always be ignored.
	Always = 1,
	//
	// Summary:
	//     Property will only be ignored if it is null.
	WhenWritingDefault = 2,
	//
	// Summary:
	//     If the value is null, the property is ignored during serialization. This is applied
	//     only to reference-type properties and fields.
	WhenWritingNull = 3,
+	//
+	// Summary:
+	//     The property is ignored during serialization. This is applied
+	//     only to reference-type properties and fields.
+	OnSerialization = 4,
+	//
+	// Summary:
+	//     The property is ignored during deserialization. This is applied
+	//     only to reference-type properties and fields.
+	OnDeserialization = 5
}

Usage Examples

In this example we had previously used a property of type string called Number. Now we decided to use a type of INT so we created a second property. We marked the first property to be ignored on serialization. So when we receive "old" serialized content with a string number, it still gets deserialized without any issue and the number is automatically "converted" into our new property.

[JsonIgnore(JsonIgnoreCondition.OnSerialization)]
public string Number
{
    get => string.Empty;
    set => NewNumber = int.Parse(value);
}

int _NewNumber;
public int NewNumber
{
    get => _NewNumber;
    set
    {
        if (value == _NewNumber) return;
        _NewNumber = value;
        OnPropertyChanged(nameof(NewNumber));
    }
}

Author:	Symbai
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

Related to #50294 and #55781. There are many ignore conditions and permutations thereof that the current APIs do not cover. We need to think carefully about providing a general-purpose solution that covers all use cases.

[eiriktsarpalis]

Extending the enum has its own limits (especially w.r.t. composability), so we're likely going down the route sketched in #55781 (comment). I will close this in favor of that other issue.