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>