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

# Configuration settings

`SAIF.NetCore.DBConnectionClient` reads exactly four named settings, all through `IEnvironmentClient.GetSettingValue`, plus two environment-identity properties, in a single method (`ConnectionClient.Setup`). It performs no `IConfiguration`, `IOptions<T>`, environment-variable, or `appsettings.json` reads of its own; its service-account credential is unlocked by the consumer, not by this library.

## Configuration retrieval methods

| Method | Class / Interface | Namespace | Usage pattern |
| --- | --- | --- | --- |
| `GetSettingValue(string configKey, string section)` | `IEnvironmentClient` (contract in `SAIF.NetCore.ServiceContracts`) | `SAIF.NetCore.Services.Contracts` | Plain-text, synchronous Environment API read. Key and section come from `public static readonly` fields of `ConnectionClientKeys`. Called once per key from the constructor through `virtual Setup()`. |
| `ApplicationHost` (property get) | `IEnvironmentClient` | `SAIF.NetCore.Services.Contracts` | Environment identity value passed to `IHttpJsonClient.SetClientInfo` as a request identification header. |
| `ApplicationName` (property get) | `IEnvironmentClient` | `SAIF.NetCore.Services.Contracts` | Environment identity value passed to `SetClientInfo`. |
| `GetSecureSetting(string configKey, string section, string systemHashValue)` | `IEnvironmentClient` | `SAIF.NetCore.Services.Contracts` | Not called by this library. The consumer (`SAIF.NetCore.ServiceExtensions`) calls it to unlock this client's service-account credentials — see *Secure settings* below. |

## Environment API settings

Settings retrieved via `IEnvironmentClient`.

| Setting key | Method | Data type | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- | --- |
| `DBConnectionClient:ServiceUrl` | `GetSettingValue(key, section)` | string | Base URL of the DBConnectionAPI. Passed to `IHttpJsonClient.SetClientInfo` as the client base address. | `ConnectionClient.Setup` → `ServiceUrl` | `src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ConnectionClient.cs` |
| `DBConnectionClient:SqlConnectionEndpoint` | `GetSettingValue(key, section)` | string | Route segment for SQL Server connection-string requests: `GET /{SqlConnectionEndpoint}/{server}/{instance}/{userName}`. | `ConnectionClient.Setup` → `SqlEndpoint` | same file |
| `DBConnectionClient:PostgreSqlConnectionEndpoint` | `GetSettingValue(key, section)` | string | Route segment for PostgreSQL connection-string requests: `GET /{PostgreSqlConnectionEndpoint}/{instance}/{userName}`. | `ConnectionClient.Setup` → `PostgreSqlEndpoint` | same file |
| `DBConnectionClient:OracleConnectionEndpoint` | `GetSettingValue(key, section)` | string | Route segment for Oracle connection-string requests: `GET /{OracleConnectionEndpoint}/{instance}/{userName}`. | `ConnectionClient.Setup` → `OracleEndpoint` | same file |

None of the four keys are validated as non-empty by this library; missing values flow unchecked into URL paths*.

**Environment identity values (not setting keys, used as request headers):**

| Value | Use | Source |
| --- | --- | --- |
| `IEnvironmentClient.ApplicationHost` | `SetClientInfo(ServiceUrl, "DBConnectionClient", applicationHost, applicationName)` header (3rd positional argument) | `ConnectionClient.cs` |
| `IEnvironmentClient.ApplicationName` | `SetClientInfo(ServiceUrl, "DBConnectionClient", applicationHost, applicationName)` header (4th positional argument) | `ConnectionClient.cs` |

**Hard-coded values (not configurable except by subclassing):**

| Value | Location |
| --- | --- |
| Client user `"DBConnectionClient"` | `ConnectionClient.Setup` |
| `MaxRetrieveAttempts` = 4 | `ConnectionClient` |
| Backoff of 2s / 3s / 5s | `ConnectionClient` |
| Placeholder tokens `ZSPECIALCHAR` and `{SERVER}` | `ConnectionClient` |
| NTLM authentication enabled at construction | `ConnectionClient.Setup` |

## Developer overrides

This library defines no override mechanism of its own. It inherits one from the standard `BaseEnvironmentClient` implementation that a consumer typically registers for `IEnvironmentClient`:

