---
title: SAIF.NetCore.WindowsService overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.WindowsService
reference_type: package
---

# 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](service-registration.md) 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.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Service registration](service-registration.md)
- [API reference](api/index.md)

## 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`