Add cancellation token support (#19)

neoscie · web-flow · commit 4ec29fee0731 · 2025-01-23T10:27:10.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added cancellation token support for commands
 - Added a built-in `verify-dependencies` command that validates the application's Dependency Injection setup by ensuring all required services are fully and correctly registered in the composition root.
 
 ### Changed
diff --git a/Neolution.DotNet.Console.SampleAsync/Commands/Echo/EchoCommand.cs b/Neolution.DotNet.Console.SampleAsync/Commands/Echo/EchoCommand.cs
@@ -41,7 +41,7 @@ public EchoCommand(ILogger<EchoCommand> logger, IHostEnvironment environment, IC
         }
 
         /// <inheritdoc />
-        public Task RunAsync(EchoOptions options)
+        public Task RunAsync(EchoOptions options, CancellationToken cancellationToken)
         {
             ArgumentNullException.ThrowIfNull(options);
 
diff --git a/Neolution.DotNet.Console.SampleAsync/Commands/GuidGen/GuidGenCommand.cs b/Neolution.DotNet.Console.SampleAsync/Commands/GuidGen/GuidGenCommand.cs
@@ -26,7 +26,7 @@ public GuidGenCommand(ILogger<GuidGenCommand> logger)
         }
 
         /// <inheritdoc />
-        public Task RunAsync(GuidGenOptions options)
+        public Task RunAsync(GuidGenOptions options, CancellationToken cancellationToken)
         {
             if (options == null)
             {
@@ -42,6 +42,7 @@ public Task RunAsync(GuidGenOptions options)
             }
 
             System.Console.WriteLine(result);
+
             this.logger.LogTrace("Wrote result to console");
             return Task.CompletedTask;
         }
diff --git a/Neolution.DotNet.Console.SampleAsync/Commands/Start/StartCommand.cs b/Neolution.DotNet.Console.SampleAsync/Commands/Start/StartCommand.cs
@@ -32,10 +32,10 @@ public StartCommand(ILogger<StartCommand> logger, IHttpClientFactory httpClientF
         }
 
         /// <inheritdoc />
-        public async Task RunAsync(StartOptions options)
+        public async Task RunAsync(StartOptions options, CancellationToken cancellationToken)
         {
             this.logger.LogDebug("Check if Google is online");
-            var response = await this.httpClient.GetAsync(new Uri("https://www.google.com"));
+            var response = await this.httpClient.GetAsync(new Uri("https://www.google.com"), cancellationToken);
             if (response.IsSuccessStatusCode)
             {
                 this.logger.LogTrace("Internet connection is available");
diff --git a/Neolution.DotNet.Console.UnitTests/DotNetConsoleBuilderTests.cs b/Neolution.DotNet.Console.UnitTests/DotNetConsoleBuilderTests.cs
@@ -14,6 +14,11 @@
     /// </summary>
     public class DotNetConsoleBuilderTests
     {
+        /// <summary>
+        /// The argument string for the internal verify-dependencies command
+        /// </summary>
+        private static readonly string[] VerifyDependenciesArgs = { "verify-dependencies" };
+
         /// <summary>
         /// Given a mistyped verb, when a default verb is defined, then should throw on console building.
         /// </summary>
@@ -98,7 +103,7 @@ public void GivenInvalidArguments_WhenNoDefaultVerbIsDefined_ThenShouldNotThrowO
         public void GivenVerifyDependenciesCommand_WhenRegistrationIsMissing_ThenShouldThrow()
         {
             // Arrange
-            var builder = DotNetConsole.CreateBuilderWithReference(Assembly.GetAssembly(typeof(DefaultCommand))!, new[] { "verify-dependencies" });
+            var builder = DotNetConsole.CreateBuilderWithReference(Assembly.GetAssembly(typeof(DefaultCommand))!, VerifyDependenciesArgs);
 
             // Intentionally only registering the transient service and not the scoped and singleton services.
             builder.Services.AddTransient<ITransientServiceStub, TransientServiceStub>();
diff --git a/Neolution.DotNet.Console.UnitTests/DotNetConsoleRunTests.cs b/Neolution.DotNet.Console.UnitTests/DotNetConsoleRunTests.cs
@@ -57,10 +57,7 @@ public void GivenServicesWithVariousServiceLifetimes_WhenRunningConsoleApp_ThenS
         [InlineData("verify-dependencies")]
         public void GivenValidArguments_WhenNoDefaultVerbIsDefined_ThenShouldNotThrow([NotNull] string args)
         {
-            if (args == null)
-            {
-                throw new ArgumentNullException(nameof(args));
-            }
+            ArgumentNullException.ThrowIfNull(args);
 
             // Arrange
             var builder = DotNetConsole.CreateBuilderWithReference(Assembly.GetAssembly(typeof(DefaultCommand))!, args.Split(" "));
diff --git a/Neolution.DotNet.Console.UnitTests/Fakes/DefaultCommand.cs b/Neolution.DotNet.Console.UnitTests/Fakes/DefaultCommand.cs
@@ -1,5 +1,6 @@
 ﻿namespace Neolution.DotNet.Console.UnitTests.Fakes
 {
+    using System.Threading;
     using System.Threading.Tasks;
     using Microsoft.Extensions.Hosting;
     using Neolution.DotNet.Console.Abstractions;
@@ -33,7 +34,7 @@ public DefaultCommand(IUnitTestLogger logger, IHostEnvironment environment)
         }
 
         /// <inheritdoc />
-        public async Task RunAsync(DefaultOptions options)
+        public async Task RunAsync(DefaultOptions options, CancellationToken cancellationToken)
         {
             this.logger.Log("options", options);
             this.logger.Log("environment", this.environment);
diff --git a/Neolution.DotNet.Console.UnitTests/Fakes/EchoCommand.cs b/Neolution.DotNet.Console.UnitTests/Fakes/EchoCommand.cs
@@ -1,5 +1,6 @@
 ﻿namespace Neolution.DotNet.Console.UnitTests.Fakes
 {
+    using System.Threading;
     using System.Threading.Tasks;
     using Neolution.DotNet.Console.Abstractions;
     using Neolution.DotNet.Console.UnitTests.Spies;
@@ -25,7 +26,7 @@ public EchoCommand(IUnitTestLogger logger)
         }
 
         /// <inheritdoc />
-        public async Task RunAsync(EchoOptions options)
+        public async Task RunAsync(EchoOptions options, CancellationToken cancellationToken)
         {
             this.logger.Log("options", options);
             await Task.CompletedTask;
diff --git a/Neolution.DotNet.Console.UnitTests/Neolution.DotNet.Console.UnitTests.csproj b/Neolution.DotNet.Console.UnitTests/Neolution.DotNet.Console.UnitTests.csproj
@@ -17,7 +17,7 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
     <PackageReference Include="Neolution.CodeAnalysis.TestsRuleset" Version="3.2.1">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
diff --git a/Neolution.DotNet.Console.UnitTests/Stubs/InjectServicesWithVariousLifetimesCommandStub.cs b/Neolution.DotNet.Console.UnitTests/Stubs/InjectServicesWithVariousLifetimesCommandStub.cs
@@ -1,5 +1,6 @@
 ﻿namespace Neolution.DotNet.Console.UnitTests.Stubs
 {
+    using System.Threading;
     using System.Threading.Tasks;
     using Neolution.DotNet.Console.Abstractions;
 
@@ -38,7 +39,7 @@ public InjectServicesWithVariousLifetimesCommandStub(ITransientServiceStub trans
         }
 
         /// <inheritdoc />
-        public async Task RunAsync(InjectServicesWithVariousLifetimesOptionsStub options)
+        public async Task RunAsync(InjectServicesWithVariousLifetimesOptionsStub options, CancellationToken cancellationToken)
         {
             await this.transientService.DoSomethingAsync();
             await this.scopedService.DoSomethingAsync();
diff --git a/Neolution.DotNet.Console/Abstractions/IDotNetConsoleCommand.cs b/Neolution.DotNet.Console/Abstractions/IDotNetConsoleCommand.cs
@@ -1,5 +1,6 @@
 ﻿namespace Neolution.DotNet.Console.Abstractions
 {
+    using System.Threading;
     using System.Threading.Tasks;
 
     /// <summary>
@@ -12,7 +13,8 @@ public interface IDotNetConsoleCommand<in TOptions>
         /// Runs the command with the specified options asynchronously.
         /// </summary>
         /// <param name="options">The options.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>The <see cref="Task"/>.</returns>
-        Task RunAsync(TOptions options);
+        Task RunAsync(TOptions options, CancellationToken cancellationToken);
     }
 }
diff --git a/Neolution.DotNet.Console/DotNetConsole.cs b/Neolution.DotNet.Console/DotNetConsole.cs
@@ -1,12 +1,17 @@
 ﻿namespace Neolution.DotNet.Console
 {
     using System;
+    using System.Globalization;
     using System.Reflection;
+    using System.Threading;
     using System.Threading.Tasks;
     using CommandLine;
+    using Microsoft.Extensions.Configuration;
     using Microsoft.Extensions.DependencyInjection;
     using Microsoft.Extensions.Hosting;
     using Neolution.DotNet.Console.Abstractions;
+    using NLog;
+    using NLog.Extensions.Logging;
 
     /// <summary>
     /// The console application.
@@ -82,16 +87,55 @@ public static DotNetConsoleBuilder CreateBuilderWithReference(Assembly servicesA
         /// <inheritdoc />
         public async Task RunAsync()
         {
-            await this.commandLineParserResult.WithParsedAsync(this.RunWithOptionsAsync);
+            using var cancellationTokenSource = new CancellationTokenSource();
+
+            Console.CancelKeyPress += (_, e) =>
+            {
+                // Prevent the console from terminating immediately and instead cancel the cancellation token source.
+                e.Cancel = true;
+                cancellationTokenSource.Cancel();
+            };
+
+            await this.RunAsync(cancellationTokenSource.Token);
+        }
+
+        /// <summary>
+        /// Runs the application.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>The <see cref="Task"/>.</returns>
+        public async Task RunAsync(CancellationToken cancellationToken)
+        {
+            try
+            {
+                cancellationToken.ThrowIfCancellationRequested();
+                await this.commandLineParserResult.WithParsedAsync(async options => await this.RunWithOptionsAsync(options, cancellationToken));
+            }
+            catch (OperationCanceledException)
+            {
+                try
+                {
+                    var logger = LogManager.Setup().LoadConfigurationFromSection(this.Services.GetRequiredService<IConfiguration>()).GetCurrentClassLogger();
+                    logger.Log(LogLevel.Info, CultureInfo.InvariantCulture, message: "Operation was canceled by the user.");
+                }
+                catch (Exception)
+                {
+                    // Ignore any exceptions that might occur while trying to log the cancellation
+                }
+            }
         }
 
         /// <summary>
         /// Runs the command with options asynchronously.
         /// </summary>
         /// <param name="options">The options.</param>
-        /// <returns>The <see cref="Task"/>.</returns>
-        private async Task RunWithOptionsAsync(object options)
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns> The <see cref="Task" />. </returns>
+        private async Task RunWithOptionsAsync(object options, CancellationToken cancellationToken)
         {
+            // Check for cancellation before proceeding
+            cancellationToken.ThrowIfCancellationRequested();
+
             // To support scoped services, create a scope for each command call/run.
             var scopeFactory = this.Services.GetRequiredService<IServiceScopeFactory>();
             await using var scope = scopeFactory.CreateAsyncScope();
@@ -104,9 +148,16 @@ private async Task RunWithOptionsAsync(object options)
 
             // Resolve the command from the service provider by the determined type and invoke the entry point method (RunAsync)
             var command = scope.ServiceProvider.GetRequiredService(commandType);
-            if (commandEntryPointMethodInfo?.Invoke(command, new[] { options }) is Task commandRunTask)
+            if (commandEntryPointMethodInfo != null)
             {
-                await commandRunTask;
+                // Prepare the parameters, including the cancellation token
+                var parameters = new[] { options, cancellationToken };
+
+                // Invoke the command's RunAsync method with the cancellation token
+                if (commandEntryPointMethodInfo.Invoke(command, parameters) is Task commandRunTask)
+                {
+                    await commandRunTask;
+                }
             }
         }
     }
diff --git a/README.md b/README.md
@@ -8,6 +8,10 @@ To help you kickstart your console application, we've provided a a [sample appli
 
 # Guides
 
+## Migrate from V3 to V4
+
+To support cancellation tokens, the `IDotNetConsoleCommand` interface had to be changed: The `RunAsync` method now requires also a `CancellationToken` as a parameter. This change is breaking, so you will need to update your commands to reflect this change.
+
 ## Migrate from V2 to V3
 
 In .NET 6 the hosting model for ASP.NET Core applications was changed, we adjusted to that to fulfill the primary goal of this package: to provide a seamless and intuitive user experience. This introduces breaking changes that are explained below.

Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,7 @@ public EchoCommand(ILogger<EchoCommand> logger, IHostEnvironment environment, IC`
`41`	`41`	`}`
`42`	`42`
`43`	`43`	`/// <inheritdoc />`
`44`		`- public Task RunAsync(EchoOptions options)`
	`44`	`+ public Task RunAsync(EchoOptions options, CancellationToken cancellationToken)`
`45`	`45`	`{`
`46`	`46`	`ArgumentNullException.ThrowIfNull(options);`
`47`	`47`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ public GuidGenCommand(ILogger<GuidGenCommand> logger)`
`26`	`26`	`}`
`27`	`27`
`28`	`28`	`/// <inheritdoc />`
`29`		`- public Task RunAsync(GuidGenOptions options)`
	`29`	`+ public Task RunAsync(GuidGenOptions options, CancellationToken cancellationToken)`
`30`	`30`	`{`
`31`	`31`	`if (options == null)`
`32`	`32`	`{`
`@@ -42,6 +42,7 @@ public Task RunAsync(GuidGenOptions options)`
`42`	`42`	`}`
`43`	`43`
`44`	`44`	`System.Console.WriteLine(result);`
	`45`	`+`
`45`	`46`	`this.logger.LogTrace("Wrote result to console");`
`46`	`47`	`return Task.CompletedTask;`
`47`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -32,10 +32,10 @@ public StartCommand(ILogger<StartCommand> logger, IHttpClientFactory httpClientF`
`32`	`32`	`}`
`33`	`33`
`34`	`34`	`/// <inheritdoc />`
`35`		`- public async Task RunAsync(StartOptions options)`
	`35`	`+ public async Task RunAsync(StartOptions options, CancellationToken cancellationToken)`
`36`	`36`	`{`
`37`	`37`	`this.logger.LogDebug("Check if Google is online");`
`38`		`- var response = await this.httpClient.GetAsync(new Uri("https://www.google.com"));`
	`38`	`+ var response = await this.httpClient.GetAsync(new Uri("https://www.google.com"), cancellationToken);`
`39`	`39`	`if (response.IsSuccessStatusCode)`
`40`	`40`	`{`
`41`	`41`	`this.logger.LogTrace("Internet connection is available");`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`namespace Neolution.DotNet.Console.UnitTests.Fakes`
`2`	`2`	`{`
	`3`	`+ using System.Threading;`
`3`	`4`	`using System.Threading.Tasks;`
`4`	`5`	`using Microsoft.Extensions.Hosting;`
`5`	`6`	`using Neolution.DotNet.Console.Abstractions;`
`@@ -33,7 +34,7 @@ public DefaultCommand(IUnitTestLogger logger, IHostEnvironment environment)`
`33`	`34`	`}`
`34`	`35`
`35`	`36`	`/// <inheritdoc />`
`36`		`- public async Task RunAsync(DefaultOptions options)`
	`37`	`+ public async Task RunAsync(DefaultOptions options, CancellationToken cancellationToken)`
`37`	`38`	`{`
`38`	`39`	`this.logger.Log("options", options);`
`39`	`40`	`this.logger.Log("environment", this.environment);`