| File or flag | When applied | Effect |
| --- | --- | --- |
| The file path in `AppSettings:EnvApiDeveloperSettingsOverride` | Only if the file exists and the current machine is a developer machine* | Can replace any of the four `DBConnectionClient:*` values locally, ahead of the Environment API cache. |

This is never a production configuration source*. These keys are owned and documented authoritatively by `SAIF.NetCore.EnvironmentClient`.

## Secure settings

This library makes no secure-setting reads itself. Its service-account credential is unlocked by the consumer, recorded here because the hash input is this library's own assembly:

| Setting key | Encryption method | Purpose | Consuming class | Source |
| --- | --- | --- | --- | --- |
| `dbconnectionclient:connectionservicecreds` | Unlocked with `new SystemHashService(typeof(ConnectionClient).Assembly).Get(SystemType.WebApp)` | Service-account `username\|password`, split on `\|` and passed to `ConnectionClient.SetupClientCredentials` → NTLM | `SAIF.NetCore.ServiceExtensions.IServiceCollectionExtensions.RegisterDBConnectionClient` (transitive consumer) | `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs` |

Because the hash depends on this assembly, renaming, re-signing, or repackaging the assembly may change the hash and cause the secure setting to fail to unlock*.

## Transitive configuration (from dependencies)

| Setting key | Method | Source dependency | Dependency type | Purpose |
| --- | --- | --- | --- | --- |
| `AppSettings:ApplicationHost` | Read by `HostResolver` in `SAIF.NetCore.EnvironmentClient` | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive via `IEnvironmentClient` registration) | Selects the environment track, and therefore which `DBConnectionClient:*` values are returned; also becomes the `ApplicationHost` header. |
| `AppSettings:EnvApiDeveloperSettingsOverride` | Read by `BaseEnvironmentClient.ResolveDeveloperSettingsOverride` | `SAIF.NetCore.EnvironmentClient` | NuGet (transitive) | Developer-machine override of any `DBConnectionClient:*` value. |
| `IEnvironmentClient` registration | Required service, not registered by this library | `SAIF.NetCore.ServiceContracts` (contract); `SAIF.NetCore.EnvironmentClient` (implementation) | NuGet | `ServiceExtensions` registers `BaseEnvironmentClient` as a singleton. |
| `IHttpJsonClient` registration | Required service, not registered by this library | `SAIF.NetCore.ServiceContracts` (contract); `SAIF.NetCore.HttpClients` (implementation) | NuGet | Registered transient; captured by the singleton `ConnectionClient`. |
| `dbconnectionclient:connectionservicecreds` | Secure Environment API setting | `SAIF.NetCore.ServiceExtensions` | NuGet (transitive) | See *Secure settings* above. |

These keys are owned by `SAIF.NetCore.EnvironmentClient` and `SAIF.NetCore.ServiceExtensions`; their authoritative catalogs belong to those libraries.

## Configuration dependencies

| Dependency | Type | Required at | Impact if missing |
| --- | --- | --- | --- |
| `IEnvironmentClient` registration | Service | Construction (`Setup()`) | Any exception from the environment client propagates out of the `ConnectionClient` constructor uncaught. |
| `DBConnectionClient:ServiceUrl` and the three endpoint keys | Environment API setting | Construction, then every request | A missing value resolves to an empty string with no validation; URL paths are built unchecked, likely producing malformed requests*. |
| `dbconnectionclient:connectionservicecreds` | Secure Environment API setting | Consumer registration (`ServiceExtensions`) | `RegisterDBConnectionClient` constructs and configures the `ConnectionClient` instance first, then unconditionally calls `GetSecureSetting`, splits the result on `\|`, and indexes into the split array before calling `SetupClientCredentials`; it has no fallback branch. A retrieval failure, a missing setting, or a result without a `\|`-delimited second field throws during service resolution, so the already-constructed instance is never returned by the factory and remains unreachable. Direct construction that skips this factory (and never calls `SetupClientCredentials`) is the only path that leaves the ambient process identity active. |

## 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)
- [Security and authorization](security-authorization.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.

## Sources
- `src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ConnectionClient.cs`
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs`