Class ServiceCollectionExtensions

Provides extension methods for IServiceCollection to facilitate the integration of Spectre.Console's CommandApp.

Inheritance

object

ServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Coree.NETStandard.SpectreConsole

Assembly: Coree.NETStandard.dll

Syntax

public static class ServiceCollectionExtensions

Methods

| Edit this page View Source

AddSpectreConsole(IServiceCollection, Action<IConfigurator>, bool)

Adds and configures Spectre.Console's Spectre.Console.Cli.CommandApp and related services to the specified IServiceCollection. This setup allows for utilizing Spectre.Console's command line interface tools within a .NET Core application, enabling the definition, parsing, and execution of commands.

Declaration

public static IServiceCollection AddSpectreConsole(this IServiceCollection services, Action<IConfigurator> configureCommandApp, bool suppressLifeTimeStatusMessages = true)

Parameters

Type	Name	Description
IServiceCollection	services	The IServiceCollection to add services to.
Action<IConfigurator>	configureCommandApp	An Action delegate that is used to configure the Spectre.Console.Cli.CommandApp.
bool	suppressLifeTimeStatusMessages	Supresses default output of the application host.

Returns

Type	Description
IServiceCollection	The IServiceCollection so that additional calls can be chained.

Remarks

This method performs the following operations:

Initializes a new instance of Spectre.Console.Cli.CommandApp and configures it using the provided configureCommandApp action.
Scans for command types registered within the Spectre.Console.Cli.CommandApp and registers them as singletons in the service collection.
Registers the Spectre.Console.Cli.CommandApp itself as a singleton service, configured to use a SpectreConsoleTypeRegistrar for dependency injection.
Adds a SpectreConsoleHostedService, to manage the application lifecycle of the Spectre.Console.Cli.CommandApp.

static async Task Main(string[] args)
{
    var builder = Host.CreateDefaultBuilder(args);
    builder.ConfigureServices(services =>
    {
        services.AddSpectreConsole(configCommandApp =>
        {
            configCommandApp.SetApplicationName("testapp");
            configCommandApp.AddCommand<MyAsyncCommand>("my-command");
        });
        services.AddSingleton<ISomeServiceDependency, SomeServiceDependency>();
        services.AddHostedService<SomeOtherBackgroundService>();
    });
    await builder.Build().RunAsync();
}

public class MyAsyncCommand : AsyncCommand<MyAsyncCommand.Settings>
{
    private readonly ISomeServiceDependency dependencyService; private readonly IHostApplicationLifetime appLifetime;

    public MyAsyncCommand(ISomeServiceDependency dependencyService, IHostApplicationLifetime appLifetime)
    {
        this.dependencyService = dependencyService; this.appLifetime = appLifetime;
    }

    public class Settings : CommandSettings
    {
        [Description("The commandline setting")]
        [CommandArgument(0, "<Setting>")]
        public string? SomeSetting { get; init; }
    }

    public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
    {
        try { await dependencyService.PerformConsoleAction(appLifetime.ApplicationStopping); }
        catch (Exception) { return (int)SpectreConsoleHostedService.ExitCode.CommandTerminated; }
        return (int)SpectreConsoleHostedService.ExitCode.SuccessAndContinue;
    }
}

| Edit this page View Source

AddSpectreConsoleSyncCommandExecutor(IServiceCollection, Action<IConfigurator>, bool)

Registers a command execution environment with Spectre.Console integration into the application's service collection. This setup facilitates the execution of command-line commands synchronously within their own task contexts. Designed to support multiple commands, this configuration allows for abrupt termination of commands upon service cancellation, ensuring immediate response to stop requests.

Declaration

public static IServiceCollection AddSpectreConsoleSyncCommandExecutor(this IServiceCollection services, Action<IConfigurator> configureCommandApp, bool suppressLifeTimeStatusMessages = true)

Parameters

Type	Name	Description
IServiceCollection	services	The IServiceCollection to configure, which is augmented with the necessary services and configurations for Spectre.Console command execution.
Action<IConfigurator>	configureCommandApp	A delegate that configures the command-line application, facilitating the registration and setup of individual commands within the Spectre.Console framework.
bool	suppressLifeTimeStatusMessages	Optional. Determines whether to suppress host lifetime status messages, with a default value of true. Setting this to false enables the visibility of these messages, providing insights into the lifecycle events of the host and command execution.

Returns

Type	Description
IServiceCollection	The IServiceCollection, now configured with the Spectre.Console command execution environment, ready for further configuration or immediate use within the application's startup process.

Remarks

Integrating the Spectre.Console command executor into your services collection. Commands are executed synchronously but in a separate task. Note that attempts to abort commands gracefully will face challenges due to their execution in separate tasks, which are not managed by the service host's context.

static async Task Main(string[] args)
{
    var builder = Host.CreateDefaultBuilder(args);
    builder.ConfigureServices(services =>
    {
        services.AddSingleton<ISomeServiceDependency, SomeServiceDependency>();
        services.AddHostedService<SomeOtherBackgroundService>();
        services.AddSpectreConsoleSyncCommandExecutor(configureCommandApp =>
        {
            configureCommandApp.SetApplicationName("toolkit");
            configureCommandApp.AddCommand<MyAsyncCommand>("my-command");
        });
    });
    await builder.Build().RunAsync();
}

public class MyAsyncCommand : AsyncCommand<MyAsyncCommand.Settings>
{
    private readonly ISomeServiceDependency dependencyService;
    private readonly IHostApplicationLifetime appLifetime;

    public MyAsyncCommand(ISomeServiceDependency dependencyService, IHostApplicationLifetime appLifetime)
    {
        this.dependencyService = dependencyService;
        this.appLifetime = appLifetime;
    }

    public class Settings : CommandSettings
    {
        [Description("The commandline setting")]
        [CommandArgument(0, "<Setting>")]
        public string? SomeSetting { get; init; }
    }

    public override async Task<int> ExecuteAsync(CommandContext context, Settings settings)
    {
        // Attempts to abort the command gracefully will fail because the command runs on a separate task and not in the service host's managed context.
        try {
            await dependencyService.PerformConsoleAction(appLifetime.ApplicationStopping);
        }
        catch (Exception)
        {
            // This catch block is unreachable. The service host's abrupt termination of the command prevents this block from being executed.
            return (int)SpectreConsoleHostedService.ExitCode.CommandTerminated;
        }
        // It's crucial to explicitly manage the service host's state after command execution completes, either continuing operation or initiating shutdown.
        return (int)SpectreConsoleHostedService.ExitCode.SuccessAndContinue;
    }
}