Skip to content

SAIF.NetCore.ServiceExtensions operations and processes

This page catalogs the composition-root operations performed by this library: DI registration extension methods, startup-class pipeline configuration, cross-cutting middleware, and small helper surfaces.

Operation catalog

ID Operation Summary Rules
OP-01 Register environment client Registers the non-secure IEnvironmentClient and supporting services; secure settings are unavailable. BR-SE-01, BR-SE-02
OP-02 Register secure environment client Registers the secure IEnvironmentClient and a hash service keyed on the caller's assembly. BR-SE-03
OP-03 Register DB connection client Lazily constructs IDBConnectionClient and bootstraps its credentials from a secure, hash-gated setting. BR-SE-04, BR-SE-05, BR-SE-01
OP-04 Register Edge API auth services Registers JWT-bearer-only authentication for external/Edge APIs. BR-SE-06
OP-05 Register Core API auth services Registers the dual JWT/Windows authentication policy and SecurityApi authorization for internal/Core APIs. BR-SE-07, BR-SE-08
OP-06 Require authenticated user Opt-in global MVC filter requiring authentication on every action. BR-SE-09
OP-07 Register OIDC services Registers OIDC middleware/services and delegates to web authentication setup. BR-SE-10, BR-SE-11
OP-08 Add web authentication Configures Cookie/OpenIdConnect authentication schemes for web applications. BR-SE-11
OP-09 Register for Windows service Composes environment client, logging, error handling, and DB connectivity for Windows services. BR-SE-03, BR-SE-04
OP-10 Register logging and error handler Registers logging, the single IErrorHandler, and error-handling middleware/hooks. BR-SE-12
OP-11 Dynamic error handler invocation Request-pipeline exception handling: maps exceptions to HTTP responses and runs error hooks. BR-SE-12, BR-SE-13, BR-SE-14
OP-12 Debug request handler invocation Logs every request at Debug level with request details. BR-SE-15
OP-13 Legacy cookie gate middleware Presence-only legacy session/auth cookie checks that redirect but never block the pipeline. BR-SE-16
OP-14 App startup configure services AppStartup.ConfigureServices: selects the web-app auth stack and composes session/logging/MVC. BR-SE-03, BR-SE-16, BR-SE-17, BR-SE-18
OP-15 App startup configure pipeline AppStartup.Configure: assembles the HTTP request pipeline for web applications. BR-SE-13, BR-SE-10, BR-SE-17, BR-SE-19
OP-16 Core and Edge API startup CoreAPIStartup/EdgeAPIStartup: composes and pipelines internal and external API hosts. BR-SE-01, BR-SE-03, BR-SE-04, BR-SE-06, BR-SE-07, BR-SE-19
OP-17 OIDC MVC and Razor startup OidcMvcStartup/OidcRazorStartup: adds MVC or Razor Pages support on top of AppStartup. —
OP-18 Console host bootstrap IHostBuilderExtensions/ConsoleBase/ConsoleAsyncBase: composes and runs console applications. BR-SE-20, BR-SE-03, BR-SE-04, BR-SE-21
OP-19 Configure OpenTelemetry Composes opt-in OpenTelemetry logging, metrics, and tracing. BR-SE-22, BR-SE-23, BR-SE-24
OP-20 Configuration helpers IConfigurationExtensions: required/optional configuration-value reads with key validation. BR-SE-25
OP-21 Controller throw helpers ControllerBaseExtensions: converts error conditions to typed HTTP error responses. BR-SE-13, BR-SE-26
OP-22 JWT controller claim helpers JwtControllerBase: derives username and authentication time from JWT claims. BR-SE-27
OP-23 Windows service error-handler helpers IWindowsServiceErrorHandlerExtensions: fluent registration of special error actions and shutdown exemptions. —

Process flow diagram

The diagram below shows the composition-time decision points that route each application shape (web UI, API, console, Windows service) through the matching registration and startup operations catalogued above.

flowchart TD
    A[Application composition root] --> B{Application shape}
    B -->|Web UI| C[AppStartup / OidcMvcStartup / OidcRazorStartup]
    B -->|Internal API| D[CoreAPIStartup]
    B -->|External API| E[EdgeAPIStartup]
    B -->|Minimal console| F1["IHostBuilderExtensions.BuildConsoleApp:<br>config + logging + IHostedService only"]
    B -->|SAIF console| F2["IHostBuilderExtensions.BuildSaifConsoleApp:<br>calls BuildConsoleApp, then adds registrations below"]
    B -->|Windows service| G["RegisterForWindowsService: support-service<br>registrations only (no host/IHostedService wired here)"]
    C --> H[Register environment/secure environment client]
    D --> H
    E --> H
    G --> H
    F2 --> H
    F2 --> H2["RegisterDBConnectionClient + ConsoleLogService"]
    C --> I[Register auth services]
    D --> I
    E --> I
    H --> J[Register logging and error handler]
    I --> J
    J --> K{Hosting model builds an HTTP pipeline?}
    K -->|Yes: Web UI, Internal API, External API| L{Which Configure method?}
    L -->|AppStartup| M1["AppStartup.Configure: buffering, optional<br>session gate, error handler, debug handler,<br>then UseAuthentication (inline, not ConfigureMiddleware)"]
    L -->|Core/Edge| M2["BaseApiStartup.ConfigureMiddleware:<br>buffering, error handler, debug handler"]
    M1 --> N[UseAuthentication / UseAuthorization]
    M2 --> N
    K -->|No: Minimal console, SAIF console| O1["Generic Host runs TConsole as the<br>registered IHostedService (no Configure/<br>IApplicationBuilder step)"]
    K -->|No: Windows service| O2["This library registers no host/IHostedService for<br>Windows service; hosting is the consuming<br>application's own responsibility"]
    C --> P{EnableSessionMiddleware set?}
    P -->|Yes, AppStartup only| Q["AspNetSessionIdMiddleware wired via<br>UseSession + UseMiddleware (fail-open gate)"]
    P -->|No| R[No session gate wired]
    Q --> M1
    R --> M1
    C --> S["LegacyBolAuthMiddleware: registered in DI when<br>EnableLegacyBolAuthMiddleware is set, but never<br>wired via UseMiddleware (dead code)"]
    J --> T["Optional: Configure OpenTelemetry"]

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/IServiceCollectionExtensions.cs
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/Middleware/DynamicErrorHandler.cs, DebugRequestHandler.cs, LegacyBolAuthMiddleware.cs, AspNetSessionIdMiddleware.cs
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/Startup/AppStartup.cs, CoreAPIStartup.cs, EdgeAPIStartup.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
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IConfigurationExtensions.cs
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/ControllerBaseExtensions.cs
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/JwtControllerBase.cs
  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IWindowsServiceErrorHandlerExtensions.cs