feat: Add CancellationToken support for RunBuild.Exec (#10185)

feat: add `CancellationToken` support for `RunBuild.Exec`

Author: filzrev

src/Docfx.App/Helpers/DocumentBuilderWrapper.cs

@@ -15,7 +15,7 @@ internal static class DocumentBuilderWrapper
 {
     private static readonly Assembly[] s_pluginAssemblies = LoadPluginAssemblies(AppContext.BaseDirectory).ToArray();
 
-    public static void BuildDocument(BuildJsonConfig config, BuildOptions options, TemplateManager templateManager, string baseDirectory, string outputDirectory, string templateDirectory)
+    public static void BuildDocument(BuildJsonConfig config, BuildOptions options, TemplateManager templateManager, string baseDirectory, string outputDirectory, string templateDirectory, CancellationToken cancellationToken)
     {
         var postProcessorNames = config.PostProcessors.ToImmutableArray();
         var metadata = config.GlobalMetadata?.ToImmutableDictionary();
@@ -39,7 +39,7 @@ public static void BuildDocument(BuildJsonConfig config, BuildOptions options, T
         using var builder = new DocumentBuilder(s_pluginAssemblies.Concat(pluginAssemblies), postProcessorNames);
 
         var parameters = ConfigToParameter(config, options, templateManager, baseDirectory, outputDirectory, templateDirectory);
-        builder.Build(parameters, outputDirectory);
+        builder.Build(parameters, outputDirectory, cancellationToken);
     }
 
     private static IEnumerable<Assembly> LoadPluginAssemblies(string pluginDirectory)

src/Docfx.App/RunBuild.cs

@@ -16,7 +16,7 @@ internal static class RunBuild
     /// <summary>
     /// Build document with specified settings.
     /// </summary>
-    public static string Exec(BuildJsonConfig config, BuildOptions options, string configDirectory, string outputDirectory = null)
+    public static string Exec(BuildJsonConfig config, BuildOptions options, string configDirectory, string outputDirectory = null, CancellationToken cancellationToken = default)
     {
         var stopwatch = Stopwatch.StartNew();
         if (config.Template == null || config.Template.Count == 0)
@@ -36,7 +36,7 @@ public static string Exec(BuildJsonConfig config, BuildOptions options, string c
         {
             var templateManager = new TemplateManager(config.Template, config.Theme, configDirectory);
 
-            DocumentBuilderWrapper.BuildDocument(config, options, templateManager, baseDirectory, outputFolder, null);
+            DocumentBuilderWrapper.BuildDocument(config, options, templateManager, baseDirectory, outputFolder, null, cancellationToken);
 
             templateManager.ProcessTheme(outputFolder, true);
         }

src/Docfx.Build/CompilePhaseHandler.cs

@@ -39,7 +39,7 @@ public void Handle(List<HostService> hostServices, int maxParallelism)
                     _restructions.AddRange(hostService.TableOfContentRestructions);
                 }
             }
-        }, maxParallelism);
+        }, maxParallelism, Context.CancellationToken);
 
         DistributeTocRestructions(hostServices);
 
@@ -49,7 +49,7 @@ public void Handle(List<HostService> hostServices, int maxParallelism)
             Build(hostService, maxParallelism);
         }
 
-        hostServices.RunAll(Postbuild, maxParallelism);
+        hostServices.RunAll(Postbuild, maxParallelism, Context.CancellationToken);
     }
 
     private void Prepare(List<HostService> hostServices, int maxParallelism)
@@ -66,7 +66,8 @@ private void Prepare(List<HostService> hostServices, int maxParallelism)
                 {
                     m.LocalPathFromRoot ??= StringExtension.ToDisplayPath(Path.Combine(m.BaseDir, m.File));
                 },
-                maxParallelism);
+                maxParallelism,
+                Context.CancellationToken);
         }
     }
 
@@ -83,7 +84,7 @@ private void DistributeTocRestructions(List<HostService> hostServices)
         }
     }
 
