Table of Contents

Introduction

Invex.Extensions.Hosting is a small library of utilities for the .NET generic host. This page explains which gaps it fills, when it is (and is not) the right tool, and the ideas behind its design.

What it is

The generic host and Microsoft.Extensions.DependencyInjection cover most application plumbing, but three everyday tasks still need hand-written boilerplate. This library packages each of them as a single, tested building block:

Feature Problem it solves
Multi-interface registration Registering one implementation under several service types without creating duplicate instances.
Host control Stopping the application gracefully with a specific process exit code.
Cycle background service Running periodic background work on a fixed, drift-free cadence.

When to use it

  • A hosted service also needs to be reachable by the rest of the application, for example a worker that exposes its status to a health endpoint.
  • A component detects a fatal condition and must stop the host so that a supervisor (container orchestrator, Windows service manager, systemd, CI pipeline) sees a failure exit code.
  • A worker polls, flushes or checks something every N milliseconds and the period must not slip as the work takes longer.

When not to use it

  • Calendar or cron scheduling. CycleBackgroundService runs on a fixed interval measured with a monotonic clock; it has no notion of wall-clock times such as "every day at 02:00". Use a job scheduler for that.
  • Concurrent cycles. Cycles never overlap. If independent work items should run in parallel, queue them from the cycle or use a different design.
  • Conditional registrations. The multi-interface overloads append registrations like the framework's AddSingleton and AddScoped; there are no TryAdd variants.

Key concepts at a glance

Concept Type In one sentence
Forwarded registration ServiceCollectionExtensions The implementation is registered once and every listed service type resolves to that same instance.
Host control IHostControl A drop-in superset of IHostApplicationLifetime that adds StopApplication(int exitCode).
Fixed cadence CycleBackgroundService Each cycle is scheduled relative to the previous scheduled start, so work duration never adds drift.

Design principles

  • Tiny surface area. The library exposes exactly four public types. Everything else is internal.
  • No behavioral surprises. All extensions compose the standard Microsoft.Extensions.DependencyInjection and Microsoft.Extensions.Hosting primitives; nothing replaces or intercepts host behavior.
  • Broad compatibility. Targets netstandard2.0 and net10.0, so it works in both legacy applications (including .NET Framework 4.8, via the netstandard2.0 build) and modern ones.
  • Trimming/AOT friendly. In the net10.0 build, implementation type parameters are annotated with [DynamicallyAccessedMembers] so trimming preserves the constructors the DI container needs.
  • Stable public API. The public API surface is locked by snapshot tests (PublicApiTests); any accidental breaking change fails the build.

Versioning and support

The package follows semantic versioning (versions are generated by GitVersion). Breaking changes only occur in major releases.

Next steps

Edit this page