Skip to content

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.

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