Runtime: Add JsonException and make JsonReaderException internal

[steveharter]

Proposal to add a single exception class called JsonException and make JsonReaderException internal instead of public.

The new exception contains a "Path" property used by the serializer, and the LineNumber and BytePositionInLine become nullable since they are not always set.

The original proposal was to add two new exception classes, but during review there was not enough justification for three classes. Keeping JsonReaderException is necessary since the serializer itself has a dependency to catch exceptions thrown from the reader in order to re-throw.

namespace System.Text.Json
{
    public class JsonException : System.Exception
    {
        public JsonException (string message, string path, long? lineNumber, long? bytePositionInLine, Exception innerException);
        public JsonException (string message, string path, long? lineNumber, long? bytePositionInLine);
        protected JsonException(SerializationInfo info, StreamingContext context);
        public long? BytePositionInLine { get; }
        public long? LineNumber { get; }
        public string Path { get; }
        public override void GetObjectData(System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context);
    }
}

[steveharter]

cc @ahsonkhan @rynowak

[ahsonkhan]

the existing JsonReaderException will now derive from that instead of System.Exception.

Would the JsonWriter continue to throw the InvalidOperationException/ArgumentException/etc.?

[rynowak]

For the reader/writer I think it depends case by case.

Misuse of APIs should result in InvalidOperation/Argument exceptions

Incorrect JSON should result in JsonExceptions

[steveharter]

This is not proposing changing any exception semantics except:

• The deserializer now always throws JsonSerializationException on invalid JSON (instead of JsonReaderException) - even when JsonReaderException is originally thrown from the reader.
• The serializer will throw JsonSerializationException (currently the only exception case is MaxDepth exceeded).

Otherwise as @rynowak states yes misuse of APIs will continue to result in InvalidOperation etc. One non-obvious case is the deserializer throws InvalidOperation due to "duplicate" property names when using the case-insensitive setting or [JsonProperty(name)] - this is raised before inspecting any JSON.

[rynowak]

API proposal looks like what I would expect.

[steveharter]

Updated to make JsonReaderException internal.

[wli3]

This breaking change blocked our build. https://github.com/dotnet/cli/pull/11392. And I am surprised there is no concrete decision which Exception is the replacement (JsonSerializationException is not exposed). But the type is removed first.

From the conversion i will replace all JsonReaderException with JsonException. Please file bug on CLI if there is further decision.

[steveharter]

Closing as API approved