CLI Command RunAsync support passing in/propagating a CancelationToken

Is your feature request related to a problem? Please describe. By convention in DotNet Core one wild supply a CancellationToken into an Async method when awaited!

Describe the solution you’d like Support passing in a CancelationToken such that is propagated to the AsyncCommand.ExecuteAsync and for that matter provide a ValidateAsync that also takes the token.

In this way a command handler can detect it’s being canceled (via async Main for example)

Describe alternatives you’ve considered

One can make the organ available via static and class scoped but its not very well encapsulated.

Additional context N/A

[Cryptoc1]

I recently encountered the need to support cancellation in my CLI, and wanted to share my solution/workaround.

In my case, SIGINT/SIGTERM would terminate the cli process, but some background work would continue running. The API managing this background work supported passing a CancellationToken, so my solution consist of a abstract implementation of AsyncCommand that uses a CancellationTokenSource to encapsulate the System.Console.CancelKeyPress and AppDomain.CurrentDomain.ProcessExit events:

using Spectre.Console.Cli;

namespace Cli;

public abstract class CancellableAsyncCommand : AsyncCommand
{
    public abstract Task<int> ExecuteAsync( CommandContext context, CancellationToken cancellation );

    public sealed override async Task<int> ExecuteAsync( CommandContext context )
    {
        using var cancellationSource = new CancellationTokenSource();

        System.Console.CancelKeyPress += onCancelKeyPress;
        AppDomain.CurrentDomain.ProcessExit += onProcessExit;

        using var _ = cancellationSource.Token.Register(
            ( ) =>
            {
                AppDomain.CurrentDomain.ProcessExit -= onProcessExit;
                System.Console.CancelKeyPress -= onCancelKeyPress;
            }
        );

        var cancellable = ExecuteAsync( context, cancellationSource.Token );
        return await cancellable;

        void onCancelKeyPress( object? sender, ConsoleCancelEventArgs e )
        {
            // NOTE: cancel event, don't terminate the process
            e.Cancel = true;

            cancellationSource.Cancel();
        }

        void onProcessExit( object? sender, EventArgs e )
        {
            if( cancellationSource.IsCancellationRequested )
            {
                // NOTE: SIGINT (cancel key was pressed, this shouldn't ever actually hit however, as we remove the event handler upon cancellation of the `cancellationSource`)
                return;
            }

            cancellationSource.Cancel();
        }
    }
}

When targeting NETCOREAPP directly a PosixSignalRegistration, as @Simonl9l suggests, makes for a simpler implementation:

using System.Runtime.InteropServices;
using Spectre.Console.Cli;

namespace Cli;

public abstract class CancellableAsyncCommand : AsyncCommand
{
    public abstract Task<int> ExecuteAsync( CommandContext context, CancellationToken cancellation );

    public sealed override async Task<int> ExecuteAsync( CommandContext context )
    {
        using var cancellationSource = new CancellationTokenSource();

        using var sigInt = PosixSignalRegistration.Create( PosixSignal.SIGINT, onSignal );
        using var sigQuit = PosixSignalRegistration.Create( PosixSignal.SIGQUIT, onSignal );
        using var sigTerm = PosixSignalRegistration.Create( PosixSignal.SIGTERM, onSignal );

        var cancellable = ExecuteAsync( context, cancellationSource.Token );
        return await cancellable;

        void onSignal( PosixSignalContext context )
        {
            context.Cancel = true;
            cancellationSource.Cancel();
        }
    }
}

With this approach, commands inherit from CancellableAsyncCommand, rather than AsyncCommand, and no changes should be needed to the Program.cs:

using Microsoft.Extensions.DependencyInjection;
using Spectre.Console.Cli;

var services = new ServiceCollection()
    .AddCliServices();

var registrar = new TypeRegistrar( services );
var app = new CommandApp<DefaultCommand>( registrar );

app.Configure(
    config =>
    {
#if DEBUG
        config.PropagateExceptions();
        config.ValidateExamples();
#endif
    }
);

return await app.RunAsync( args );

public class DefaultCommand : CancellableAsyncCommand
{
    public async Task<int> ExecuteAsync( CommandContext context, CancellationToken cancellation )
    {
        await DoWorkInThreads( cancellation );

        // ...
        return 0;
    } 
}

References:

• Rainer Stropek, Graceful Shutdown C# Apps
• .NET Generic Host Source Code, ConsoleLifetime.netcoreapp.cs
• .NET Generic Host Source Code, ConsoleLifetime.notnetcoreapp.cs

P.S. I’ve just started using Spectre after using natemcmaster/CommandLineUtils for a while, and playing around with dotnet/command-line-api a bit; I think I’m in love… ✌🏻❤️

[alvpickmans]

@Cryptoc1 nice workaround, it feels it would be a nice and simple addition to the library (yet I’m sure it has some implications)

I’ve decouple the cancellation token source from the abstract command implementation so it can be used on both AsyncCommand and AsyncCommand<TSettings>, but otherwise pretty nice solution for now!

internal sealed class ConsoleAppCancellationTokenSource 
{
    private readonly CancellationTokenSource _cts = new();

    public CancellationToken Token => _cts.Token;

    public ConsoleAppCancellationTokenSource()
    {
        System.Console.CancelKeyPress += OnCancelKeyPress;
        AppDomain.CurrentDomain.ProcessExit += OnProcessExit;

        using var _ = _cts.Token.Register(
            () =>
            {
                AppDomain.CurrentDomain.ProcessExit -= OnProcessExit;
                System.Console.CancelKeyPress -= OnCancelKeyPress;
            }
        );
    }

    private void OnCancelKeyPress(object? sender, ConsoleCancelEventArgs e)
    {
        // NOTE: cancel event, don't terminate the process
        e.Cancel = true;

        _cts.Cancel();
    }

    private void OnProcessExit(object? sender, EventArgs e)
    {
        if (_cts.IsCancellationRequested)
        {
            // NOTE: SIGINT (cancel key was pressed, this shouldn't ever actually hit however, as we remove the event handler upon cancellation of the `cancellationSource`)
            return;
        }

        _cts.Cancel();
    }
}

public abstract class CancellableAsyncCommand : AsyncCommand
{
    private readonly ConsoleAppCancellationTokenSource _cancellationTokenSource = new();

    public abstract Task<int> ExecuteAsync(CommandContext context, CancellationToken cancellation);

    public sealed override async Task<int> ExecuteAsync(CommandContext context)
        => await ExecuteAsync(context, _cancellationTokenSource.Token);

}

public abstract class CancellableAsyncCommand<TSettings> : AsyncCommand<TSettings>
    where TSettings : CommandSettings
{
    private readonly ConsoleAppCancellationTokenSource _cancellationTokenSource = new();

    public abstract Task<int> ExecuteAsync(CommandContext context, TSettings settings, CancellationToken cancellation);

    public sealed override async Task<int> ExecuteAsync(CommandContext context, TSettings settings)
        => await ExecuteAsync(context, settings, _cancellationTokenSource.Token);
}