Skip to content

SAIF.NetCore.WindowsService overview

Documentation context: Distributed as a NuGet package.

SAIF.NetCore.WindowsService is a small hosting skeleton for building SAIF Windows Services on the .NET Generic Host: a program-runner base class that builds and runs the host, and a timed background-worker base class that repeatedly runs a consumer-supplied task and applies a fail-stop error policy.

Purpose

  • Let a consumer stand up a Windows Service with three roles: a Program (ServiceProgramRunnerBase, hosting and composition), a Service Worker (ServiceWorker<T>, the recurring loop), and a Service Task Runner (the consumer's own IServiceTaskRunner implementation carrying the business logic).
  • Apply a uniform, fail-stop error policy: every exception from the task runner is reported through IWindowsServiceErrorHandler and, unless explicitly exempt, stops the whole host.
  • Define the configuration-source stack (appsettings.json plus environment variables, re-added after the Generic Host defaults) and an optional startup delay (DelayStart) for every service built on this library.

Responsibilities

  • Build, delay-start, and run the Generic Host (ServiceProgramRunnerBase.Run/Create/CreateHostBuilder), including UseWindowsService() so the same executable runs as a console app outside the SCM.
  • Run a consumer's IServiceTaskRunner on a fixed-delay loop (ServiceWorker<T>.ExecuteAsync), catching every exception and deciding, via ShutdownExemptExceptionType entries on the resolved IWindowsServiceErrorHandler, whether to continue or stop the host.
  • Configure the SAIF logger (ISaifWindowsServiceLogService.Configure) at startup, using the IEnvironmentClient/IHttpJsonClient resolved from the DI container.

Key components

  • ServiceProgramRunnerBase (SAIF.NetCore.WindowsService): the consumer's Program base class — owns host creation, the startup delay, and the error-handler/logger configuration hooks; holds the process-global static ServiceHost.
  • ServiceWorker<T> (SAIF.NetCore.WindowsService, where T : IServiceTaskRunner): a BackgroundService subclass that runs T.Run(stoppingToken) on a fixed-delay loop and applies the fail-stop error policy.

This library takes no NuGet dependency on any other SAIF implementation library — only on the foundation-layer SAIF.NetCore.ServiceContracts — and ships no DI registration extension method of its own; see Service registration for the recommended companion SAIF.NetCore.ServiceExtensions.RegisterForWindowsService call, which satisfies the four services ServiceWorker<T>/ServiceProgramRunnerBase resolve from the container. It is not the only way to satisfy them: an equivalent set of manual registrations for IWindowsServiceErrorHandler, ISaifWindowsServiceLogService, IEnvironmentClient, and IHttpJsonClient works just as well, since ServiceProgramRunnerBase only calls GetRequiredService for those contracts and neither calls nor checks for RegisterForWindowsService itself.

Sources

  • src/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService.csproj
  • src/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/ServiceProgramRunnerBase.cs
  • src/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/ServiceWorker.cs