--- title: SAIF.NetCore.ServiceContracts operations and processes summary: Business and technical operations supported by this library. status: draft owner: Framework.NCore maintainers last_reviewed: 2026-10-02 library: SAIF.NetCore.ServiceContracts reference_type: package --- # 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](operations/construct-oidc-application-credentials.md) | 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](business-rules.md#br-001-raw-oidc-credential-string-must-not-be-null), [BR-002](business-rules.md#br-002-raw-oidc-credentials-must-be-two-pipe-delimited-segments) | — | — | | [Register a shutdown exempt exception type](operations/register-shutdown-exempt-exception-type.md) | 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](business-rules.md#br-003-shutdown-exempt-exception-type-must-not-be-null), [BR-004](business-rules.md#br-004-shutdown-exempt-type-must-be-a-strict-exception-subclass), [BR-005](business-rules.md#br-005-shutdown-exempt-type-defaults-to-always-allowed) | — | — | | [Configure HTTP client options](operations/configure-http-client-options.md) | 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](business-rules.md#br-006-http-client-option-defaults), [BR-007](business-rules.md#br-007-persistheaders-with-no-argument-enables-persistence), [BR-008](business-rules.md#br-008-usenewtonsoftjson-selects-the-newtonsoft-serializer) | — | — | | [Create error handling event arguments and results](operations/create-error-handling-event-arguments-and-results.md) | 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](business-rules.md#br-010-error-handling-event-args-default-to-unhandled-with-special-actions-enabled), [BR-011](business-rules.md#br-011-special-error-action-result-defaults-to-not-executed) | — | — | | [Construct SAIF exceptions](operations/construct-saif-exceptions.md) | 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](business-rules.md#br-009-httpstatuscodeexception-defaults-to-text-plain-content-type) | — | — | ## 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. ```mermaid 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 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. ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Dependencies](dependencies.md) - [Business rules](business-rules.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.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`