Fix API Diff args + async (#49164)

ericstj · web-flow · commit 1dd8c27e8a5b · 2025-05-28T12:12:27.000-07:00
diff --git a/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff.Tool/Program.cs b/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff.Tool/Program.cs
@@ -18,96 +18,96 @@ public static class Program
 
     public static async Task Main(string[] args)
     {
-        RootCommand rootCommand = new("genapidiff");
+        RootCommand rootCommand = new("ApiDiff - Tool for generating a markdown diff of two different versions of the same assembly.");
 
-        Option<string> optionBeforeAssembliesFolderPath = new(name: "", aliases: ["--before", "-b"])
+        Option<string> optionBeforeAssembliesFolderPath = new("--before", "-b")
         {
             Description = "The path to the folder containing the old (before) assemblies to be included in the diff.",
             Arity = ArgumentArity.ExactlyOne,
             Required = true
         };
 
-        Option<string> optionBeforeRefAssembliesFolderPath = new(name: "", aliases: ["--refbefore", "-rb"])
+        Option<string> optionBeforeRefAssembliesFolderPath = new("--refbefore", "-rb")
         {
             Description = "The path to the folder containing the references required by old (before) assemblies, not to be included in the diff.",
             Arity = ArgumentArity.ExactlyOne,
             Required = false
         };
 
-        Option<string> optionAfterAssembliesFolderPath = new(name: "", aliases: ["--after", "-a"])
+        Option<string> optionAfterAssembliesFolderPath = new("--after", "-a")
         {
             Description = "The path to the folder containing the new (after) assemblies to be included in the diff.",
             Arity = ArgumentArity.ExactlyOne,
             Required = true
         };
 
-        Option<string> optionAfterRefAssembliesFolderPath = new(name: "", aliases: ["--refafter", "-ra"])
+        Option<string> optionAfterRefAssembliesFolderPath = new("--refafter", "-ra")
         {
             Description = "The path to the folder containing references required by the new (after) reference assemblies, not to be included in the diff.",
             Arity = ArgumentArity.ExactlyOne,
             Required = false
         };
 
-        Option<string> optionOutputFolderPath = new(name: "", aliases: ["--output", "-o"])
+        Option<string> optionOutputFolderPath = new("--output", "-o")
         {
             Description = "The path to the output folder.",
             Arity = ArgumentArity.ExactlyOne,
             Required = true
         };
 
-        Option<string> optionBeforeFriendlyName = new(name: "", aliases: ["--beforeFriendlyName", "-bfn"])
+        Option<string> optionBeforeFriendlyName = new("--beforeFriendlyName", "-bfn")
         {
             Description = "The friendly name to describe the 'before' assembly.",
             Arity = ArgumentArity.ExactlyOne,
             Required = true
         };
 
-        Option<string> optionAfterFriendlyName = new(name: "", aliases: ["--afterFriendlyName", "-afn"])
+        Option<string> optionAfterFriendlyName = new("--afterFriendlyName", "-afn")
         {
             Description = "The friendly name to describe the 'after' assembly.",
             Arity = ArgumentArity.ExactlyOne,
             Required = true
         };
 
-        Option<string> optionTableOfContentsTitle = new(name: "", aliases: ["--tableOfContentsTitle", "-tc"])
+        Option<string> optionTableOfContentsTitle = new("--tableOfContentsTitle", "-tc")
         {
             Description = $"The optional title of the markdown table of contents file that is placed in the output folder.",
-            Arity = ArgumentArity.ZeroOrMore,
+            Arity = ArgumentArity.ExactlyOne,
             Required = false,
             DefaultValueFactory = _ => "api_diff"
         };
 
-        Option<FileInfo[]?> optionFilesWithAssembliesToExclude = new(name: "", aliases: ["--assembliesToExclude", "-eas"])
+        Option<FileInfo[]?> optionFilesWithAssembliesToExclude = new("--assembliesToExclude", "-eas")
         {
             Description = "An optional array of filepaths, each containing a list of assemblies that should be excluded from the diff. Each file should contain one assembly name per line, with no extensions.",
             Arity = ArgumentArity.ZeroOrMore,
             Required = false,
             DefaultValueFactory = _ => null
         };
 
-        Option<FileInfo[]?> optionFilesWithAttributesToExclude = new(name: "", aliases: ["--attributesToExclude", "-eattrs"])
+        Option<FileInfo[]?> optionFilesWithAttributesToExclude = new("--attributesToExclude", "-eattrs")
         {
             Description = $"An optional array of filepaths, each containing a list of attributes to exclude from the diff. Each file should contain one API full name per line. You can either modify the default file '{AttributesToExcludeDefaultFileName}' to add your own attributes, or include additional files using this command line option.",
             Arity = ArgumentArity.ZeroOrMore,
             Required = false,
             DefaultValueFactory = _ => [new FileInfo(AttributesToExcludeDefaultFileName)]
         };
 
-        Option<FileInfo[]?> optionFilesWithApisToExclude = new(name: "", aliases: ["--apisToExclude", "-eapis"])
+        Option<FileInfo[]?> optionFilesWithApisToExclude = new("--apisToExclude", "-eapis")
         {
             Description = "An optional array of filepaths, each containing a list of APIs to exclude from the diff. Each file should contain one API full name per line.",
             Arity = ArgumentArity.ZeroOrMore,
             Required = false,
             DefaultValueFactory = _ => null
         };
 
-        Option<bool> optionAddPartialModifier = new(name: "", aliases: ["--addPartialModifier", "-apm"])
+        Option<bool> optionAddPartialModifier = new("--addPartialModifier", "-apm")
         {
             Description = "Add the 'partial' modifier to types.",
             DefaultValueFactory = _ => false
         };
 
-        Option<bool> optionAttachDebugger = new(name: "", aliases: ["--attachDebugger", "-d"])
+        Option<bool> optionAttachDebugger = new("--attachDebugger", "-d")
         {
             Description = "Stops the tool at startup, prints the process ID and waits for a debugger to attach.",
             DefaultValueFactory = _ => false
@@ -128,9 +128,9 @@ public static async Task Main(string[] args)
         rootCommand.Options.Add(optionAddPartialModifier);
         rootCommand.Options.Add(optionAttachDebugger);
 
-        rootCommand.SetAction(async (ParseResult result) =>
+        rootCommand.SetAction(async (ParseResult result, CancellationToken cancellationToken) =>
         {
-            DiffConfiguration c = new(
+            DiffConfiguration diffConfig = new(
                 BeforeAssembliesFolderPath: result.GetValue(optionBeforeAssembliesFolderPath) ?? throw new NullReferenceException("Null before assemblies directory"),
                 BeforeAssemblyReferencesFolderPath: result.GetValue(optionBeforeRefAssembliesFolderPath),
                 AfterAssembliesFolderPath: result.GetValue(optionAfterAssembliesFolderPath) ?? throw new NullReferenceException("Null after assemblies directory"),
@@ -145,13 +145,15 @@ public static async Task Main(string[] args)
                 AddPartialModifier: result.GetValue(optionAddPartialModifier),
                 AttachDebugger: result.GetValue(optionAttachDebugger)
             );
-            await HandleCommandAsync(c).ConfigureAwait(false);
+            await HandleCommandAsync(diffConfig, cancellationToken).ConfigureAwait(false);
         });
         await rootCommand.Parse(args).InvokeAsync();
     }
 
-    private static Task HandleCommandAsync(DiffConfiguration diffConfig)
+    private static Task HandleCommandAsync(DiffConfiguration diffConfig, CancellationToken cancellationToken = default)
     {
+        cancellationToken.ThrowIfCancellationRequested();
+
         var log = new ConsoleLog(MessageImportance.Normal);
 
         string assembliesToExclude = string.Join(", ", diffConfig.FilesWithAssembliesToExclude?.Select(a => a.FullName) ?? []);
@@ -197,7 +199,7 @@ private static Task HandleCommandAsync(DiffConfiguration diffConfig)
                                                                    diagnosticOptions: null // TODO: If needed, add CLI option to pass specific diagnostic options
                                                                    );
 
-        return diffGenerator.RunAsync();
+        return diffGenerator.RunAsync(cancellationToken);
     }
 
     private static void WaitForDebugger()
diff --git a/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/FileOutputDiffGenerator.cs b/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/FileOutputDiffGenerator.cs
@@ -87,11 +87,13 @@ internal FileOutputDiffGenerator(ILog log,
     public IReadOnlyDictionary<string, string> Results => _results.AsReadOnly();
 
     /// <inheritdoc/>
-    public async Task RunAsync()
+    public async Task RunAsync(CancellationToken cancellationToken)
     {
         Debug.Assert(_beforeAssembliesFolderPaths.Length == 1);
         Debug.Assert(_afterAssembliesFolderPaths.Length == 1);
 
+        cancellationToken.ThrowIfCancellationRequested();
+
         (IAssemblySymbolLoader beforeLoader, Dictionary<string, IAssemblySymbol> beforeAssemblySymbols) =
             AssemblySymbolLoader.CreateFromFiles(
                 _log,
@@ -118,7 +120,7 @@ public async Task RunAsync()
                                                   _addPartialModifier,
                                                   _diagnosticOptions);
 
-        await generator.RunAsync().ConfigureAwait(false);
+        await generator.RunAsync(cancellationToken).ConfigureAwait(false);
 
         // If true, output is disk. Otherwise, it's the Results dictionary.
         if (_writeToDisk)
@@ -135,6 +137,8 @@ public async Task RunAsync()
 
         foreach ((string assemblyName, string text) in generator.Results.OrderBy(r => r.Key))
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             string fileName = $"{_tableOfContentsTitle}_{assemblyName}.md";
             tableOfContents.AppendLine($"* [{assemblyName}]({fileName})");
 
diff --git a/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/IDiffGenerator.cs b/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/IDiffGenerator.cs
@@ -13,5 +13,5 @@ public interface IDiffGenerator
     /// <summary>
     /// Asynchronously runs the diff generator and may populate the <see cref="Results"/> dictionary depending on the use case.
     /// </summary>
-    Task RunAsync();
+    Task RunAsync(CancellationToken cancellationToken);
 }
diff --git a/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/MemoryOutputDiffGenerator.cs b/src/Compatibility/ApiDiff/Microsoft.DotNet.ApiDiff/MemoryOutputDiffGenerator.cs
@@ -85,19 +85,23 @@ internal MemoryOutputDiffGenerator(
     public IReadOnlyDictionary<string, string> Results => _results.AsReadOnly();
 
     /// <inheritdoc/>
-    public async Task RunAsync()
+    public async Task RunAsync(CancellationToken cancellationToken)
     {
         Stopwatch swRun = Stopwatch.StartNew();
 
         foreach ((string beforeAssemblyName, IAssemblySymbol beforeAssemblySymbol) in _beforeAssemblySymbols)
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             // Needs to block so the _afterAssemblySymbols dictionary gets updated.
             await ProcessBeforeAndAfterAssemblyAsync(beforeAssemblyName, beforeAssemblySymbol).ConfigureAwait(false);
         }
 
         // Needs to happen after processing the before and after assemblies and filtering out the existing ones.
         foreach ((string afterAssemblyName, IAssemblySymbol afterAssemblySymbol) in _afterAssemblySymbols)
         {
+            cancellationToken.ThrowIfCancellationRequested();
+
             await ProcessNewAssemblyAsync(afterAssemblyName, afterAssemblySymbol).ConfigureAwait(false);
         }
 
diff --git a/test/Microsoft.DotNet.ApiDiff.Tests/Diff.Base.Tests.cs b/test/Microsoft.DotNet.ApiDiff.Tests/Diff.Base.Tests.cs
@@ -61,7 +61,7 @@ protected async Task RunTestAsync(
             addPartialModifier,
             DiffGeneratorFactory.DefaultDiagnosticOptions);
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         foreach ((string expectedAssemblyName, string expectedCode) in expected)
         {
diff --git a/test/Microsoft.DotNet.ApiDiff.Tests/Diff.Disk.Tests.cs b/test/Microsoft.DotNet.ApiDiff.Tests/Diff.Disk.Tests.cs
@@ -96,7 +96,7 @@ public async Task DiskRead_DiskWrite()
             outputFolderPath.DirPath,
             writeToDisk: true);
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         VerifyDiskWrite(outputFolderPath.DirPath, DefaultTableOfContentsTitle, ExpectedTableOfContents, DefaultExpectedAssemblyMarkdowns);
     }
@@ -255,7 +255,7 @@ Lines preceded by a '+' are additions and a '-' indicates removal.
             outputFolderPath.DirPath,
             writeToDisk: true);
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         VerifyDiskWrite(outputFolderPath.DirPath, DefaultTableOfContentsTitle, expectedTableOfContents, expectedAssemblyMarkdowns);
     }
@@ -286,7 +286,7 @@ public async Task DiskRead_DiskWrite_ExcludeAssembly()
             writeToDisk: true,
             filesWithAssembliesToExclude: await GetFileWithListsAsync(root, [DefaultAssemblyName]));
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         VerifyDiskWrite(outputFolderPath.FullName, DefaultTableOfContentsTitle, ExpectedEmptyTableOfContents, []);
     }
