CasCap.Common.Services 5.2.0

CasCap.Common.Services

Run selected .NET background features by name, observe their lifecycle and expose assembly-backed application metadata.

Installation

dotnet add package CasCap.Common.Services

Target frameworks: net10.0, net11.0

Usage

Register implementations as IBgFeature, then supply the enabled names to the launcher:

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using CasCap.Common.Abstractions;
using CasCap.Common.Extensions;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSingleton<IBgFeature, WorkerFeature>();
builder.Services.AddApplicationHostLifecycle(builder.Configuration);
builder.Services.AddFeatureFlagService(
    new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "Worker" });

using var host = builder.Build();
await host.RunAsync();
return host.Services.GetApplicationExitCode();

public sealed class WorkerFeature(ILogger<WorkerFeature> logger) : IBgFeature
{
    public string FeatureName => "Worker";

    public async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            if (logger.IsEnabled(LogLevel.Debug))
                logger.LogDebug("{ClassName} poll completed", nameof(WorkerFeature));
            await Task.Delay(TimeSpan.FromMinutes(1), cancellationToken);
        }
    }
}

Feature matching is case-insensitive. A feature named IBgFeature.AlwaysEnabled ("All") runs regardless of the selected set. Registration supplies IOptions<FeatureFlagConfig>; it does not automatically read an EnabledFeatures JSON section.

AddApplicationHostLifecycle binds CasCap:HostLifecycleConfig, configures HostOptions.ShutdownTimeout, and registers ApplicationExitState:

{
  "CasCap": {
    "HostLifecycleConfig": {
      "ShutdownTimeoutMs": 30000
    }
  }
}

Set the Kubernetes terminationGracePeriodSeconds longer than this timeout, including any PreStop duration and a safety margin.

UTC Cron Scheduling

CoalescingScheduleRunner in CasCap.Common.Services accepts a parsed Cronos expression, an injected TimeProvider, an awaited callback and a cancellation token. Five-field expressions use minute precision; seconds require explicit CronFormat.IncludeSeconds.

await CoalescingScheduleRunner.RunAsync(
    Cronos.CronExpression.Parse("0 * * * *"),
    TimeProvider.System,
    async (scheduledForUtc, token) => await RunJobAsync(scheduledForUtc, token),
    stoppingToken);

Occurrences are strictly after the cursor and use UTC. Each schedule runs sequentially; after completion, missed occurrences are coalesced rather than replayed. Startup/manual execution, distributed ownership, durable requests, retries and idempotency belong to the consumer. Cancellation stops pending delays and is passed into callbacks; callback failures propagate. RunWithTimeoutAsync cancels a cooperative operation and awaits its cleanup before reporting a timeout. It does not forcibly abandon work that ignores cancellation.

Feature Supervision Activity

• No matching features is a startup failure.
• A child may finish while siblings continue. Faults from enabled children propagate to the host.
• If all children finish before cancellation, the launcher reports an unexpected lifecycle failure.
• A finite job must request IHostApplicationLifetime.StopApplication() before returning.
• Host cancellation cancels and awaits outstanding features, including their cleanup.
• A child fault requests host shutdown immediately, then cancels and awaits its siblings before propagating the failure.
• A child fault marks ApplicationExitState as failed before requesting shutdown. On .NET 10, the process entry point returns GetApplicationExitCode() after RunAsync to report a nonzero result.
• On .NET 11 with BackgroundServiceExceptionBehavior.StopHost, Host.StopAsync and RunAsync rethrow background failures after cleanup. Preserve that failure at the process boundary rather than suppressing it; the exit state remains available for custom exception-handling entry points.
• AddFeatureFlagService registers the exit state automatically. Call AddApplicationExitState() directly in hosts that also need to report startup or non-feature outcomes through the same process boundary.
• A directly registered BackgroundService outside FeatureFlagBgService must mark the same state before requesting fatal shutdown, or use another supervisor that does.
• Align host and container termination budgets for uncooperative cleanup.

flowchart TD
    HOST["Host startup"] --> MATCH["Match registered features against enabled names"]
    MATCH --> RUN["Run matching features and All features"]
    RUN --> WATCH["Observe child tasks"]
    WATCH -->|Child finishes, siblings remain| WATCH
    WATCH -->|Child faults or all finish without stopping| FAIL["Request host shutdown, cancel and await siblings, propagate failure"]
    WATCH -->|Host cancellation or requested stop| STOP["Cancel and await children, then clean shutdown"]

Configuration Examples

Feature Execution Only

The registration in Usage enables the selected features without periodic metadata logging.

Feature Execution with Metadata

Pass addApplicationMetadataService: true to register ApplicationMetadataBgService and ApplicationMetadata. The latter reads version, source revision and build context from assembly attributes, not live Git state.

builder.Services.AddFeatureFlagService(enabledFeatures, addApplicationMetadataService: true);

The optional metadata service binds ApplicationMetadataConfig. It writes one Information line with the repository, version, branch and commit at startup and then every LogInterval, which defaults to fifteen minutes and must be positive:

{
  "ApplicationMetadataConfig": {
    "LogInterval": "01:00:00"
  }
}