---
title: SAIF.NetCore.ServiceContracts overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ServiceContracts
reference_type: package
---

# SAIF.NetCore.ServiceContracts overview

> **Documentation context:** Pipeline-packed NuGet package, consumed as a build-time dependency by other libraries in this repository.

`SAIF.NetCore.ServiceContracts` is the foundation-layer contracts assembly for the Framework.NCore mono-repo: it declares the interfaces, DTOs, enums, exception types, and event-args/delegate types that every other `SAIF.NetCore.*` ncore implementation library and consuming application depend on, and it contains no runtime behavior of its own beyond constructors, validating setters, and two fluent option methods.

## Purpose
- Define the cross-cutting contract surface — configuration retrieval (`IEnvironmentClient`), HTTP client (`IHttpJsonClient`/`IHttpRequestResult`), database connection-string retrieval (`IDBConnectionClient`), system hashing (`ISystemHashService`), logging (`ISaifLogService`/`ISaifWindowsServiceLogService`), identity/authorization (`IIdentityService`), OIDC (`IOidcSettings` and related), web and Windows-service error handling, and shared DTOs/exceptions — so that implementation libraries can be swapped without changing consumer code.
- Sit at the bottom of the dependency graph: it has zero `SAIF.NetCore.*` dependencies and is consumed by 16 in-repo packages, per `Architecture.md` and the package feed data.

## Responsibilities
- Declare configuration, HTTP, database-connection, hashing, logging, identity, OIDC, and error-handling contracts implemented by sibling `SAIF.NetCore.*` packages.
- Provide small, self-contained data types (`OidcAppCredentials`, `HttpClientOptions`, `JwtSet`, `ExternalUser`, `ExternalUserType`, `UserProfile`, `UserGroup`) with their own constructor validation and defaulting logic.
- Define the exception hierarchy (`SAIFException`, `HttpStatusCodeException`) used by implementation libraries for application-level errors.
- Define Windows-service error-handling event args, delegates, and the `ShutdownExemptExceptionType` validation helper consumed by `SAIF.NetCore.ErrorHandler`.

## Key components
- `IEnvironmentClient`: configuration/secure-setting contract implemented by `SAIF.NetCore.EnvironmentClient`.
- `IHttpJsonClient`/`IHttpRequestResult`: HTTP client contract implemented by `SAIF.NetCore.HttpClients`.
- `IIdentityService`/`IIdentityServiceAccessor`: identity/authorization contract implemented by `SAIF.NetCore.AuthService`.
- OIDC contracts (`IOidcSettings`, `IRoleClaimService`, `IJwtAuthorizationCookieClaimService`, `IJwtRefreshService`, `ILoginRedirectService`, `IDataProtectionCertService`, `IUrlCaseService`, `IClaimTransformCacheService`): implemented by `SAIF.NetCore.OIDC`.
- `IWindowsServiceErrorHandler` and related error-handling types: implemented by `SAIF.NetCore.ErrorHandler`.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts.csproj`
- `src/SAIF.NetCore.ServiceContracts/ReadMe.md`
- `Architecture.md`