Improve error message for dictionary key converters not implementing ReadAsPropertyName/WriteAsPropertyName.

[bitbonk]

Description

When I serialize an object that contains a property of type Dictionary<TKey, TValue> and TKey is a custom class, I get a NotSupportedException, even if there is a JSON converter for this.

JsonSerializer.Serialize(
    new Custom
    {
        Dict = new Dictionary<CustomKey, string>
        {
            [new CustomKey {Value1 = "one", Value2 = "two"}] = "three",
            [new CustomKey {Value1 = "four", Value2 = "five"}] = "six"
        }});

class Custom
{
    public Dictionary<CustomKey, string> Dict { get; set; }
}

[JsonConverter(typeof(CustomKeyJsonConverter))]
class CustomKey
{
    public string Value1 { get; set; }
    public string Value2 { get; set; }

    public static CustomKey Parse(string text)
    {
        var values = text.Split("-");
        return new CustomKey {Value1 = values[0], Value2 = values[1]};
    }

    public override string ToString()
    {
        return $"{this.Value1}-{this.Value2}";
    }
}

class CustomKeyJsonConverter : JsonConverter<CustomKey>
{
    public override CustomKey? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return CustomKey.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, CustomKey value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString());
    }
}

Reproduction Steps

see above

Expected behavior

The serialization (and deserialization) should succeed if there is a JSON converter for the key.

Actual behavior

The following NotSupportedException exception is thrown

System.NotSupportedException
The type 'JsonTest.CustomKey' is not a supported dictionary key using converter of type 'JsonTtest.CustomKeyJsonConverter'. The unsupported member type is located on type 'System.String'. Path: $.Dict.
   at System.Text.Json.ThrowHelper.ThrowNotSupportedException(WriteStack& state, NotSupportedException ex)
   at System.Text.Json.Serialization.JsonConverter`1.WriteCore(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.Serialization.Metadata.JsonTypeInfo`1.Serialize(Utf8JsonWriter writer, T& rootValue, Object rootValueBoxed)
   at System.Text.Json.JsonSerializer.WriteString[TValue](TValue& value, JsonTypeInfo`1 jsonTypeInfo)
   at System.Text.Json.JsonSerializer.Serialize[TValue](TValue value, JsonSerializerOptions options)

Regression?

The same behavior is in .NET 6, 7 and 8, so it probably not a regression.

Known Workarounds

Write a custom JSON for the whole Dictionary<CustomKey, string> type.

Configuration

Windows 11, ,NET SDK 8.0.100-rc.2.23502.2

Other information

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

---

Description

When I serialize an object that contains a property of type Dictionary<TKey, TValue> and TKey is a custom class, I get a NotSupportedException, even if there is JSON converter for this.

JsonSerializer.Serialize(
    new Custom
    {
        Dict = new Dictionary<CustomKey, string>
        {
            [new CustomKey {Value1 = "one", Value2 = "two"}] = "three",
            [new CustomKey {Value1 = "four", Value2 = "five"}] = "six"
        }});

class Custom
{
    public Dictionary<CustomKey, string> Dict { get; set; }
}

[JsonConverter(typeof(CustomKeyJsonConverter))]
class CustomKey
{
    public string Value1 { get; set; }
    public string Value2 { get; set; }

    public static CustomKey Parse(string text)
    {
        var values = text.Split("-");
        return new CustomKey {Value1 = values[0], Value2 = values[1]};
    }

    public override string ToString()
    {
        return $"{this.Value1}-{this.Value2}";
    }
}

class CustomKeyJsonConverter : JsonConverter<CustomKey>
{
    public override CustomKey? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return CustomKey.Parse(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, CustomKey value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString());
    }
}

Reproduction Steps

see above

Expected behavior

The serialization (and deserialization) should succeed if there is a JSON converter for the key.

Actual behavior

The following NotSupportedException exception is thrown

```text
System.NotSupportedException
The type 'JsonTtest.CustomKey' is not a supported dictionary key using converter of type 'JsonTtest.CustomKeyJsonConverter'. The unsupported member type is located on type 'System.String'. Path: $.Dict.
   at System.Text.Json.ThrowHelper.ThrowNotSupportedException(WriteStack& state, NotSupportedException ex)
   at System.Text.Json.Serialization.JsonConverter`1.WriteCore(Utf8JsonWriter writer, T& value, JsonSerializerOptions options, WriteStack& state)
   at System.Text.Json.Serialization.Metadata.JsonTypeInfo`1.Serialize(Utf8JsonWriter writer, T& rootValue, Object rootValueBoxed)
   at System.Text.Json.JsonSerializer.WriteString[TValue](TValue& value, JsonTypeInfo`1 jsonTypeInfo)
   at System.Text.Json.JsonSerializer.Serialize[TValue](TValue value, JsonSerializerOptions options)

### Regression?

The same behavior is in .NET 6, 7 and 8, so it probably not a regression.

### Known Workarounds

Write a custom JSON for the whole `Dictionary<CustomKey, string>` type.

### Configuration

Windows 11, ,NET SDK 8.0.100-rc.2.23502.2

### Other information

_No response_

<table>
  <tr>
    <th align="left">Author:</th>
    <td>bitbonk</td>
  </tr>
  <tr>
    <th align="left">Assignees:</th>
    <td>-</td>
  </tr>
  <tr>
    <th align="left">Labels:</th>
    <td>

`area-System.Text.Json`

</td>
  </tr>
  <tr>
    <th align="left">Milestone:</th>
    <td>-</td>
  </tr>
</table>
</details>

[eiriktsarpalis]

Using converters for dictionary key serialization requires overriding the ReadAsPropertyName/WriteAsPropertyName methods:

class CustomKeyJsonConverter : JsonConverter<CustomKey>
{
    public override CustomKey? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => CustomKey.Parse(reader.GetString());

    public override void Write(Utf8JsonWriter writer, CustomKey value, JsonSerializerOptions options)
        => writer.WriteStringValue(value.ToString());

    public override CustomKey ReadAsPropertyName(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => CustomKey.Parse(reader.GetString());

    public override void WriteAsPropertyName(Utf8JsonWriter writer, CustomKey value, JsonSerializerOptions options)
        => writer.WritePropertyName(value.ToString());
}

Keeping the issue open since we could improve the error message to include this information.

[naeemaei]

I am interested in helping to contribute in this issue

[eiriktsarpalis]

Thanks @naeemaei, I've assigned it to you.

[naeemaei]

Considering that this error occurs when the methods are not implemented in the converter, is it better to create a method with NotImplementedException in ThrowHelper.cs or append dictionary key converter not implemented ReadAsPropertyName/WriteAsPropertyName methods message to the existing message of the DictionaryKeyTypeNotSupported key?

[DoesNotReturn]
public static void ThrowNotImplementedException_DictionaryKeyTypeConvertorNotImplemented(Type keyType, JsonConverter converter)
{
    throw new NotImplementedException(SR.Format(SR.DictionaryKeyTypeConvertorNotImplemented, keyType, converter.GetType()));
}

@eiriktsarpalis

[eiriktsarpalis]

Changing the exception type can break users that depend on catching the current exception. I think it would be preferable to just update the error message.

[bitbonk]

Just for completeness and future readers: Changing the converter as @eiriktsarpalis suggested in #93406 (comment) does fix the problem, the exceptions goes away and the type is correctly (de)serialized (testet with .NET 6).