As an application grows, its Main method collects service registrations, start-up work and clean-up code from every library it uses. The order of those steps starts to matter, and nothing states it. A failure halfway through start-up leaves resources that nobody releases.

Sphere10.Framework.Application gives that work a structure. Each library contributes a module, start-up and shutdown work become small task classes, and one builder runs everything in a defined order. This article shows how to write modules and tasks, how the order is decided, and who owns the service provider.

1. Write a module

A module overrides only what it needs. This one registers a service, one initializer and one finalizer, and logs from its two hooks.

public sealed class StorageModule : ModuleConfigurationBase {
	public override int Priority => 10;

	public override void RegisterComponents(IServiceCollection services) {
		services.AddSingleton<ActivityLog>();
		services.AddInitializer<OpenStorageInitializer>();
		services.AddFinalizer<CloseStorageFinalizer>();
	}

	public override void OnInitialize(IServiceProvider serviceProvider) {
		base.OnInitialize(serviceProvider);
		serviceProvider.GetRequiredService<ActivityLog>().Add("StorageModule.OnInitialize");
	}

	public override void OnFinalize(IServiceProvider serviceProvider) {
		base.OnFinalize(serviceProvider);
		serviceProvider.GetRequiredService<ActivityLog>().Add("StorageModule.OnFinalize");
	}
}

Priority orders modules. A higher value registers, initializes and finalizes earlier, and the default is 0. A module that supplies a default implementation should let the host override it, which HasImplementationFor<T>() makes a one-line test.

public override void RegisterComponents(IServiceCollection services) {
	if (!services.HasImplementationFor<IReportFormatter>())
		services.AddSingleton<IReportFormatter, PlainReportFormatter>();
	services.AddInitializer<LoadTemplatesInitializer>();
}

2. The contracts

classDiagram
    direction TB
    class ICoreModuleConfiguration {
      +Priority
      +OnInitialize(provider)
      +OnFinalize(provider)
    }
    class ModuleConfigurationBase {
      +RegisterComponents(services)
    }
    class IApplicationInitializer {
      +Priority
      +Parallelizable
      +Initialize()
    }
    class IApplicationFinalizer {
      +Finalize()
    }
    ICoreModuleConfiguration <|.. ModuleConfigurationBase
    ModuleConfigurationBase ..> IApplicationInitializer : registers
    ModuleConfigurationBase ..> IApplicationFinalizer : registers

3. Write the tasks

A task derives from the base class for its natural direction and overrides one method. A synchronous task derives from SyncApplicationInitializerBase.

public sealed class OpenStorageInitializer : SyncApplicationInitializerBase {
	private readonly ActivityLog _log;

	public OpenStorageInitializer(ActivityLog log) {
		_log = log;
	}

	public override int Priority => 10;

	public override void Initialize() => _log.Add("OpenStorageInitializer (priority 10)");
}

A task whose work is asynchronous derives from AsyncApplicationInitializerBase and overrides InitializeAsync.

public override async Task InitializeAsync(CancellationToken cancellationToken = default) {
	await Task.Yield();
	_log.Add("LoadTemplatesInitializer (priority 20, async)");
}

Each base supplies the other direction, so the host can call either form. Finalizers follow the same pattern with SyncApplicationFinalizerBase and AsyncApplicationFinalizerBase.

4. Start and end the framework

The host lists its modules explicitly. Nothing is discovered by scanning assemblies.

Sphere10Framework.Instance
	.Build()
	.WithProductInformation(product => {
		product.ProductName = "ArticleSample";
		product.CompanyName = "Example Company";
		product.ProductVersion = new ApplicationVersion { Major = 1 };
	})
	.AddServices(services => {
		services.AddSingleton(new Local<ISettingsProvider>(new CachedSettingsProvider(new DirectoryFileSettingsProvider(Path.Combine(directory, "user")))));
		services.AddSingleton(new Global<ISettingsProvider>(new CachedSettingsProvider(new DirectoryFileSettingsProvider(Path.Combine(directory, "shared")))));
		services.AddSingleton<IReportFormatter, UpperCaseReportFormatter>();
	})
	.AddModule<Sphere10.Framework.Application.ModuleConfiguration>()
	.AddModule<ReportingModule>()
	.AddModule<StorageModule>()
	.Start();

AddServices callbacks run before any module registers, which is why the host's UpperCaseReportFormatter wins over the module's default. The Framework's own ModuleConfiguration supplies product information, settings and usage services. The sample points its settings providers at the sample directory so that nothing is written to the user's profile.

After Start() returns, services are resolved from Sphere10Framework.Instance.ServiceProvider. At shutdown the host calls EndFramework() once.

var services = Sphere10Framework.Instance.ServiceProvider;
var log = services.GetRequiredService<ActivityLog>();
var product = services.GetRequiredService<IProductInformationProvider>().ProductInformation;
log.Add(services.GetRequiredService<IReportFormatter>().Format($"running {product.ProductName}"));

Sphere10Framework.Instance.EndFramework();

5. The order of everything

---
config:
  sequence:
    actorMargin: 8
    width: 96
    mirrorActors: false
    messageMargin: 28
    noteMargin: 8
---
sequenceDiagram
    participant H as Host
    participant F as Framework
    participant M as Modules, tasks
    H->>F: Start()
    F->>M: RegisterComponents
    Note over F: build provider
    F->>M: OnInitialize
    F->>M: initializers
    H->>F: EndFramework()
    F->>M: finalizers
    F->>M: OnFinalize
    Note over F: dispose provider

The sample records each step and checks the result against this table.

StorageModule.OnInitialize
ReportingModule.OnInitialize
OpenStorageInitializer (priority 10)
LoadTemplatesInitializer (priority 20, async)
RUNNING ARTICLESAMPLE
CloseStorageFinalizer
StorageModule.OnFinalize
ReportingModule.OnFinalize
Lifecycle order check: passed

StorageModule was added last and still initializes first, because its priority is 10. An initializer that sets Parallelizable to true runs in a parallel phase after all sequential ones, so keep tasks that depend on each other sequential.

6. Ownership and failure

• Start() builds the service provider and owns it. EndFramework() runs the finalizers and module hooks and then disposes the provider.
• A host that already has a provider, such as ASP.NET Core, calls RegisterModules(services) on the builder and later Start(provider). That provider stays with its host and is not disposed by the framework.
• A failing initializer stops the remaining ones and fails start-up. The framework disposes the provider it built and runs no finalizers, so do not call EndFramework() after a failed start.
• Every finalizer is attempted even when one fails, and the failures are thrown together at the end.

7. Get the package and run the sample

Add the core package and Sphere10.Framework.Application.

dotnet add package Sphere10.Framework
dotnet add package Sphere10.Framework.Application

The complete MIT-licensed sample contains the code shown above.

dotnet run -c Release -- ./fresh-data

The output is the list shown above. The Application guide covers process tasks in full, including the plugin tasks that belong to a running desktop or Blazor application.

The Sphere10 Framework overview describes the rest of the toolkit.

Author: Herman Schoenfeld