perf: Change serializer for XrefMap from NewtonsoftJson to System.Text.Json

src/Docfx.Build/XRefMaps/XRefMapDownloader.cs

@@ -10,7 +10,7 @@
 
 namespace Docfx.Build.Engine;
 
-public class XRefMapDownloader
+public sealed class XRefMapDownloader
 {
     private readonly SemaphoreSlim _semaphore;
     private readonly IReadOnlyList<string> _localFileFolders;
@@ -40,22 +40,22 @@ public XRefMapDownloader(string baseFolder = null, IReadOnlyList<string> fallbac
     /// <param name="uri">The uri of xref map file.</param>
     /// <returns>An instance of <see cref="XRefMap"/>.</returns>
     /// <threadsafety>This method is thread safe.</threadsafety>
-    public async Task<IXRefContainer> DownloadAsync(Uri uri)
+    public async Task<IXRefContainer> DownloadAsync(Uri uri, CancellationToken token = default)
     {
         ArgumentNullException.ThrowIfNull(uri);
 
-        await _semaphore.WaitAsync();
+        await _semaphore.WaitAsync(token);
         return await Task.Run(async () =>
         {
             try
             {
                 if (uri.IsAbsoluteUri)
                 {
-                    return await DownloadBySchemeAsync(uri);
+                    return await DownloadBySchemeAsync(uri, token);
                 }
                 else
                 {
-                    return ReadLocalFileWithFallback(uri);
+                    return await ReadLocalFileWithFallback(uri, token);
                 }
             }
             finally
@@ -65,14 +65,14 @@ public async Task<IXRefContainer> DownloadAsync(Uri uri)
         });
     }
 
-    private IXRefContainer ReadLocalFileWithFallback(Uri uri)
+    private ValueTask<IXRefContainer> ReadLocalFileWithFallback(Uri uri, CancellationToken token = default)
     {
         foreach (var localFileFolder in _localFileFolders)
         {
             var localFilePath = Path.Combine(localFileFolder, uri.OriginalString);
             if (File.Exists(localFilePath))
             {
-                return ReadLocalFile(localFilePath);
+                return ReadLocalFileAsync(localFilePath, token);
             }
         }
         throw new FileNotFoundException($"Cannot find xref map file {uri.OriginalString} in path: {string.Join(",", _localFileFolders)}", uri.OriginalString);
@@ -81,17 +81,17 @@ private IXRefContainer ReadLocalFileWithFallback(Uri uri)
     /// <remarks>
     /// Support scheme: http, https, file.
     /// </remarks>
-    protected virtual async Task<IXRefContainer> DownloadBySchemeAsync(Uri uri)
+    private async ValueTask<IXRefContainer> DownloadBySchemeAsync(Uri uri, CancellationToken token = default)
     {
         IXRefContainer result;
         if (uri.IsFile)
         {
-            result = DownloadFromLocal(uri);
+            result = await DownloadFromLocalAsync(uri, token);
         }
         else if (uri.Scheme == Uri.UriSchemeHttp ||
             uri.Scheme == Uri.UriSchemeHttps)
         {
-            result = await DownloadFromWebAsync(uri);
+            result = await DownloadFromWebAsync(uri, token);
         }
         else
         {
@@ -104,13 +104,13 @@ protected virtual async Task<IXRefContainer> DownloadBySchemeAsync(Uri uri)
         return result;
     }
 
-    protected static IXRefContainer DownloadFromLocal(Uri uri)
+    private static ValueTask<IXRefContainer> DownloadFromLocalAsync(Uri uri, CancellationToken token = default)
     {
         var filePath = uri.LocalPath;
-        return ReadLocalFile(filePath);
+        return ReadLocalFileAsync(filePath, token);
     }
 
-    private static IXRefContainer ReadLocalFile(string filePath)
+    private static async ValueTask<IXRefContainer> ReadLocalFileAsync(string filePath, CancellationToken token = default)
     {
         Logger.LogVerbose($"Reading from file: {filePath}");
 
@@ -121,8 +121,8 @@ private static IXRefContainer ReadLocalFile(string filePath)
 
             case ".json":
                 {
-                    using var stream = File.OpenText(filePath);
-                    return JsonUtility.Deserialize<XRefMap>(stream);
+                    using var stream = File.OpenRead(filePath);
+                    return await SystemTextJsonUtility.DeserializeAsync<XRefMap>(stream, token);
                 }
 
             case ".yml":
@@ -134,7 +134,7 @@ private static IXRefContainer ReadLocalFile(string filePath)
         }
     }
 
-    protected static async Task<XRefMap> DownloadFromWebAsync(Uri uri)
+    private static async Task<XRefMap> DownloadFromWebAsync(Uri uri, CancellationToken token = default)
     {
         Logger.LogVerbose($"Reading from web: {uri.OriginalString}");
 
@@ -147,14 +147,13 @@ protected static async Task<XRefMap> DownloadFromWebAsync(Uri uri)
             Timeout = TimeSpan.FromMinutes(30), // Default: 100 seconds
         };
 
-        using var stream = await httpClient.GetStreamAsync(uri);
+        using var stream = await httpClient.GetStreamAsync(uri, token);
 
         switch (Path.GetExtension(uri.AbsolutePath).ToLowerInvariant())
         {
             case ".json":
                 {
-                    using var sr = new StreamReader(stream, bufferSize: 81920); // Default :1024 byte
-                    var xrefMap = JsonUtility.Deserialize<XRefMap>(sr);
+                    var xrefMap = await SystemTextJsonUtility.DeserializeAsync<XRefMap>(stream, token);
                     xrefMap.BaseUrl = ResolveBaseUrl(xrefMap, uri);
                     return xrefMap;
                 }

src/Docfx.Build/XRefMaps/XRefMapRedirection.cs

@@ -15,7 +15,7 @@ public class XRefMapRedirection
     public string UidPrefix { get; set; }
 
     [YamlMember(Alias = "href")]
-    [JsonProperty("Href")]
+    [JsonProperty("href")]
     [JsonPropertyName("href")]
     public string Href { get; set; }
 }

src/Docfx.Common/Docfx.Common.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
     <PackageReference Include="Spectre.Console" />
   </ItemGroup>
@@ -7,4 +7,10 @@
     <ProjectReference Include="..\Docfx.Plugins\Docfx.Plugins.csproj" />
     <ProjectReference Include="..\Docfx.YamlSerialization\Docfx.YamlSerialization.csproj" />
   </ItemGroup>
+
+  <!-- TODO: Following settings will be removed after NewtonsoftJson dependencies are removed. -->
+  <ItemGroup>
+    <InternalsVisibleTo Include="docfx.Build" />
+    <InternalsVisibleTo Include="Docfx.Build.Tests" />
+  </ItemGroup>
 </Project>

src/Docfx.Common/Json/System.Text.Json/ObjectToInferredTypesConverter.cs

@@ -0,0 +1,77 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+#nullable enable
+
+namespace Docfx.Common;
+
+/// <summary>
+/// Custom JsonConverters for <see cref="object"/>.
+/// </summary>
+/// <seealso href="https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/converters-how-to?pivots=dotnet-8-0#deserialize-inferred-types-to-object-properties" />
+/// <seealso href="https://github.com/dotnet/runtime/issues/98038" />
+internal class ObjectToInferredTypesConverter : JsonConverter<object>
+{
+    /// <inheritdoc/>
+    public override object? Read(
+        ref Utf8JsonReader reader,
+        Type typeToConvert,
+        JsonSerializerOptions options)
+    {
+        switch (reader.TokenType)
+        {
+            case JsonTokenType.True:
+                return true;
+            case JsonTokenType.False:
+                return false;
+            case JsonTokenType.Number when reader.TryGetInt32(out int intValue):
+                return intValue;
+            case JsonTokenType.Number when reader.TryGetInt64(out long longValue):
+                return longValue;
+            case JsonTokenType.Number:
+                return reader.GetDouble();
+            case JsonTokenType.String when reader.TryGetDateTime(out DateTime datetime):
+                return datetime;
+            case JsonTokenType.String:
+                return reader.GetString();
+            case JsonTokenType.Null:
+                return null;
+            case JsonTokenType.StartArray:
+                {
+                    var list = new List<object?>();
+                    while (reader.Read() && reader.TokenType != JsonTokenType.EndArray)
+                    {
+                        object? element = Read(ref reader, typeof(object), options);
+                        list.Add(element);
+                    }
+                    return list;
+                }
+            case JsonTokenType.StartObject:
+                {
+                    try
+                    {
+                        using var doc = JsonDocument.ParseValue(ref reader);
+                        return JsonSerializer.Deserialize<Dictionary<string, dynamic>>(doc, options);
+                    }
+                    catch (Exception)
+                    {
+                        goto default;
+                    }
+                }
+            default:
+                {
+                    using var doc = JsonDocument.ParseValue(ref reader);
+                    return doc.RootElement.Clone();
+                }
+        }
+    }
+
+    /// <inheritdoc/>
+    public override void Write(Utf8JsonWriter writer, object objectToWrite, JsonSerializerOptions options)
+    {
+        JsonSerializer.Serialize(writer, objectToWrite, objectToWrite.GetType(), options);
+    }
+}

src/Docfx.Common/Json/System.Text.Json/SystemTextJsonUtility.cs

@@ -0,0 +1,101 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+#nullable enable
+
+namespace Docfx.Common;
+
+/// <summary>
+/// Utility class for JSON serialization/deserialization.
+/// </summary>
+internal static class SystemTextJsonUtility
+{
+    /// <summary>
+    /// Default JsonSerializerOptions options.
+    /// </summary>
+    public static readonly JsonSerializerOptions DefaultSerializerOptions;
+
+    /// <summary>
+    ///  Default JsonSerializerOptions options with indent setting.
+    /// </summary>
+    public static readonly JsonSerializerOptions IndentedSerializerOptions;
+
+    static SystemTextJsonUtility()
+    {
+        DefaultSerializerOptions = new JsonSerializerOptions()
+        {
+            // DefaultBufferSize = 1024 * 16, // TODO: Set appropriate buffer size based on benchmark.(Default: 16KB)
+            AllowTrailingCommas = true,
+            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+            PropertyNameCaseInsensitive = true,
+            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+            // DictionaryKeyPolicy = JsonNamingPolicy.CamelCase, // This setting is not compatible to `Newtonsoft.Json` serialize result.
+            NumberHandling = JsonNumberHandling.AllowReadingFromString,
+            Converters =
+            {
+                new JsonStringEnumConverter(),
+                new ObjectToInferredTypesConverter(), // Required for `Dictionary<string, object>` type deserialization.
+            },
+            WriteIndented = false,
+        };
+
+        IndentedSerializerOptions = new JsonSerializerOptions(DefaultSerializerOptions)
+        {
+            WriteIndented = true,
+        };
+    }
+
+    /// <summary>
+    /// Converts the value of a type specified by a generic type parameter into a JSON string.
+    /// </summary>
+    public static string Serialize<T>(T model, bool indented = false)
+    {
+        var options = indented
+            ? IndentedSerializerOptions
+            : DefaultSerializerOptions;
+
+        return JsonSerializer.Serialize(model, options);
+    }
+
+    /// <summary>
+    /// Converts the value of a type specified by a generic type parameter into a JSON string.
+    /// </summary>
+    public static string Serialize<T>(Stream stream, bool indented = false)
+    {
+        var options = indented
+            ? IndentedSerializerOptions
+            : DefaultSerializerOptions;
+
+        return JsonSerializer.Serialize(stream, options);
+    }
+
+    /// <summary>
+    /// Reads the UTF-8 encoded text representing a single JSON value into a TValue.
+    /// The Stream will be read to completion.
+    /// </summary>
+    public static T? Deserialize<T>(string json)
+    {
+        return JsonSerializer.Deserialize<T>(json, DefaultSerializerOptions);
+    }
+
+    /// <summary>
+    /// Reads the UTF-8 encoded text representing a single JSON value into a TValue.
+    /// The Stream will be read to completion.
+    /// </summary>
+    public static T? Deserialize<T>(Stream stream)
+    {
+        return JsonSerializer.Deserialize<T>(stream, DefaultSerializerOptions);
+    }
+
+    /// <summary>
+    /// Asynchronously reads the UTF-8 encoded text representing a single JSON value
+    //  into an instance of a type specified by a generic type parameter. The stream
+    //  will be read to completion.
+    public static async ValueTask<T?> DeserializeAsync<T>(Stream stream, CancellationToken token = default)
+    {
+        return await JsonSerializer.DeserializeAsync<T>(stream, DefaultSerializerOptions, cancellationToken: token);
+    }
+}

test/Docfx.Build.Tests/XRefMapSerializationTest.cs

@@ -10,7 +10,7 @@
 namespace Docfx.Build.Engine.Tests;
 
 public class XRefMapSerializationTest
-{  
+{
     [Fact]
     public void XRefMapSerializationRoundTripTest()
     {
@@ -43,17 +43,49 @@ public void XRefMapSerializationRoundTripTest()
             },
             Others = new Dictionary<string, object>
             {
-                ["Other1"] = "Dummy",
+                ["StringValue"] = "Dummy",
+                ["BooleanValue"] = true,
+                ["IntValue"] = int.MaxValue,
+                ["LongValue"] = long.MaxValue,
+                ["DoubleValue"] = 1.234d,
+
+                //// YamlDotNet don't deserialize dictionary's null value.
+                // ["NullValue"] = null,
+
+                //// Following types has no deserialize compatibility (NewtonsoftJson deserialize value to JArray/Jvalue)
+                // ["ArrayValue"] = new object[] { 1, 2, 3 },
+                // ["ObjectValue"] = new Dictionary<string, string>{["Prop1"="Dummy"]}
             }
         };
 
-        // Arrange
-        var jsonResult = RoundtripByNewtonsoftJson(model);
-        var yamlResult = RoundtripWithYamlDotNet(model);
+        // Validate serialized JSON text.
+        {
+            // Arrange
+            var systemTextJson = SystemTextJsonUtility.Serialize(model);
+            var newtonsoftJson = JsonUtility.Serialize(model);
 
-        // Assert
-        jsonResult.Should().BeEquivalentTo(model);
-        yamlResult.Should().BeEquivalentTo(model);
+            // Assert
+            systemTextJson.Should().Be(newtonsoftJson);
+        }
+
+        // Validate roundtrip result.
+        {
+            // Arrange
+            var systemTextJsonResult = RoundtripBySystemTextJson(model);
+            var newtonsoftJsonResult = RoundtripByNewtonsoftJson(model);
+            var yamlResult = RoundtripWithYamlDotNet(model);
+
+            // Assert
+            systemTextJsonResult.Should().BeEquivalentTo(model);
+            newtonsoftJsonResult.Should().BeEquivalentTo(model);
+            yamlResult.Should().BeEquivalentTo(model);
+        }
+    }
+
+    private static T RoundtripBySystemTextJson<T>(T model)
+    {
+        var json = SystemTextJsonUtility.Serialize(model);
+        return SystemTextJsonUtility.Deserialize<T>(json);
     }
 
     private static T RoundtripByNewtonsoftJson<T>(T model)