Provide better example, explanation, and documentation on how and when to use the newer CancellationToken feature

[lochnessopensource]

A while back, cancellation token support was requested here: spectreconsole/spectre.console#701
and was eventually added as a feature in Spectre. Unfortunately, the documentation provides no guidance or examples on how and when to properly use this new feature.

@0xced or @patriksvensson, are you able to clarify this in the GitHub issue? It would be great if someone could implement an update to the documentation with this information.

---

Please upvote 👍 this issue if you are interested in it.

[0xced]

You're right, the documentation still needs to be updated.

Here's the very short version.

using System;
using System.Threading;
using Spectre.Console.Cli;

var cancellationTokenSource = new CancellationTokenSource();
// 👇 wire up the cancellation token source to Ctrl+C
Console.CancelKeyPress += (_, _) => cancellationTokenSource.Cancel();

var app = new CommandApp();
app.Configure(c =>
{
    // configure your application here
});
// 👇 pass the cancellation token to the RunAsync method
return await app.RunAsync(args, cancellationTokenSource.Token);

Then the cancellation token that triggers when Ctrl+C is pressed is automatically passed down to the commands in the Execute or ExecuteAsync method.

[0xced]

Async Commands and Cancellation now explains how to properly use the new top-level cancellation feature.