hosting library

Provides classes for managing application lifetime, hosting background services, and coordinating application startup/shutdown.

This library implements hosting abstractions inspired by Microsoft.Extensions.Hosting, enabling structured application lifecycle management with dependency injection integration.

Basic Application Host

Create and run a hosted application:

Future<void> main(List<String> args) async => Host.createDefaultBuilder()
    .configureServices(
      (_, services) => services.addHostedService<ExampleHostedService>(
        (services) => ExampleHostedService(
          services
              .getRequiredService<LoggerFactory>()
              .createLogger('ExampleHostedService'),
          services.getRequiredService<HostApplicationLifetime>(),
        ),
      ),
    )
    .useConsoleLifetime(null)
    .build()
    .run();

Background Services

Run long-lived background tasks by overriding BackgroundService.execute:

final class MyBackgroundService extends BackgroundService {
  @override
  Future<void> execute(CancellationToken stoppingToken) async {
    print('--- Service Work ---');
    print('Background service is running once and then exiting.');
  }
}

Register it like any other hosted service:

await createDefaultBuilder(args)
    .configureServices((context, services) {
      services.addHostedService<MyBackgroundService>(
        (services) => MyBackgroundService(),
      );
    })
    .useConsoleLifetime()
    .build()
    .run();

Application Lifetime

React to application lifecycle events:

class ExampleHostedService extends HostedService {
  final Logger _logger;

  ExampleHostedService(
    Logger logger,
    HostApplicationLifetime lifetime,
  ) : _logger = logger {
    lifetime
      ..applicationStarted.register((_) => _onStarted())
      ..applicationStopping.register((_) => _onStopping())
      ..applicationStopped.register((_) => _onStopped());
  }

  @override
  Future<void> start(CancellationToken cancellationToken) async {
    _logger.logInformation('=== Host Lifecycle Example ===');
    _logger.logInformation('1. `start` has been called.');
    return;
  }

  @override
  Future<void> stop(CancellationToken cancellationToken) async {
    _logger.logInformation('4. `stop` has been called.');
    return;
  }

  void _onStarted() {
    _logger.logInformation('2. `applicationStarted` callback ran.');
  }

  void _onStopping() {
    _logger.logInformation('3. `applicationStopping` callback ran.');
  }

  void _onStopped() {
    _logger.logInformation('5. `applicationStopped` callback ran.');
  }
}

Host Configuration

Build and start a host directly when the console lifetime is not needed:

final hostBuilder = Host.createApplicationBuilder();
// ..logging.addDebug()
// ..logging.setMinimumLevel(LogLevel.trace);

print('--- Start Host ---');
final host = hostBuilder.build()..start();

Classes

ApplicationLifetime

Allows consumers to perform cleanup during a graceful shutdown.

BackgroundService

Base class for implementing a long running HostedService.

DefaultHostApplicationBuilder

Represents a hosted applications and services builder that helps manage configuration, logging, lifetime, and more.

DefaultHostBuilder

DefaultServiceFactoryAdapter<TContainerBuilder>

Environments

Commonly used environment names.

Host

A program abstraction.

HostApplicationBuilder

Represents a hosted applications and services builder which helps manage configuration, logging, lifetime, and more.

HostApplicationBuilderSettings

Settings for constructing an HostApplicationBuilder.

HostApplicationLifetime

Allows consumers to be notified of application lifetime events. This interface is not intended to be user-replaceable.

HostBuilder

A program initialization abstraction.

HostBuilderAdapter

HostBuilderContext

Context containing the common services on the Host. Some properties may be null until set by the Host.

HostDefaults

Constants for HostBuilder configuration keys.

HostedService

Defines methods for objects that are managed by the host.

HostEnvironment

Provides information about the hosting environment an application is running in.

HostingEnvironment

HostLifetime

Tracks host lifetime.

ServiceFactoryAdapter

Extensions

HostEnvironmentEnvExtensions on HostEnvironment

Extension methods for HostEnvironment.

HostingAbstractionsHostBuilderExtensions on HostBuilder

Provides extension methods for the HostBuilder from the hosting abstractions package.

HostingAbstractionsHostExtensions on Host

HostingHostBuilderExtensions on HostBuilder

Provides extension methods for the HostBuilder from the hosting package.

OptionsBuilderExtensions on OptionsBuilder<TOptions>

ServiceCollectionHostedServiceExtensions on ServiceCollection

Extension methods for adding hosted services to a ServiceCollection.

Functions

createApplicationBuilder({HostApplicationBuilderSettings? settings}) → HostApplicationBuilder

createDefaultBuilder([List<String>? args]) → HostBuilder

Initializes a new instance of the HostBuilder class with pre-configured defaults.

Typedefs

ConfigureAppConfigurationDelegate = void Function(HostBuilderContext context, ConfigurationBuilder configuration)

ConfigureContainer<TContainerBuilder> = void Function(TContainerBuilder containerBuilder)

ConfigureContainerBuilder<TContainerBuilder> = void Function(TContainerBuilder containerBuilder)

ConfigureContainerDelegate<TContainerBuilder> = TContainerBuilder Function(HostBuilderContext context, TContainerBuilder builder)

ConfigureDefaultServiceProvider = void Function(HostBuilderContext context, ServiceProviderOptions options)

ConfigureHostConfigurationDelegate = void Function(ConfigurationBuilder configuration)

ConfigureServicesDelegate = void Function(HostBuilderContext context, ServiceCollection services)

ContextResolver = HostBuilderContext? Function()

CreateServiceProvider = ServiceProvider Function()

FactoryResolver<TContainerBuilder> = ServiceProviderFactory<TContainerBuilder> Function(HostBuilderContext hostContext)

ServiceProviderFactoryDelegate<TContainerBuilder> = ServiceProviderFactory<TContainerBuilder> Function(HostBuilderContext? context)