Skip to content

SAIF.NetCore.DBConnectionClient overview

Documentation context: Packaged Component (NuGet)

SAIF.NetCore.DBConnectionClient is an implementation-layer NuGet package that provides ConnectionClient, the sole behavioral type implementing the IDBConnectionClient contract from SAIF.NetCore.ServiceContracts; rather than connecting to any database itself, it retrieves fully formatted SQL Server, PostgreSQL, and Oracle connection strings from a remote HTTP service (the DBConnectionAPI) on behalf of the hosting application.

Purpose

  • Act as a connection-string retrieval client: callers that need to open a SQL Server, PostgreSQL, or Oracle connection ask ConnectionClient for the formatted connection string instead of assembling or storing one themselves.
  • Centralize the HTTP calling convention (client-identity headers, NTLM authentication, retry-with-backoff, in-memory caching) that every connection-string lookup shares, so individual applications do not reimplement it.
  • Serve as the implementation half of a contract/implementation split: the interface (IDBConnectionClient) lives in the foundation SAIF.NetCore.ServiceContracts package, while this package supplies the concrete behavior, typically wired up by SAIF.NetCore.ServiceExtensions.

Responsibilities

  • Resolve the DBConnectionAPI base URL and the three endpoint path segments from the DBConnectionClient configuration section via IEnvironmentClient.GetSettingValue.
  • Configure the injected IHttpJsonClient with client-identity headers and, when supplied, explicit NTLM service-account credentials.
  • Retrieve connection strings over HTTP with a bounded retry policy and cache successful results per connection name for the lifetime of the client instance.
  • Classify HTTP outcomes into permanent failures (401, 403, 404 — fail fast), transient failures (503 or network error — retry), and other failures, and translate classified response failures and exhausted transient retries into DBClientException; a malformed backoff configuration instead throws InvalidOperationException, and exceptions from the injected IHttpJsonClient or IEnvironmentClient propagate unwrapped.
  • Decode legacy special-character placeholders (ZSPECIALCHAR) in returned connection strings before caching and returning them.

Key components

  • ConnectionClient: the template-method-style class that owns configuration resolution, HTTP client setup, retrieval-with-retry, and caching.
  • ConnectionClientKeys: the public static class holding the configuration section name and the three endpoint-key constants.
  • DBClientException: the SAIFException (ServiceContracts) subtype used to surface classified HTTP response failures and exhausted transient retries; configuration errors (InvalidOperationException) and collaborator exceptions are not wrapped in it.

Sources

  • src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ConnectionClient.cs
  • src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ClientException.cs
  • src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/IDBConnectionClient.cs