Class HostBuilderExtensions

Provides extension methods for IHostBuilder to facilitate the integration of Spectre.Console's CommandApp into the application's host builder.

Inheritance

object

HostBuilderExtensions

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 HostBuilderExtensions

Methods

UseSpectreConsole(IHostBuilder, Action<IConfigurator>, bool)

Configures the application's host builder to use Spectre.Console's Spectre.Console.Cli.CommandApp and related services. This setup enables the application to utilize Spectre.Console's command line interface tools, allowing for the definition, parsing, and execution of commands within a .NET Core application.

Declaration

public static IHostBuilder UseSpectreConsole(this IHostBuilder builder, Action<IConfigurator> configureCommandApp, bool suppressLifeTimeStatusMessages = true)

Parameters

Type	Name	Description
IHostBuilder	builder	The IHostBuilder to configure.
Action<IConfigurator>	configureCommandApp	An Action<T> delegate that configures the Spectre.Console.Cli.CommandApp.
bool	suppressLifeTimeStatusMessages	Supresses default output of the application host.

Returns

Type	Description
IHostBuilder	The IHostBuilder so that additional configuration calls can be chained.

Remarks

This method performs the following operations:

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

static async Task Main(string[] args)
{
    var builder = Host.CreateDefaultBuilder(args);
    builder.ConfigureServices(services =>
    {
        services.AddSingleton<ISomeServiceDependency, SomeServiceDependency>();
        services.AddHostedService<SomeOtherBackgroundService>();
    });
    builder.UseSpectreConsole(configCommandApp =>
    {
        configCommandApp.SetApplicationName("testapp");
        configCommandApp.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)
    {
        try { await dependencyService.PerformConsoleAction(appLifetime.ApplicationStopping); }
        catch (Exception) { return (int)SpectreConsoleHostedService.ExitCode.CommandTerminated; }
        return (int)SpectreConsoleHostedService.ExitCode.SuccessAndContinue;
    }
}

Exceptions

Type	Condition
ArgumentNullException	Thrown if builder is null.

UseSpectreConsoleSyncCommandExecutor(IHostBuilder, Action<IConfigurator>, bool)

Sets up a command execution environment within the application's host configuration, where commands are executed synchronously. This method creates an entry point for a command-line application that supports multiple commands, each running in a synchronous manner within its own task context. In the event of a service cancellation, the currently executing command will be terminated abruptly.

Declaration

public static IHostBuilder UseSpectreConsoleSyncCommandExecutor(this IHostBuilder builder, Action<IConfigurator> configureCommandApp, bool suppressLifeTimeStatusMessages = true)

Parameters

Type	Name	Description
IHostBuilder	builder	The host builder to configure, which is augmented with services and configurations necessary for managing command execution.
Action<IConfigurator>	configureCommandApp	A delegate that configures the command-line application, facilitating the registration and setup of individual commands.
bool	suppressLifeTimeStatusMessages	Optional. Determines whether to suppress host lifetime status messages, with a default value of true. When set to false, these messages are made visible, offering insights into the lifecycle events of the host.

Returns

Type	Description
IHostBuilder	The host builder, now configured with the synchronous command execution environment, ready for further configuration or immediate use.

Remarks

static async Task Main(string[] args)
{
    var builder = Host.CreateDefaultBuilder(args);
    builder.ConfigureServices(services =>
    {
        services.AddSingleton<ISomeServiceDependency, SomeServiceDependency>();
        services.AddHostedService<SomeOtherBackgroundService>();
    });
    builder.UseSpectreConsoleSyncCommandExecutor(configCommandApp =>
    {
        configCommandApp.SetApplicationName("testapp");
        configCommandApp.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;
}

}

Exceptions

Type	Condition
ArgumentNullException	Thrown if the provided host builder is null, ensuring method reliability and preventing null reference errors.