[API Proposal]: Add a JsonEncodedText.Value property

[eiriktsarpalis]

Background and motivation

The JsonEncodedText struct encapsulates both the UTF8 and string representations of the encoded value, however only the UTF8 value is accessible via the EncodedUtf8Bytes property. This makes the type more difficult to use in deserialization scenaria, for instance:

public class MyConverter : JsonConverter<Foo>
{
      private readonly JsonEncodedText _preEncodedPropertyName = JsonEncodedText.Encode("propertyName");

      public override void Write(Utf8JsonWriter writer, Foo value, JsonSerializerOptions options)
      {
             writer.WriteStartObject();
             writer.WriteString(_propertyName.Utf8EncodedBytes, value.Value);
             writer.WriteEndObject();
      }

      public override Foo Read(ref Utf8JsonReader reader, Type ttc, JsonSerializerOptions options)
      {
             reader.Read();
             reader.Read();
             Debug.Assert(reader.TokenType == JsonTokenType.PropertyName);
 
             string propertyName = reader.ReadPropertyName();
             if (_preEncodedPropertyName.ToString() == propertyName) // there's no proper way to fetch the UTF-16 variant when serializing
             {
                     /* read the property value */
             }
      }
}

API Proposal

namespace System.Text.Json;

public struct JsonEncodedValue
{
       public ReadOnlySpan<byte> EncodedUtf8Bytes => _utf8Value;
+      public string Value => _value ?? string.Empty;
}

API Usage

From the previous example:

      public override Foo Read(ref Utf8JsonReader reader, Type ttc, JsonSerializerOptions options)
      {
             reader.Read();
             reader.Read();
             Debug.Assert(reader.TokenType == JsonTokenType.PropertyName);
 
             string propertyName = reader.ReadPropertyName();
             if (_preEncodedPropertyName.Value == propertyName) // there's no proper way to fetch the UTF-16 variant when serializing
             {
                     /* read the property value */
             }
      }

Alternative Designs

We might expose the property as ReadOnlySpan<char>, but there's currently no reason why we would want to do this; the current implementation will always create a string for the UTF-16 representation.

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 JsonEncodedText struct encapsulates both the UTF8 and string representations of the encoded value, however only the UTF8 value is accessible via the EncodedUtf8Bytes property. This makes the type more difficult to use in deserialization scenaria, for instance:

public class MyConverter : JsonConverter<Foo>
{
      private readonly JsonEncodedText _preEncodedPropertyName = JsonEncodedText.Encode("propertyName");

      public override void Write(Utf8JsonWriter writer, Foo value, JsonSerializerOptions options)
      {
             writer.WriteStartObject();
             writer.WriteString(_propertyName.Utf8EncodedBytes, value.Value);
             writer.WriteEndObject();
      }

      public override Foo Read(ref Utf8JsonReader reader, Type ttc, JsonSerializerOptions options)
      {
             reader.Read();
             reader.Read();
             Debug.Assert(reader.TokenType == JsonTokenType.PropertyName);
 
             string propertyName = reader.ReadPropertyName();
             if (_preEncodedPropertyName.ToString() == propertyName) // there's no proper way to fetch the UTF-16 variant when serializing
             {
                     /* read the property value */
             }
      }
}

API Proposal

namespace System.Text.Json;

public struct JsonEncodedValue
{
       public ReadOnlySpan<byte> EncodedUtf8Bytes => _utf8Value;
+      public string Value => _value ?? string.Empty;
}

API Usage

From the previous example:

      public override Foo Read(ref Utf8JsonReader reader, Type ttc, JsonSerializerOptions options)
      {
             reader.Read();
             reader.Read();
             Debug.Assert(reader.TokenType == JsonTokenType.PropertyName);
 
             string propertyName = reader.ReadPropertyName();
             if (_preEncodedPropertyName.Value == propertyName) // there's no proper way to fetch the UTF-16 variant when serializing
             {
                     /* read the property value */
             }
      }

### Alternative Designs

_No response_

### Risks

_No response_

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

`api-suggestion`, `area-System.Text.Json`

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

[terrajobst]

Video

• Assuming Value would either expose the string passed to Encode or produce a string when given a span, this looks fine
  • The sketched implementation seems to suggest that for the span case the return value might be the empty string, which seems problematic.
• We should document that the string passed to Encode might be a different one from the one returned by Value
  • This happens to be the current implementation ;-)

namespace System.Text.Json;

public partial struct JsonEncodedText
{
    public string Value { get; }
}

[schoder-moreno]

Is this one up for grabs @eiriktsarpalis? If so I'd like to take a stab at it :)

[eiriktsarpalis]

Yep, go for it :-)