-    private static void Prebuild(HostService hostService)
+    private void Prebuild(HostService hostService)
     {
         RunBuildSteps(
             hostService.Processor.BuildSteps,
@@ -99,7 +100,7 @@ private static void Prebuild(HostService hostService)
             });
     }
 
-    private static void Build(HostService hostService, int maxParallelism)
+    private void Build(HostService hostService, int maxParallelism)
     {
         hostService.Models.RunAll(
             m =>
@@ -124,10 +125,11 @@ private static void Build(HostService hostService, int maxParallelism)
                         });
                 }
             },
-            maxParallelism);
+            maxParallelism,
+            Context.CancellationToken);
     }
 
-    private static void Postbuild(HostService hostService)
+    private void Postbuild(HostService hostService)
     {
         hostService.Reload(hostService.Models);
 
@@ -140,12 +142,14 @@ private static void Postbuild(HostService hostService)
             });
     }
 
-    private static void RunBuildSteps(IEnumerable<IDocumentBuildStep> buildSteps, Action<IDocumentBuildStep> action)
+    private void RunBuildSteps(IEnumerable<IDocumentBuildStep> buildSteps, Action<IDocumentBuildStep> action)
     {
         if (buildSteps != null)
         {
             foreach (var buildStep in buildSteps.OrderBy(static step => step.BuildOrder))
             {
+                Context.CancellationToken.ThrowIfCancellationRequested();
+
                 action(buildStep);
             }
         }

src/Docfx.Build/DocumentBuildContext.cs

@@ -16,13 +16,7 @@ public sealed class DocumentBuildContext : IDocumentBuildContext
     private readonly ConcurrentDictionary<string, TocInfo> _tableOfContents = new(FilePathComparer.OSPlatformSensitiveStringComparer);
     private readonly Task<IXRefContainerReader> _reader;
 
-    public DocumentBuildContext(string buildOutputFolder)
-        : this(buildOutputFolder, Enumerable.Empty<FileAndType>(), ImmutableArray<string>.Empty, ImmutableArray<string>.Empty, 1, Directory.GetCurrentDirectory(), string.Empty, null, null) { }
-
-    public DocumentBuildContext(string buildOutputFolder, IEnumerable<FileAndType> allSourceFiles, ImmutableArray<string> externalReferencePackages, ImmutableArray<string> xrefMaps, int maxParallelism, string baseFolder, string versionName, ApplyTemplateSettings applyTemplateSetting, string rootTocPath)
-        : this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null, null) { }
-
-    public DocumentBuildContext(DocumentBuildParameters parameters)
+    public DocumentBuildContext(DocumentBuildParameters parameters, CancellationToken cancellationToken)
     {
         BuildOutputFolder = Path.Combine(Path.GetFullPath(EnvironmentContext.BaseDirectory), parameters.OutputBaseDir);
         VersionName = parameters.VersionName;
@@ -34,9 +28,10 @@ public DocumentBuildContext(DocumentBuildParameters parameters)
 
         if (parameters.XRefMaps.Length > 0)
         {
+            // Note: `_reader` task is processed asyncronously and await is called later. So OperationCancellationException is not thrown by this lines.
             _reader = new XRefCollection(
                 from u in parameters.XRefMaps
-                select new Uri(u, UriKind.RelativeOrAbsolute)).GetReaderAsync(parameters.Files.DefaultBaseDir, parameters.MarkdownEngineParameters?.FallbackFolders);
+                select new Uri(u, UriKind.RelativeOrAbsolute)).GetReaderAsync(parameters.Files.DefaultBaseDir, parameters.MarkdownEngineParameters?.FallbackFolders, cancellationToken);
         }
         RootTocPath = parameters.RootTocPath;
 
@@ -54,9 +49,18 @@ from u in parameters.XRefMaps
             }
         }
         VersionFolder = versionDir;
+        CancellationToken = cancellationToken;
     }
 
