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

src/Docfx.Build/XRefMaps/XRefMapDownloader.cs

@@ -8,7 +8,7 @@
 
 namespace Docfx.Build.Engine;
 
-public class XRefMapDownloader
+public sealed class XRefMapDownloader
 {
     private readonly SemaphoreSlim _semaphore;
     private readonly IReadOnlyList<string> _localFileFolders;
@@ -38,22 +38,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
@@ -63,14 +63,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);
@@ -79,17 +79,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
         {
@@ -102,13 +102,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}");
 
@@ -119,8 +119,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":
@@ -132,7 +132,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}");
 
@@ -145,14 +145,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
-                    return JsonUtility.Deserialize<XRefMap>(sr);
+                    return await SystemTextJsonUtility.DeserializeAsync<XRefMap>(stream, token);
                 }
             case ".yml":
             default:
@@ -162,23 +161,4 @@ protected static async Task<XRefMap> DownloadFromWebAsync(Uri uri)
                 }
         }
     }
-
-    public static void UpdateHref(XRefMap map, Uri uri)
-    {
-        if (!string.IsNullOrEmpty(map.BaseUrl))
-        {
-            if (!Uri.TryCreate(map.BaseUrl, UriKind.Absolute, out Uri baseUri))
-            {
-                throw new InvalidDataException($"Xref map file (from {uri.AbsoluteUri}) has an invalid base url: {map.BaseUrl}.");
-            }
-            map.UpdateHref(baseUri);
-            return;
-        }
-        if (uri.Scheme == "http" || uri.Scheme == "https")
-        {
-            map.UpdateHref(uri);
-            return;
-        }
-        throw new InvalidDataException($"Xref map file (from {uri.AbsoluteUri}) missing base url.");
-    }
 }

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/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>
+public 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 | JsonIgnoreCondition.WhenWritingDefault,
+            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);
+    }
+}