---
title: Configuration settings
summary: Configuration keys consumed by this library, retrieval methods, and runtime dependencies.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.Clients.UC4
reference_type: package
---

# Configuration settings

SAIF.NetCore.Clients.UC4 reads exactly two Environment API settings, both in the `uc4coreapi` section, through `IEnvironmentClient`; it reads no `IConfiguration` keys, `Web.config`/`App.config` settings, environment variables, or secure settings directly.

## Configuration retrieval methods

| Method | Class / Interface | Namespace | Usage pattern |
| --- | --- | --- | --- |
| `IEnvironmentClient.HasSetting(string configKey, string section)` | `IEnvironmentClient` (contract) → `BaseEnvironmentClient.HasSetting` (runtime) | `SAIF.NetCore.Services.Contracts` | Called twice from a private `EnsureSettingExists` helper during construction, with section `"uc4coreapi"`; a `false` result throws `NotSupportedException`. Existence check only — no value check. |
| `IEnvironmentClient.GetSettingValue(string configKey, string section)` | `IEnvironmentClient` → `BaseEnvironmentClient.GetSettingValue` | `SAIF.NetCore.Services.Contracts` | Called twice in the constructor, immediately after the existence check, to populate `ServiceUrl` and `ScheduleJobEndpoint`. A missing/null value resolves to `""` and never throws. |

## Environment API settings

Settings retrieved via `IEnvironmentClient`. Both keys live in a single dedicated section, `uc4coreapi`, read only by `UC4Client`; there is no wrapping configuration class — `UC4Client` itself holds the resolved values as public, privately-set properties.

| Setting key | Method | Data type | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- | --- |
| `uc4coreapi:url` | `HasSetting` then `GetSettingValue` | string (absolute URL) | Base URL of the UC4 Core API, passed to `IHttpJsonClient.SetClientInfo` on the first `ScheduleJob` call; exposed read-only as `UC4Client.ServiceUrl`. **Required** — missing key throws `NotSupportedException` at construction. | `UC4Client` (ctor, `Init`) | `src/SAIF.NetCore.Clients.UC4/SAIF.NetCore.Clients.UC4/SAIF.NetCore.Clients.UC4/Services/UC4Client.cs` |
| `uc4coreapi:schedulejobroute` | `HasSetting` then `GetSettingValue` | string (relative URL path, expected to end in its own separator) | Relative route prefix for the schedule-job POST; the request resource is `{ScheduleJobEndpoint}{jobname}`, a direct concatenation with no separator added and no URL-encoding. Exposed read-only as `UC4Client.ScheduleJobEndpoint`. **Required** — missing key throws `NotSupportedException` at construction. | `UC4Client` (ctor, `ScheduleJob`) | same file |

