[API Proposal]: Add ReadCommentHandling to JsonSourceGenerationOptions

[Shane32]

Background and motivation

Typical appsettings.json files often contain comments, and in order for console apps to read such files in a NativeAOT environment, it is required that the deserialization process ignore comments. It appears this behavior is not yet supported. Since NativeAOT is targeted towards console applications, it seems that this would be a feature worthwhile to support. I would certainly make use of it.

API Proposal

I suggest the same name and description as is found within JsonSerializerOptions.

sealed class JsonSourceGenerationOptionsAttribute : JsonAttribute
{
    // other properties

    /// <summary>
    /// Gets or sets a value that defines how comments are handled during deserialization.
    /// </summary>
    public JsonCommentHandling ReadCommentHandling { get; set; }
}

API Usage

[JsonSourceGenerationOptions(ReadCommentHandling = JsonCommentHandling.Skip)]
[JsonSerializable(typeof(MyAppSettings))]
internal partial class SourceGenerationContext : JsonSerializerContext
{
}

Alternative Designs

public bool SkipComments { get; set; }

Risks

If Allow is not supported but only Skip and Disallow, using a boolean property like SkipComments may reduce the ability to gracefully expand the feature in the future.

References

• JsonSourceGenerationOptionsAttribute Class
• JsonSerializerOptions Class
• JsonCommentHandling Enum
• JsonSourceGenerationOptions.cs

[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

Typical appsettings.json files often contain comments, and in order for console apps to read such files in a NativeAOT environment, it is required that the deserialization process ignore comments. It appears this behavior is not yet supported. Since NativeAOT is targeted towards console applications, it seems that this would be a feature worthwhile to support. I would certainly make use of it.

API Proposal

    sealed class JsonSourceGenerationOptionsAttribute : JsonAttribute
    {
        // other properties

        /// <summary>
        /// Gets or sets a value that defines how comments are handled during deserialization.
        /// </summary>
        public JsonCommentHandling ReadCommentHandling { get; set; }
}

API Usage

[JsonSourceGenerationOptions(ReadCommentHandling = JsonCommentHandling.Skip)]
[JsonSerializable(typeof(MyAppSettings))]
internal partial class SourceGenerationContext : JsonSerializerContext
{
}

Alternative Designs

No response

Risks

No response

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

[layomia]

@tarekgh @captainsafia @eerhardt do you think this is important for 8.0 Native AOT?

[tarekgh]

@layomia what is the behavior today when encountering comments? I am trying to understand what will be broken if didn't ignore the comments.

[Shane32]

Unhandled exception. System.Text.Json.JsonException: '/' is invalid after a value. Expected either ',', '}', or ']'. Path: $.Printers[0] | LineNumber: 3 | BytePositionInLine: 6.
 ---> System.Text.Json.JsonReaderException: '/' is invalid after a value. Expected either ',', '}', or ']'. LineNumber: 3 | BytePositionInLine: 6.
   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
   at System.Text.Json.Utf8JsonReader.ConsumeNextToken(Byte marker)
   at System.Text.Json.Utf8JsonReader.ConsumeNextTokenOrRollback(Byte marker)
   at System.Text.Json.Utf8JsonReader.ReadSingleSegment()
   at System.Text.Json.Utf8JsonReader.Read()
   at System.Text.Json.Serialization.Converters.ObjectDefaultConverter`1.OnTryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, T& value)
   at System.Text.Json.Serialization.JsonConverter`1.TryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, T& value)
   at System.Text.Json.Serialization.JsonCollectionConverter`2.OnTryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, TCollection& value)
   at System.Text.Json.Serialization.JsonConverter`1.TryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, T& value)
   at System.Text.Json.Serialization.Metadata.JsonPropertyInfo`1.ReadJsonAndSetMember(Object obj, ReadStack& state, Utf8JsonReader& reader)
   at System.Text.Json.Serialization.Converters.ObjectDefaultConverter`1.OnTryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, T& value)
   at System.Text.Json.Serialization.JsonConverter`1.TryRead(Utf8JsonReader& reader, Type typeToConvert, JsonSerializerOptions options, ReadStack& state, T& value)
   at System.Text.Json.Serialization.JsonConverter`1.ReadCore(Utf8JsonReader& reader, JsonSerializerOptions options, ReadStack& state)
   --- End of inner exception stack trace ---
   at System.Text.Json.ThrowHelper.ReThrowWithPath(ReadStack& state, JsonReaderException ex)
   at System.Text.Json.Serialization.JsonConverter`1.ReadCore(Utf8JsonReader& reader, JsonSerializerOptions options, ReadStack& state)
   at System.Text.Json.JsonSerializer.ReadFromSpan[TValue](ReadOnlySpan`1 utf8Json, JsonTypeInfo jsonTypeInfo, Nullable`1 actualByteCount)
   at System.Text.Json.JsonSerializer.ReadFromSpan[TValue](ReadOnlySpan`1 json, JsonTypeInfo jsonTypeInfo)
   at System.Text.Json.JsonSerializer.Deserialize[TValue](String json, JsonTypeInfo`1 jsonTypeInfo)
   at App.ExecuteAsync(CancellationToken stoppingToken) in C:\Users\Shane\source\repos\ZboxGlobal\HiveServer\PrintClient\App.cs:line 34
   at Microsoft.Extensions.Hosting.Internal.Host.StartAsync(CancellationToken cancellationToken)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token)
   at Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync(IHost host, CancellationToken token)
   at Program.<Main>$(String[] args) in C:\___________________\Program.cs:line 12
   at Program.<Main>(String[] args)

[layomia]

@layomia what is the behavior today when encountering comments? I am trying to understand what will be broken if didn't ignore the comments.

The current behavior is throw an exception by default, but we can configure the right option to ignore at runtime:

@Shane32 does the following work for you?

JsonSerializerOptions options = new() { ReadCommentHandling = ... } ;
SourceGenerationContext context = new(options);
// Deserialize as needed
...

[Shane32]

Sorry that was the exception trace from PublishSingleFile. However, the one from PublishAot is essentially the same.

Yes, that does work actually. I thought I tried using the options class but must have tried it differently. Is this the intended design then? Thanks in advance!

[layomia]

@Shane32 yes the JsonSourceGenerationOptions class only holds configuration that "fast-path" logic needs to honor at runtime. Currently this logic is only generated for serialization, not deserialization (where ReadCommentHandling would apply). In the future if we have fast-path for deserialization (#55043) this option would be considered.