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

# SAIF.NetCore.ServiceExtensions overview

> **Documentation context:** Pipeline-packed NuGet package

`SAIF.NetCore.ServiceExtensions` is the top-layer composition root of the repository's three-layer model. It owns no domain logic of its own; instead, it provides `IServiceCollection`/`IApplicationBuilder`/`IWebHostBuilder`/`HostBuilder`/`IHostApplicationBuilder` extension methods, abstract ASP.NET Core startup base classes, console/Windows-service hosting bases, and OpenTelemetry composition helpers that wire together the foundation package (`SAIF.NetCore.ServiceContracts`) and nine implementation-layer packages (ten internal package references in total), so that a consuming application adds a single NuGet package reference to assemble a complete SAIF application.

## Purpose
- Compose dependency-injection registrations, startup base classes, middleware, and observability for SAIF .NET Core applications, so consuming teams do not re-wire auth, environment configuration, DB connectivity, error handling, HTTP clients, logging, OIDC, health/ping, or system hashing by hand in every application.
- Consumed by web UI applications (OIDC login apps), internal/Core APIs, external/Edge APIs, console applications, and Windows services across the repository's SAIF.NetCore.* application family.
- Directly references only 10 of the other 18 libraries in this repository (AuthService, DBConnectionClient, EnvironmentClient, ErrorHandler, HttpClients, Logging, OIDC, PingableService, ServiceContracts, SystemHash); `HashUtil`, `Common`, `Clients.UC4`, `LegacyAuth`, `NHibernate`, `NtlmApiAuth`, `Services.Messaging`, and `WindowsService` are **not** referenced or wired by this library, so the repository-wide `Architecture.md` description of ServiceExtensions pulling in "the full set" of SAIF services is only partially accurate*.

## Responsibilities
- Register the environment-client, DB-connection-client, authentication/authorization, OIDC, logging, and error-handling services implemented by other SAIF packages, through 14 public `IServiceCollection` extension methods.
- Provide three ASP.NET Core startup archetypes that encode the repository's standard application shapes: web UI with OIDC (`AppStartup` → `OidcMvcStartup`/`OidcRazorStartup`), internal/Core API with dual Negotiate+JWT authentication (`CoreAPIStartup`), and external/Edge API with JWT-only authentication (`EdgeAPIStartup`).
- Provide console host-builder configuration (`IHostBuilderExtensions.BuildConsoleApp<TConsole>`/`BuildSaifConsoleApp<TConsole>`) for any `IHostedService` — including, optionally, this library's `ConsoleBase`/`ConsoleAsyncBase` convenience bases — and separate `IServiceCollection` support-service registrations for Windows services (`RegisterForWindowsService<T>`/`RegisterForWindowsService()`) that a consumer adds to an independently-supplied host; the Windows-service methods register support services only and do not build a host or register the consumer's `IHostedService`.
- Supply cross-cutting middleware (`DynamicErrorHandler`, `DebugRequestHandler`, `LegacyBolAuthMiddleware`, `AspNetSessionIdMiddleware`) and MVC controller helpers (`JwtControllerBase`, `ControllerBaseExtensions`) for consistent HTTP error responses and claim reads.
- Compose optional OpenTelemetry logging/metrics/tracing as an opt-in capability that no startup base class invokes automatically*.

## Key components
- `IServiceCollectionExtensions`: the primary composition surface — 14 extension methods registering environment-client, DB-connection-client, auth, OIDC, logging, and error-handling services.
- `AppStartup` / `OidcMvcStartup` / `OidcRazorStartup`: the web UI startup archetype, with authentication branching on the `ASPNETCORE_HOST_LOCATION` environment variable.
- `BaseApiStartup` / `CoreAPIStartup` / `EdgeAPIStartup`: the API startup archetypes for internal (dual-auth) and external (JWT-only) hosts.
- `IHostBuilderExtensions` / `ConsoleBase` / `ConsoleAsyncBase`: the console-hosting composition surface.
- `OpenTelemetryExtensions` / `OpenTelemetryOptions`: the opt-in observability composition boundary.
- `Middleware` namespace (`DynamicErrorHandler`, `DebugRequestHandler`, `AspNetSessionIdMiddleware`, `LegacyBolAuthMiddleware`): cross-cutting request-pipeline behavior defined and registered by this library.
- `ControllerBaseExtensions` / `JwtControllerBase` / `IConfigurationExtensions` / `IWindowsServiceErrorHandlerExtensions`: smaller, self-contained helper surfaces for HTTP error responses, JWT claim reads, configuration-key validation, and Windows-service error-handler setup.

## 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)
- [Security and authorization](security-authorization.md)
- [Service registration](service-registration.md)
- [API reference](api/index.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions.csproj`
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs`
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/Startup/AppStartup.cs`, `CoreAPIStartup.cs`, `EdgeAPIStartup.cs`, `BaseApiStartup.cs`, `OidcMvcStartup.cs`, `OidcRazorStartup.cs`
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IHostBuilderExtensions.cs`, `ConsoleBase.cs`, `ConsoleAsyncBase.cs`
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/OpenTelemetryExtensions.cs`
- `Architecture.md`