Both settings are validated for **existence only**, not for a non-empty or well-formed value ([BR-UC4-01](business-rules.md#br-uc4-01-required-settings-must-exist-at-construction), [BR-UC4-02](business-rules.md#br-uc4-02-settings-existence-is-validated-independently-of-value-content)). An empty `uc4coreapi:url` is accepted silently and fails later with `UriFormatException` on the first `ScheduleJob` call; an empty `uc4coreapi:schedulejobroute` causes every POST to target `{jobname}` alone.

## Developer overrides

This library defines no developer override file or flag of its own. It is affected by the transitive `SAIF.NetCore.EnvironmentClient` developer override mechanism (`AppSettings:EnvApiDeveloperSettingsOverride`), with an asymmetric effect:

| File or flag | When applied | Effect | Source |
| --- | --- | --- | --- |
| EnvironmentClient developer settings override file | Developer machine, file present | Can replace the **value** of `uc4coreapi:url` / `uc4coreapi:schedulejobroute` once the key already exists in the Environment API for that track. It does **not** satisfy the `HasSetting` existence check performed by `EnsureSettingExists` — a key entirely absent from the Environment API still throws `NotSupportedException`, even if the override file defines it (CR-UC4-04). | `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/BaseEnvironmentClient.cs` |

## Transitive configuration (from dependencies)

UC4 has no `<ProjectReference>` and a single `PackageReference` to `SAIF.NetCore.ServiceContracts` (contracts only, no configuration reads). Configuration arrives transitively through the runtime implementations of the two injected contracts, which a consuming application must register.

| Setting key | Method | Source dependency | Dependency type | Purpose |
| --- | --- | --- | --- | --- |
| Registered `IEnvironmentClient` | DI resolution | `SAIF.NetCore.EnvironmentClient` (`BaseEnvironmentClient` / `SecureEnvironmentClient`) | NuGet (runtime-registered by `SAIF.NetCore.ServiceExtensions`) | Required constructor dependency; resolves both `uc4coreapi` settings. |
| Registered `IHttpJsonClient` | DI resolution | `SAIF.NetCore.HttpClients` (`HttpJsonClient`) | NuGet (runtime-registered by `SAIF.NetCore.ServiceExtensions`) | Required constructor dependency; sends the schedule-job POST. Reads no configuration of its own; retry/delay come from `HttpClientOptions` defaults (retry on 401/502/503, 1000 ms, 3 retries), which UC4 never overrides. |
| `EnvironmentApiUrl` (environment variable) | Process bootstrap | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Base URL of the Environment API that serves section `uc4coreapi`; absent → `MissingEnvironmentUrlVariableException` before `UC4Client` can be constructed. |
| `IHostEnvironment.ApplicationName` | Host-supplied identity | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Selects the application/host-qualified Environment API retrieval URL used to look up `uc4coreapi:*`; whether the underlying settings are published once and shared across applications on the server side, or published separately per consuming application, is unknown**. |
| `AppSettings:ApplicationHost`, `AppSettings:EnvApiDeveloperOverrideAllowed`, `AppSettings:EnvApiDeveloperSettingsOverride` | `IConfiguration` bootstrap | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Determine host → track and hence which `uc4coreapi` values are returned; enable the developer override described above. |
| `COREAPIENABLED=1` | `IConfiguration` root key | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Required only if the host registers `SecureEnvironmentClient` on a non-developer machine; UC4 itself performs no secure reads. |
| `EnvironmentClient:GetHostsByTrack:RetryCount` / `:RetrySleepMs` | `IConfiguration` (optional) | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Startup resilience of the environment client that UC4 depends on. |

## Configuration dependencies

| Dependency | Type | Required at | Impact if missing |
| --- | --- | --- | --- |
| `uc4coreapi:url` | Environment API setting (key) | Construction (DI activation) | `NotSupportedException`; construction aborts. |
| `uc4coreapi:schedulejobroute` | Environment API setting (key) | Construction (DI activation) | `NotSupportedException`; construction aborts. |
| `IEnvironmentClient` registration | DI service | Construction (DI container activation) | `UC4Client` cannot be resolved by the DI container; activation fails immediately with the container's resolution error (constructor parameter). A manual `new UC4Client(null, httpJsonClient)` is accepted by the unguarded constructor, but fails immediately during construction — not deferred to first use — because the constructor's first statement, `EnsureSettingExists`, calls `env.HasSetting`, which throws a `NullReferenceException` on the null `env` right away. |
| `IHttpJsonClient` registration | DI service | Construction (DI container activation) | `UC4Client` cannot be resolved by the DI container under normal constructor-injection DI resolution; activation fails immediately (constructor parameter). Only a manual `new UC4Client(env, null)` is accepted by the unguarded constructor and fails later, on the first `ScheduleJob` call, with a `NullReferenceException`. |

Key configuration risks: existence-only validation means a malformed or empty `uc4coreapi:url` is detected late, at the first `ScheduleJob` call, as a `UriFormatException` rather than at construction (CR-UC4-01); a `uc4coreapi:schedulejobroute` value missing its own trailing separator silently produces the wrong request resource (CR-UC4-02); because both values are snapshotted into properties in the constructor, a long-lived (Singleton) `UC4Client` never observes an Environment API change until process restart (CR-UC4-05).

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.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.Clients.UC4/SAIF.NetCore.Clients.UC4/SAIF.NetCore.Clients.UC4/Services/UC4Client.cs`
- `src/SAIF.NetCore.Clients.UC4/SAIF.NetCore.Clients.UC4/SAIF.NetCore.Clients.UC4/Constants.cs`
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/BaseEnvironmentClient.cs` — declares `HasSetting`/`GetSettingValue` and the Environment API section/host resolution behavior UC4 relies on.
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SecureEnvironmentClient.cs` — declares the secure-client construction requirement referenced by the `COREAPIENABLED` row.
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs` — declares `SetClientInfo`, the behavior `IHttpJsonClient` registration backs.
- `src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/HttpClientOptions.cs` — declares the retry/delay defaults referenced in the transitive configuration table.
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs` — registers `IEnvironmentClient` and `IHttpJsonClient` for consuming applications.