@@ -376,7 +376,7 @@ public class MySubClass
             outputFolderPath.DirPath,
             writeToDisk: true);
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         VerifyDiskWrite(outputFolderPath.DirPath, DefaultTableOfContentsTitle, ExpectedTableOfContents, expectedAssemblyMarkdowns);
     }
@@ -401,7 +401,7 @@ public async Task DiskRead_MemoryWrite()
             outputFolderPath.DirPath,
             writeToDisk: false);
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         string tableOfContentsMarkdownFilePath = Path.Join(outputFolderPath.DirPath, $"{DefaultTableOfContentsTitle}.md");
         Assert.Contains(tableOfContentsMarkdownFilePath, generator.Results.Keys);
@@ -440,7 +440,7 @@ public async Task DiskRead_MemoryWrite_ExcludeAssembly()
             writeToDisk: false,
             filesWithAssembliesToExclude: await GetFileWithListsAsync(root, [DefaultAssemblyName]));
 
-        await generator.RunAsync();
+        await generator.RunAsync(CancellationToken.None);
 
         string tableOfContentsMarkdownFilePath = Path.Join(outputFolderPath.FullName, $"{DefaultTableOfContentsTitle}.md");
         Assert.Contains(tableOfContentsMarkdownFilePath, generator.Results.Keys);

