AceWorks.Tools 2026.9.11

Ace.Tools

Common utilities and interactive maintenance tooling for .NET applications.

Ace.Tools may be used freely in commercial, personal, and open-source projects under The Unlicense.

Namespaces

Maintenance

Ace.Tools.Maintenance provides an interactive maintenance menu. Actions are discovered from loaded assemblies and resolved through dependency injection.

Maintenance can run in two modes:

• Bootstrap maintenance runs before the application host is built. Use it for self-contained diagnostics that do not require application services.
• Hosted maintenance runs during ordered host startup. It can use the application's dependency injection container and infrastructure started before the maintenance module.

Bootstrap maintenance

Run bootstrap maintenance before building the application host:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

await Startup.RunBootstrapMaintenanceAsync();

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((_, services) =>
    {
        services.AddMemoryCache();
        services.AddHostedService<SomeLongRunningService>();
    })
    .Build();

await host.RunAsync();

Only maintenance actions that also implement IBootstrapMaintenanceAction are available in bootstrap mode.

Bootstrap actions must remain self-contained because the application service provider does not exist yet.

Hosted maintenance

Register the maintenance module before hosted workloads that must wait for maintenance to complete:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((_, services) =>
    {
        // Infrastructure available to maintenance actions.
        services.AddMemoryCache();

        // Maintenance acts as an ordered startup barrier.
        services.AddMaintenanceModule();

        // Active workloads start after maintenance completes.
        services.AddHostedService<SomeLongRunningService>();
    })
    .Build();

await host.RunAsync();

When startup maintenance is enabled, hosted-service registration order is significant:

1. Hosted infrastructure registered before AddMaintenanceModule() starts first.
2. The maintenance module pauses startup and displays the maintenance prompt.
3. If requested, actions run using the application service provider.
4. Hosted services registered after AddMaintenanceModule() start when the maintenance session ends.

This allows maintenance actions to use application infrastructure without starting normal background workloads at the same time.

Hosted-service startup must remain sequential for this ordering guarantee. The maintenance module configures HostOptions.ServicesStartConcurrently accordingly; applications should not override it.

Creating a maintenance action

Apply MaintenanceActionAttribute to a concrete IMaintenanceAction implementation:

[MaintenanceAction("Run Simulation Check 🧪")]
public sealed class SimulationCheck : MaintenanceActionBase
{
    public override async ValueTask RunAsync(MaintenanceContext context, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(context);

        SimulationEngine engine = context.Services.GetRequiredService<SimulationEngine>();
        await engine.RunCheckAsync(ct);
    }
}

MaintenanceContext.Services is scoped to the maintenance session. Use it to resolve scoped application services.

To make an action available during bootstrap maintenance, also implement IBootstrapMaintenanceAction:

[MaintenanceAction("View Embedded Resources 📦🧾")]
public sealed class EmbeddedResourceInventory : MaintenanceActionBase, IBootstrapMaintenanceAction
{
    public override ValueTask RunAsync(MaintenanceContext context, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(context);
        ct.ThrowIfCancellationRequested();

        // Perform the maintenance action.

        return ValueTask.CompletedTask;
    }
}

Bootstrap actions must not depend on services registered by the application host.

Action discovery

Maintenance actions are discovered from assemblies already loaded into the current application domain.

Register assemblies loaded later explicitly:

services.AddMaintenanceActionsFromAssembly(typeof(SimulationCheck).Assembly);

Dynamic assemblies are ignored. Discovered actions are ordered first by their configured action order and then by stable type name.

Action menu grouping

Maintenance actions may be grouped into nested menu folders either explicitly or by namespace.

Explicit menu levels take precedence over namespace-derived grouping. Slash-separated explicit menu levels create nested folders.

Actions without an explicit menu level are grouped from the portion of their namespace below:

.Maintenance.Actions.

For example:

Namespaces that do not contain .Maintenance.Actions. are not forced into an Other folder. They are displayed directly in the root maintenance menu.

If you want an action to appear in an Other folder, place it there explicitly using the action's configured menu level.

So your README would continue from the end like this:

```md
Dynamic assemblies are ignored. Discovered actions are ordered first by their configured action order and then by stable type name.

### Action menu grouping

Maintenance actions may be grouped into nested menu folders either explicitly or by namespace.

Explicit menu levels take precedence over namespace-derived grouping. Slash-separated explicit menu levels create nested folders.

Actions without an explicit menu level are grouped from the portion of their namespace below:

```text
.Maintenance.Actions.

For example:

Namespaces that do not contain .Maintenance.Actions. are not forced into an Other folder. They are displayed directly in the root maintenance menu.

If you want an action to appear in an Other folder, place it there explicitly using the action's configured menu level.