SAIF.NetCore.ServiceContracts operations and processes¶

This page is the operation catalog and cross-operation hub for this library. SAIF.NetCore.ServiceContracts is a contracts-only assembly, so its only executable operations are type constructors, validating setters, and two fluent option methods; the operations declared by its interfaces (IEnvironmentClient, IHttpJsonClient, IIdentityService, OIDC contracts, and so on) are implemented in other SAIF.NetCore.* libraries and are documented there. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog¶

Operation	Intent	Trigger	Inputs	Outputs	Rules	Tables	SQL
Construct OIDC application credentials	Parse a decrypted raw credential string into a `ClientId`/`ClientSecret` pair.	A consumer constructs `OidcAppCredentials` from a raw string decrypted from CryptoApi.	`raw` (string, expected format `clientId\\|clientSecret`)	An `OidcAppCredentials` struct with `ClientId` and `ClientSecret` populated.	BR-001, BR-002	—	—
Register a shutdown exempt exception type	Validate and construct an entry describing an exception type that should not trigger Windows-service shutdown.	A consumer adds an entry to `IWindowsServiceErrorHandler.ShutdownExemptExceptionTypes`.	`t` (exception `Type`), optional `isAllowed` predicate	A `ShutdownExemptExceptionType` instance holding `Type` and `IsAllowed`.	BR-003, BR-004, BR-005	—	—
Configure HTTP client options	Initialize an `HttpClientOptions` instance with its defaults and apply optional fluent overrides.	A consumer creates options and passes them to `IHttpJsonClient.SetOptions`.	None for initialization; optional fluent-method arguments (`option`, nothing for `UseNewtonsoftJson`).	A configured `HttpClientOptions` instance; the fluent methods return `this` for chaining.	BR-006, BR-007, BR-008	—	—
Create error handling event arguments and results	Construct the event-args and result types that carry Windows-service error-handling state between an `IWindowsServiceErrorHandler` implementation and its subscribers.	An `IWindowsServiceErrorHandler` implementation raises `BeginErrorHandling`/`ErrorHandled`, or records an `ISpecialErrorAction` outcome.	`ex` (`Exception`), `container` (`IErrorContextContainer`), `handled` (bool), `results` (`SpecialErrorActionResult[]`), `title` (string), `status` (`SpecialErrorActionStatus`, optional)	A `BeginErrorHandlingEventArgs`, `ErrorHandledEventArgs`, or `SpecialErrorActionResult` instance.	BR-010, BR-011	—	—
Construct SAIF exceptions	Create the library's exception types used by implementation libraries for application-level errors.	Implementation-library code throws `new SAIFException(message[, inner])` or `new HttpStatusCodeException(message[, inner])`.	`message` (string), optional `inner` (`Exception`)	A `SAIFException` or `HttpStatusCodeException` instance ready to be thrown.	BR-009	—	—

Process flow diagram¶

The following diagram visualizes how a consumer typically exercises this library's executable surface — constructing validated data types and exceptions that are then used by implementation libraries.

flowchart TD
    Start([Consumer code]) --> Pick{What is being constructed?}
    Pick -->|OIDC credentials| OP1["OP-01: Construct OidcAppCredentials"]
    Pick -->|Shutdown-exempt type| OP2["OP-02: Register shutdown-exempt exception type"]
    Pick -->|HTTP options| OP3["OP-03: Configure HTTP client options"]
    Pick -->|Error-handling event args| OP4["OP-04: Create error-handling event arguments and results"]
    Pick -->|Exception| OP5["OP-05: Construct SAIF exceptions"]
    OP1 --> Used([Instance used by implementation library])
    OP2 --> Used
    OP3 --> Used
    OP4 --> Used
    OP5 --> Used

Contract operation catalog (declared here, implemented elsewhere)¶

The interfaces below declare operations that this library does not execute. They are listed for traceability; their step sequences belong to the implementing library's own operations-processes.md.

Contract	Declared operations	Implemented in
`IEnvironmentClient`	Get setting value / secure setting (sync and async, typed and string, with or without section, hash or `SystemType`); `GetSectionSettings`; `HasSetting`; `IsDeveloperMachine`	`SAIF.NetCore.EnvironmentClient`
`ISystemHashService`	`ComputeHash`, `ComputeHashNow`, `Get`, `GetAssembly`, `RemoveSystemHashSaltAndValidateLifetime`	`SAIF.NetCore.SystemHash`
`IHttpJsonClient` / `IHttpRequestResult`	HTTP verbs (sync/async), auth setters, client info, options, result accessors	`SAIF.NetCore.HttpClients`
`IDBConnectionClient`	Get SQL Server / Oracle / PostgreSQL connection strings	`SAIF.NetCore.DBConnectionClient`
`ISaifLogService` / `ISaifWindowsServiceLogService`	`Configure`, then Debug/Info/Warning/Error/Fatal	`SAIF.NetCore.Logging`
`IIdentityService` / `IIdentityServiceAccessor`	Identity, claims, `IsAuthorized`, `GetUser`, `GetUsersByGroup`	`SAIF.NetCore.AuthService`
OIDC contracts	Role-claim transform, claim cache, JWT cookie update and rewrite, token refresh, login redirect, data-protection cert, URL casing, settings	`SAIF.NetCore.OIDC`
`IWindowsServiceErrorHandler` and related	`HandleError`, special actions, events, shutdown-exempt types	`SAIF.NetCore.ErrorHandler`
`IErrorHandlerHook`	`Task Invoke(ExceptionEnum exceptionType, HttpContext context, Exception ex, int statusCode, List<object> logDetails)` hook called by `DynamicErrorHandler` (per XML doc)	Implemented by consumers*.
`IServiceTaskRunner`	`Run(CancellationToken)`, `TaskTitle`	Implemented by consumers and driven by `SAIF.NetCore.WindowsService` `ServiceWorker`*.

Failure and edge-case behavior¶

None of the operations on this page read or write a database or issue SQL; the library has zero data-access surface.
None of the operations delegate into a referenced library, because the library has no SAIF.NetCore.* dependencies.
See each operation's own ## Failure and edge-case behavior for its specific validation and error paths.

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.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/OidcAppCredentials.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/ShutdownExemptExceptionType.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/HttpClientOptions.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/BeginErrorHandlingEventArgs.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/ErrorHandledEventArgs.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SpecialErrorActionResult.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIFException.cs
src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/HttpStatusCodeException.cs