Original file line number	Diff line number	Diff line change
`@@ -13,5 +13,5 @@ public interface IDiffGenerator`
`13`	`13`	`/// <summary>`
`14`	`14`	`/// Asynchronously runs the diff generator and may populate the <see cref="Results"/> dictionary depending on the use case.`
`15`	`15`	`/// </summary>`
`16`		`- Task RunAsync();`
	`16`	`+ Task RunAsync(CancellationToken cancellationToken);`
`17`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -85,19 +85,23 @@ internal MemoryOutputDiffGenerator(`
`85`	`85`	`public IReadOnlyDictionary<string, string> Results => _results.AsReadOnly();`
`86`	`86`
`87`	`87`	`/// <inheritdoc/>`
`88`		`- public async Task RunAsync()`
	`88`	`+ public async Task RunAsync(CancellationToken cancellationToken)`
`89`	`89`	`{`
`90`	`90`	`Stopwatch swRun = Stopwatch.StartNew();`
`91`	`91`
`92`	`92`	`foreach ((string beforeAssemblyName, IAssemblySymbol beforeAssemblySymbol) in _beforeAssemblySymbols)`
`93`	`93`	`{`
	`94`	`+ cancellationToken.ThrowIfCancellationRequested();`
	`95`	`+`
`94`	`96`	`// Needs to block so the _afterAssemblySymbols dictionary gets updated.`
`95`	`97`	`await ProcessBeforeAndAfterAssemblyAsync(beforeAssemblyName, beforeAssemblySymbol).ConfigureAwait(false);`
`96`	`98`	`}`
`97`	`99`
`98`	`100`	`// Needs to happen after processing the before and after assemblies and filtering out the existing ones.`
`99`	`101`	`foreach ((string afterAssemblyName, IAssemblySymbol afterAssemblySymbol) in _afterAssemblySymbols)`
`100`	`102`	`{`
	`103`	`+ cancellationToken.ThrowIfCancellationRequested();`
	`104`	`+`
`101`	`105`	`await ProcessNewAssemblyAsync(afterAssemblyName, afterAssemblySymbol).ConfigureAwait(false);`
`102`	`106`	`}`
`103`	`107`
Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ protected async Task RunTestAsync(`
`61`	`61`	`addPartialModifier,`
`62`	`62`	`DiffGeneratorFactory.DefaultDiagnosticOptions);`
`63`	`63`
`64`		`- await generator.RunAsync();`
	`64`	`+ await generator.RunAsync(CancellationToken.None);`
`65`	`65`
`66`	`66`	`foreach ((string expectedAssemblyName, string expectedCode) in expected)`
`67`	`67`	`{`