-    public DocumentBuildContext(
+    #region Constructors that used by test code.
+
+    internal DocumentBuildContext(string buildOutputFolder)
+        : this(buildOutputFolder, Enumerable.Empty<FileAndType>(), ImmutableArray<string>.Empty, ImmutableArray<string>.Empty, 1, Directory.GetCurrentDirectory(), string.Empty, null, null) { }
+
+    private DocumentBuildContext(string buildOutputFolder, IEnumerable<FileAndType> allSourceFiles, ImmutableArray<string> externalReferencePackages, ImmutableArray<string> xrefMaps, int maxParallelism, string baseFolder, string versionName, ApplyTemplateSettings applyTemplateSetting, string rootTocPath)
+        : this(buildOutputFolder, allSourceFiles, externalReferencePackages, xrefMaps, maxParallelism, baseFolder, versionName, applyTemplateSetting, rootTocPath, null, null) { }
+
+    private DocumentBuildContext(
         string buildOutputFolder,
         IEnumerable<FileAndType> allSourceFiles,
         ImmutableArray<string> externalReferencePackages,
@@ -98,6 +102,7 @@ from u in xrefMaps
         }
         VersionFolder = versionFolder;
     }
+    #endregion
 
     public string BuildOutputFolder { get; }
 
@@ -129,6 +134,8 @@ from u in xrefMaps
 
     public ICustomHrefGenerator HrefGenerator { get; }
 
+    public CancellationToken CancellationToken { get; } = CancellationToken.None;
+
     internal ConcurrentBag<ManifestItem> ManifestItems { get; } = new();
 
     private ConcurrentDictionary<string, XRefSpec> ExternalXRefSpec { get; } = new();
@@ -150,9 +157,10 @@ public void ReportExternalXRefSpec(XRefSpec spec)
 
     public void ResolveExternalXRefSpec()
     {
-        Task.WaitAll(
+        Task.WaitAll([
             Task.Run(ResolveExternalXRefSpecForSpecs),
-            Task.Run(ResolveExternalXRefSpecForNoneSpecsAsync));
+            Task.Run(ResolveExternalXRefSpecForNoneSpecsAsync)
+        ], CancellationToken);
     }
 
     private void ResolveExternalXRefSpecForSpecs()
@@ -205,7 +213,7 @@ private List<string> ResolveByExternalReferencePackages(List<string> uidList, Co
 
         var oldSpecCount = externalXRefSpec.Count;
         var list = new List<string>();
-        using (var externalReferences = new ExternalReferencePackageCollection(ExternalReferencePackages, MaxParallelism))
+        using (var externalReferences = new ExternalReferencePackageCollection(ExternalReferencePackages, MaxParallelism, CancellationToken))
         {
             foreach (var uid in uidList)
             {
@@ -401,7 +409,7 @@ public XRefSpec GetXrefSpec(string uid)
 
         if (ExternalReferencePackages.Length > 0)
         {
-            using (var externalReferences = new ExternalReferencePackageCollection(ExternalReferencePackages, MaxParallelism))
+            using (var externalReferences = new ExternalReferencePackageCollection(ExternalReferencePackages, MaxParallelism, CancellationToken))
             {
                 xref = GetExternalReference(externalReferences, uid);
             }

src/Docfx.Build/DocumentBuilder.cs

@@ -39,10 +39,12 @@ public void Build(DocumentBuildParameters parameter)
         Build(new DocumentBuildParameters[] { parameter }, parameter.OutputBaseDir);
     }
 
-    public void Build(IList<DocumentBuildParameters> parameters, string outputDirectory)
+    public void Build(IList<DocumentBuildParameters> parameters, string outputDirectory, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(parameters);
 
+        cancellationToken.ThrowIfCancellationRequested();
+
         if (parameters.Count == 0)
         {
             throw new ArgumentException("Parameters are empty.", nameof(parameters));
@@ -119,7 +121,7 @@ public void Build(IList<DocumentBuildParameters> parameters, string outputDirect
                     MetadataValidators = MetadataValidators.ToList(),
                     Processors = Processors,
                 };
-                manifests.Add(builder.Build(parameter, markdownService));
+                manifests.Add(builder.Build(parameter, markdownService, cancellationToken));
             }
         }
         if (noContentFound)

src/Docfx.Build/HostServiceCreator.cs

@@ -97,7 +97,9 @@ bool NeedApplyMetadata()
             {
                 invalidFiles.Add(file.File);
             }
-        }, _context.MaxParallelism);
+        },
+        _context.MaxParallelism,
+        _context.CancellationToken);
 
         return (models.OrderBy(m => m.File, StringComparer.Ordinal).ToArray(), invalidFiles);
     }

