Add opt-in for converters to handle null

src/libraries/System.Text.Json/ref/System.Text.Json.cs

@@ -489,6 +489,8 @@ public abstract partial class JsonConverter<T> : System.Text.Json.Serialization.
  {
  protected internal JsonConverter() { }
  public override bool CanConvert(System.Type typeToConvert) { throw null; }
+ public virtual bool HandleNull { get { throw null; } }
+ [return: System.Diagnostics.CodeAnalysis.MaybeNull]
  public abstract T Read(ref System.Text.Json.Utf8JsonReader reader, System.Type typeToConvert, System.Text.Json.JsonSerializerOptions options);
  public abstract void Write(System.Text.Json.Utf8JsonWriter writer, T value, System.Text.Json.JsonSerializerOptions options);
  }

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ArrayConverter.cs

@@ -4,6 +4,7 @@
 
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -16,9 +17,9 @@ internal sealed class ArrayConverter<TCollection, TElement>
  {
  internal override bool CanHaveIdMetadata => false;
 
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((List<TElement>)state.Current.ReturnValue!).Add(value);
+ ((List<TElement>)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ConcurrentQueueOfTConverter.cs

@@ -4,16 +4,17 @@
 
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class ConcurrentQueueOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : ConcurrentQueue<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Enqueue(value);
+ ((TCollection)state.Current.ReturnValue!).Enqueue(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ConcurrentStackOfTConverter.cs

@@ -4,16 +4,17 @@
 
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class ConcurrentStackOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : ConcurrentStack<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Push(value);
+ ((TCollection)state.Current.ReturnValue!).Push(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/DictionaryDefaultConverter.cs

@@ -16,7 +16,7 @@ internal abstract class DictionaryDefaultConverter<TCollection, TValue>
  /// <summary>
  /// When overridden, adds the value to the collection.
  /// </summary>
- protected abstract void Add(TValue value, JsonSerializerOptions options, ref ReadStack state);
+ protected abstract void Add([AllowNull] TValue value, JsonSerializerOptions options, ref ReadStack state);
 
  /// <summary>
  /// When overridden, converts the temporary collection held in state.Current.ReturnValue to the final collection.

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/DictionaryOfStringTValueConverter.cs

@@ -3,7 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
-using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -15,10 +15,10 @@ internal sealed class DictionaryOfStringTValueConverter<TCollection, TValue>
  : DictionaryDefaultConverter<TCollection, TValue>
  where TCollection : Dictionary<string, TValue>
  {
- protected override void Add(TValue value, JsonSerializerOptions options, ref ReadStack state)
+ protected override void Add([AllowNull] TValue value, JsonSerializerOptions options, ref ReadStack state)
  {
  string key = state.Current.JsonPropertyNameAsString!;
- ((TCollection)state.Current.ReturnValue!)[key] = value;
+ ((TCollection)state.Current.ReturnValue!)[key] = value!;
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ICollectionOfTConverter.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -13,9 +14,9 @@ internal sealed class ICollectionOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : ICollection<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((ICollection<TElement>)state.Current.ReturnValue!).Add(value);
+ ((ICollection<TElement>)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IDictionaryConverter.cs

@@ -4,6 +4,7 @@
 
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IDictionaryOfStringTValueConverter.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -14,10 +15,10 @@ internal sealed class IDictionaryOfStringTValueConverter<TCollection, TValue>
  : DictionaryDefaultConverter<TCollection, TValue>
  where TCollection : IDictionary<string, TValue>
  {
- protected override void Add(TValue value, JsonSerializerOptions options, ref ReadStack state)
+ protected override void Add([AllowNull] TValue value, JsonSerializerOptions options, ref ReadStack state)
  {
  string key = state.Current.JsonPropertyNameAsString!;
- ((TCollection)state.Current.ReturnValue!)[key] = value;
+ ((TCollection)state.Current.ReturnValue!)[key] = value!;
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IEnumerableDefaultConverter.cs

@@ -13,7 +13,7 @@ namespace System.Text.Json.Serialization.Converters
  internal abstract class IEnumerableDefaultConverter<TCollection, TElement>
  : JsonCollectionConverter<TCollection, TElement>
  {
- protected abstract void Add(TElement value, ref ReadStack state);
+ protected abstract void Add([AllowNull] TElement value, ref ReadStack state);
  protected abstract void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options);
  protected virtual void ConvertCollection(ref ReadStack state, JsonSerializerOptions options) { }
 
@@ -66,7 +66,7 @@ internal override bool OnTryRead(
  }
 
  // Obtain the CLR value from the JSON and apply to the object.
- TElement element = elementConverter.Read(ref reader, elementConverter.TypeToConvert, options);
+ TElement element = elementConverter.Read(ref reader, elementConverter.TypeToConvert, options)!;
  Add(element, ref state);
  }
  }

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IEnumerableOfTConverter.cs

@@ -4,6 +4,7 @@
 
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -14,9 +15,9 @@ internal sealed class IEnumerableOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : IEnumerable<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((List<TElement>)state.Current.ReturnValue!).Add(value);
+ ((List<TElement>)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IListOfTConverter.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -13,9 +14,9 @@ internal sealed class IListOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : IList<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Add(value);
+ ((TCollection)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/IReadOnlyDictionaryOfStringTValueConverter.cs

@@ -3,17 +3,18 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class IReadOnlyDictionaryOfStringTValueConverter<TCollection, TValue>
  : DictionaryDefaultConverter<TCollection, TValue>
  where TCollection : IReadOnlyDictionary<string, TValue>
  {
- protected override void Add(TValue value, JsonSerializerOptions options, ref ReadStack state)
+ protected override void Add([AllowNull] TValue value, JsonSerializerOptions options, ref ReadStack state)
  {
  string key = state.Current.JsonPropertyNameAsString!;
- ((Dictionary<string, TValue>)state.Current.ReturnValue!)[key] = value;
+ ((Dictionary<string, TValue>)state.Current.ReturnValue!)[key] = value!;
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ISetOfTConverter.cs

@@ -3,16 +3,17 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class ISetOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : ISet<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Add(value);
+ ((TCollection)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ImmutableDictionaryOfStringTValueConverter.cs

@@ -3,17 +3,18 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class ImmutableDictionaryOfStringTValueConverter<TCollection, TValue>
  : DictionaryDefaultConverter<TCollection, TValue>
  where TCollection : IReadOnlyDictionary<string, TValue>
  {
- protected override void Add(TValue value, JsonSerializerOptions options, ref ReadStack state)
+ protected override void Add([AllowNull] TValue value, JsonSerializerOptions options, ref ReadStack state)
  {
  string key = state.Current.JsonPropertyNameAsString!;
- ((Dictionary<string, TValue>)state.Current.ReturnValue!)[key] = value;
+ ((Dictionary<string, TValue>)state.Current.ReturnValue!)[key] = value!;
  }
 
  internal override bool CanHaveIdMetadata => false;

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ImmutableEnumerableOfTConverter.cs

@@ -3,16 +3,17 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class ImmutableEnumerableOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : IEnumerable<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((List<TElement>)state.Current.ReturnValue!).Add(value);
+ ((List<TElement>)state.Current.ReturnValue!).Add(value!);
  }
 
  internal override bool CanHaveIdMetadata => false;

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/ListOfTConverter.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
@@ -11,9 +12,9 @@ internal sealed class ListOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection: List<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Add(value);
+ ((TCollection)state.Current.ReturnValue!).Add(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/QueueOfTConverter.cs

@@ -3,16 +3,17 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class QueueOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : Queue<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Enqueue(value);
+ ((TCollection)state.Current.ReturnValue!).Enqueue(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Collection/StackOfTConverter.cs

@@ -3,16 +3,17 @@
 // See the LICENSE file in the project root for more information.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace System.Text.Json.Serialization.Converters
 {
  internal sealed class StackOfTConverter<TCollection, TElement>
  : IEnumerableDefaultConverter<TCollection, TElement>
  where TCollection : Stack<TElement>
  {
- protected override void Add(TElement value, ref ReadStack state)
+ protected override void Add([AllowNull] TElement value, ref ReadStack state)
  {
- ((TCollection)state.Current.ReturnValue!).Push(value);
+ ((TCollection)state.Current.ReturnValue!).Push(value!);
  }
 
  protected override void CreateCollection(ref Utf8JsonReader reader, ref ReadStack state, JsonSerializerOptions options)

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Value/KeyValuePairConverter.cs

@@ -99,7 +99,7 @@ internal override bool OnTryRead(
  ThrowHelper.ThrowJsonException();
  }
 
- value = new KeyValuePair<TKey, TValue>(k, v);
+ value = new KeyValuePair<TKey, TValue>(k!, v!);
  return true;
  }
 

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/Value/NullableConverter.cs

@@ -17,6 +17,8 @@ public NullableConverter(JsonConverter<T> converter)
 
  public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
  {
+ // We do not check _converter.HandleNull, as the underlying struct cannot be null.
+ // A custom converter for some type T? can handle null.
  if (reader.TokenType == JsonTokenType.Null)
  {
  return null;
@@ -30,6 +32,8 @@ public override void Write(Utf8JsonWriter writer, T? value, JsonSerializerOption
  {
  if (!value.HasValue)
  {
+ // We do not check _converter.HandleNull, as the underlying struct cannot be null.
+ // A custom converter for some type T? can handle null.
  writer.WriteNullValue();
  }
  else

src/libraries/System.Text.Json/src/System/Text/Json/Serialization/JsonConverter.cs

@@ -40,12 +40,6 @@ internal JsonConverter() { }
 
  internal abstract Type? ElementType { get; }
 
- /// <summary>
- /// Cached value of ShouldHandleNullValue. It is cached since the converter should never
- /// change the value depending on state and because it may contain non-trival logic.
- /// </summary>
- internal bool HandleNullValue { get; set; }
-
  /// <summary>
  /// Cached value of TypeToConvert.IsValueType, which is an expensive call.
  /// </summary>