--- title: SAIF.NetCore.ServiceExtensions operations and processes summary: Catalog of operations/processes implemented by this library. status: draft owner: Framework.NCore maintainers last_reviewed: 2026-10-02 library: SAIF.NetCore.ServiceExtensions reference_type: package --- # 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](operations/register-environment-client.md) | Registers the non-secure `IEnvironmentClient` and supporting services; secure settings are unavailable. | [BR-SE-01](business-rules.md#br-se-01-non-secure-environment-clients-cannot-retrieve-secure-settings), [BR-SE-02](business-rules.md#br-se-02-a-null-system-hash-must-not-be-resolved-as-required) | | OP-02 | [Register secure environment client](operations/register-secure-environment-client.md) | Registers the secure `IEnvironmentClient` and a hash service keyed on the caller's assembly. | [BR-SE-03](business-rules.md#br-se-03-secure-mode-system-hash-is-computed-from-the-caller's-assembly) | | OP-03 | [Register DB connection client](operations/register-db-connection-client.md) | Lazily constructs `IDBConnectionClient` and bootstraps its credentials from a secure, hash-gated setting. | [BR-SE-04](business-rules.md#br-se-04-db-connection-credentials-are-fetched-as-a-secure%2C-hash-gated-setting), [BR-SE-05](business-rules.md#br-se-05-the-credential-value-must-be-a-user%7Cpassword-pair), [BR-SE-01](business-rules.md#br-se-01-non-secure-environment-clients-cannot-retrieve-secure-settings) | | OP-04 | [Register Edge API auth services](operations/register-edge-api-auth-services.md) | Registers JWT-bearer-only authentication for external/Edge APIs. | [BR-SE-06](business-rules.md#br-se-06-edge-apis-authenticate-with-jwt-bearer-only) | | OP-05 | [Register Core API auth services](operations/register-core-api-auth-services.md) | Registers the dual JWT/Windows authentication policy and SecurityApi authorization for internal/Core APIs. | [BR-SE-07](business-rules.md#br-se-07-core-apis-authenticate-via-a-dual-jwt%2Fwindows-policy-scheme), [BR-SE-08](business-rules.md#br-se-08-securityapi-provides-authorization-policies-dynamically) | | OP-06 | [Require authenticated user](operations/require-authenticated-user.md) | Opt-in global MVC filter requiring authentication on every action. | [BR-SE-09](business-rules.md#br-se-09-opt-in-global-authenticated-user-requirement) | | OP-07 | [Register OIDC services](operations/register-oidc-services.md) | Registers OIDC middleware/services and delegates to web authentication setup. | [BR-SE-10](business-rules.md#br-se-10-jwt-refresh-and-lower-case-url-middleware-are-conditionally-registered), [BR-SE-11](business-rules.md#br-se-11-web-apps-default-to-cookie-authentication-with-optional-openidconnect-challenge) | | OP-08 | [Add web authentication](operations/add-web-authentication.md) | Configures Cookie/OpenIdConnect authentication schemes for web applications. | [BR-SE-11](business-rules.md#br-se-11-web-apps-default-to-cookie-authentication-with-optional-openidconnect-challenge) | | OP-09 | [Register for Windows service](operations/register-for-windows-service.md) | Composes environment client, logging, error handling, and DB connectivity for Windows services. | [BR-SE-03](business-rules.md#br-se-03-secure-mode-system-hash-is-computed-from-the-caller's-assembly), [BR-SE-04](business-rules.md#br-se-04-db-connection-credentials-are-fetched-as-a-secure%2C-hash-gated-setting) | | OP-10 | [Register logging and error handler](operations/register-logging-and-error-handler.md) | Registers logging, the single `IErrorHandler`, and error-handling middleware/hooks. | [BR-SE-12](business-rules.md#br-se-12-exactly-one-ierrorhandler-must-be-registered-among-error-handleables) | | OP-11 | [Dynamic error handler invocation](operations/dynamic-error-handler-invoke.md) | Request-pipeline exception handling: maps exceptions to HTTP responses and runs error hooks. | [BR-SE-12](business-rules.md#br-se-12-exactly-one-ierrorhandler-must-be-registered-among-error-handleables), [BR-SE-13](business-rules.md#br-se-13-exception-to-http-response-mapping), [BR-SE-14](business-rules.md#br-se-14-hook-failures-are-aggregated%2C-not-suppressed) | | OP-12 | [Debug request handler invocation](operations/debug-request-handler-invoke.md) | Logs every request at Debug level with request details. | [BR-SE-15](business-rules.md#br-se-15-every-request-is-logged-at-debug-level) | | OP-13 | [Legacy cookie gate middleware](operations/legacy-cookie-gate-middleware.md) | Presence-only legacy session/auth cookie checks that redirect but never block the pipeline. | [BR-SE-16](business-rules.md#br-se-16-legacy-cookie-gates-check-presence-only-and-are-fail-open) | | OP-14 | [App startup configure services](operations/app-startup-configure-services.md) | `AppStartup.ConfigureServices`: selects the web-app auth stack and composes session/logging/MVC. | [BR-SE-03](business-rules.md#br-se-03-secure-mode-system-hash-is-computed-from-the-caller's-assembly), [BR-SE-16](business-rules.md#br-se-16-legacy-cookie-gates-check-presence-only-and-are-fail-open), [BR-SE-17](business-rules.md#br-se-17-session-support-and-its-gate-are-opt-in), [BR-SE-18](business-rules.md#br-se-18-web-app-auth-stack-is-selected-by-aspnetcore_host_location) | | OP-15 | [App startup configure pipeline](operations/app-startup-configure-pipeline.md) | `AppStartup.Configure`: assembles the HTTP request pipeline for web applications. | [BR-SE-13](business-rules.md#br-se-13-exception-to-http-response-mapping), [BR-SE-10](business-rules.md#br-se-10-jwt-refresh-and-lower-case-url-middleware-are-conditionally-registered), [BR-SE-17](business-rules.md#br-se-17-session-support-and-its-gate-are-opt-in), [BR-SE-19](business-rules.md#br-se-19-hsts-is-always-on%3B-https-redirect-is-configurable-for-web-apps) | | OP-16 | [Core and Edge API startup](operations/core-and-edge-api-startup.md) | `CoreAPIStartup`/`EdgeAPIStartup`: composes and pipelines internal and external API hosts. | [BR-SE-01](business-rules.md#br-se-01-non-secure-environment-clients-cannot-retrieve-secure-settings), [BR-SE-03](business-rules.md#br-se-03-secure-mode-system-hash-is-computed-from-the-caller's-assembly), [BR-SE-04](business-rules.md#br-se-04-db-connection-credentials-are-fetched-as-a-secure%2C-hash-gated-setting), [BR-SE-06](business-rules.md#br-se-06-edge-apis-authenticate-with-jwt-bearer-only), [BR-SE-07](business-rules.md#br-se-07-core-apis-authenticate-via-a-dual-jwt%2Fwindows-policy-scheme), [BR-SE-19](business-rules.md#br-se-19-hsts-is-always-on%3B-https-redirect-is-configurable-for-web-apps) | | OP-17 | [OIDC MVC and Razor startup](operations/oidc-mvc-and-razor-startup.md) | `OidcMvcStartup`/`OidcRazorStartup`: adds MVC or Razor Pages support on top of `AppStartup`. | — | | OP-18 | [Console host bootstrap](operations/console-host-bootstrap.md) | `IHostBuilderExtensions`/`ConsoleBase`/`ConsoleAsyncBase`: composes and runs console applications. | [BR-SE-20](business-rules.md#br-se-20-console-configuration-source-precedence), [BR-SE-03](business-rules.md#br-se-03-secure-mode-system-hash-is-computed-from-the-caller's-assembly), [BR-SE-04](business-rules.md#br-se-04-db-connection-credentials-are-fetched-as-a-secure%2C-hash-gated-setting), [BR-SE-21](business-rules.md#br-se-21-console-process-exit-code-reflects-consolebase.exitcode) | | OP-19 | [Configure OpenTelemetry](operations/configure-open-telemetry.md) | Composes opt-in OpenTelemetry logging, metrics, and tracing. | [BR-SE-22](business-rules.md#br-se-22-enabling-opentelemetry-replaces-existing-logging-providers), [BR-SE-23](business-rules.md#br-se-23-all-meters-and-activity-sources-are-collected%3B-all-traces-sampled), [BR-SE-24](business-rules.md#br-se-24-otlp-export-requires-the-otlp-endpoint-variable) | | OP-20 | [Configuration helpers](operations/configuration-helpers.md) | `IConfigurationExtensions`: required/optional configuration-value reads with key validation. | [BR-SE-25](business-rules.md#br-se-25-required-configuration-keys-must-exist) | | OP-21 | [Controller throw helpers](operations/controller-throw-helpers.md) | `ControllerBaseExtensions`: converts error conditions to typed HTTP error responses. | [BR-SE-13](business-rules.md#br-se-13-exception-to-http-response-mapping), [BR-SE-26](business-rules.md#br-se-26-controller-helpers-convert-to-http-errors-by-throwing) | | OP-22 | [JWT controller claim helpers](operations/jwt-controller-claim-helpers.md) | `JwtControllerBase`: derives username and authentication time from JWT claims. | [BR-SE-27](business-rules.md#br-se-27-username-and-auth-time-are-derived-from-jwt-claims) | | OP-23 | [Windows service error-handler helpers](operations/windows-service-error-handler-helpers.md) | `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. ```mermaid 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:
config + logging + IHostedService only"] B -->|SAIF console| F2["IHostBuilderExtensions.BuildSaifConsoleApp:
calls BuildConsoleApp, then adds registrations below"] B -->|Windows service| G["RegisterForWindowsService: support-service
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
session gate, error handler, debug handler,
then UseAuthentication (inline, not ConfigureMiddleware)"] L -->|Core/Edge| M2["BaseApiStartup.ConfigureMiddleware:
buffering, error handler, debug handler"] M1 --> N[UseAuthentication / UseAuthorization] M2 --> N K -->|No: Minimal console, SAIF console| O1["Generic Host runs TConsole as the
registered IHostedService (no Configure/
IApplicationBuilder step)"] K -->|No: Windows service| O2["This library registers no host/IHostedService for
Windows service; hosting is the consuming
application's own responsibility"] C --> P{EnableSessionMiddleware set?} P -->|Yes, AppStartup only| Q["AspNetSessionIdMiddleware wired via
UseSession + UseMiddleware (fail-open gate)"] P -->|No| R[No session gate wired] Q --> M1 R --> M1 C --> S["LegacyBolAuthMiddleware: registered in DI when
EnableLegacyBolAuthMiddleware is set, but never
wired via UseMiddleware (dead code)"] J --> T["Optional: Configure OpenTelemetry"] ``` ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Dependencies](dependencies.md) - [Configuration](configuration.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/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`