src/Docfx.Build/LinkPhaseHandler.cs

@@ -77,7 +77,7 @@ private IEnumerable<ManifestItemWithContext> ExportManifest(HostService hostServ
                     }
                 }
             }
-        });
+        }, Context.CancellationToken);
         return manifestItems;
     }
 
@@ -136,7 +136,7 @@ private void CheckFileLink(FileModel model, HostService hostService, SaveResult
                     Logger.LogWarning($"Invalid file link:({fileLink}).", code: WarningCodes.Build.InvalidFileLink);
                 }
             }
-        });
+        }, Context.CancellationToken);
     }
 
     private void HandleUids(SaveResult result)

src/Docfx.Build/ManifestProcessor.cs

@@ -87,7 +87,8 @@ private void NormalizeToObject()
                 }
             }
         },
-        _context.MaxParallelism);
+        _context.MaxParallelism,
+        _context.CancellationToken);
     }
 
     private void FeedOptions()
@@ -113,7 +114,8 @@ private void FeedOptions()
                 }
             }
         },
-        _context.MaxParallelism);
+        _context.MaxParallelism,
+        _context.CancellationToken);
     }
 
     private void UpdateHref()
@@ -130,7 +132,8 @@ private void UpdateHref()
                 m.Item.Content = m.FileModel.Content;
             }
         },
-        _context.MaxParallelism);
+        _context.MaxParallelism,
+        _context.CancellationToken);
     }
 
     private void ApplySystemMetadata()
@@ -171,7 +174,8 @@ private void ApplySystemMetadata()
                 }
             }
         },
-        _context.MaxParallelism);
+        _context.MaxParallelism,
+        _context.CancellationToken);
 
         _globalMetadata["_shared"] = sharedObjects;
     }

src/Docfx.Build/PostProcessors/ExtractSearchIndex.cs

@@ -37,7 +37,7 @@ public ImmutableDictionary<string, object> PrepareMetadata(ImmutableDictionary<s
         return metadata;
     }
 
-    public Manifest Process(Manifest manifest, string outputFolder)
+    public Manifest Process(Manifest manifest, string outputFolder, CancellationToken cancellationToken = default)
     {
         if (outputFolder == null)
         {
@@ -57,6 +57,8 @@ from output in item.Output
         Logger.LogInfo($"Extracting index data from {htmlFiles.Count} html files");
         foreach (var relativePath in htmlFiles)
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             var filePath = Path.Combine(outputFolder, relativePath);
             var html = new HtmlDocument();
             Logger.LogDiagnostic($"Extracting index data from {filePath}");

src/Docfx.Build/PostProcessors/HtmlPostProcessor.cs

@@ -39,7 +39,7 @@ public ImmutableDictionary<string, object> PrepareMetadata(ImmutableDictionary<s
         return metadata;
     }
 
-    public Manifest Process(Manifest manifest, string outputFolder)
+    public Manifest Process(Manifest manifest, string outputFolder, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(manifest);
         ArgumentNullException.ThrowIfNull(outputFolder);
@@ -58,6 +58,8 @@ where output.Key.Equals(".html", StringComparison.OrdinalIgnoreCase)
                                   OutputFile = output.Value.RelativePath,
                               })
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             if (!EnvironmentContext.FileAbstractLayer.Exists(tuple.OutputFile))
             {
                 continue;