---
title: Consumption
summary: How a consuming application references, constructs, calls, and disposes the proxy.
status: draft
owner: SAIF.Core documentation
last_reviewed: 2026-09-24
---

# Consumption

A consumer obtains connection strings by holding a `DbConnectionServiceProxy` instance for the lifetime of `SAIF.Services.Common.DbConnectionService`, which is itself consumed by `SAIF.Services.Web.Proxies` and, through that library, by `SAIF.Services.Web.Proxies` consumers documented at [`SAIF.Services.Web.Proxies` overview](../../libraries/saif-services-web-proxies/overview.md).

## Reference style

| Field | Value |
| --- | --- |
| Mechanism | Service Reference (svcutil) |
| Declared in | `Services/SAIF.Services.Web.Proxies/Service References/DbConnection/Reference.svcmap` |
| Generated artifacts | `Services/SAIF.Services.Web.Proxies/Service References/DbConnection/Reference.cs` |
| Target framework | .NET Framework 4.6.2 |
| Regeneration command | Visual Studio "Update Service Reference" |

## Construction

```csharp
public DbConnectionServiceProxy(string serviceUrl)
{
    Enforce.ArgumentNotNullOrWhiteSpace(serviceUrl, nameof(serviceUrl));
    webService = new ConnectInfoSoapClient(new BasicHttpBinding(), new EndpointAddress(serviceUrl));
}
```

| Step | Requirement |
| --- | --- |
| Endpoint address | Constructor argument, itself resolved by `DbConnectionService` from `IEnvironmentService.GetConfigSetting("dbconnectionserviceurl")` |
| Binding | Constructed in code — `new BasicHttpBinding()` with all defaults |
| Credentials | None |
| Initialization | Single-constructor |

## Endpoint configuration

| Setting | Value | Source | Changeable without a rebuild |
| --- | --- | --- | --- |
| Endpoint address | Unresolved from repository configuration** | `Services/SAIF.Services.Common/DbConnectionService.cs:21` | Not determined from source** |
| Binding configuration | Constructed in code | `Services/SAIF.Services.Web.Proxies/Legacy/DbConnectionsServiceProxy.cs:18` | No |
| Security mode | None declared — `BasicHttpBinding()` default* | `DbConnectionsServiceProxy.cs:18` | No |

The `app.config` `<client><endpoint name="ConnectInfoSoap">` entry (`Services/SAIF.Services.Web.Proxies/app.config:73`) is present but is not used at runtime, because the wrapper supplies an explicit `Binding` and `EndpointAddress` to the generated constructor.

## Resilience

| Concern | Finding | Configurable by consumer | Source | Tech debt |
| --- | --- | --- | --- | --- |
| Timeout | None configured — binding defaults apply | No | `DbConnectionsServiceProxy.cs:18` | Yes |
| Retry | None configured | No | — | Yes |
| Circuit breaking | None configured | No | — | Yes |
| Thread safety | Not determined from source | — | — | No |
| Cancellation | Not supported — no cancellation on any call site | — | `DbConnectionsServiceProxy.cs:31,45` | Yes |
| Message size limits | Not set — WCF default of 65,536 bytes applies* | No | `DbConnectionsServiceProxy.cs:18` | No |

Both calls are synchronous and blocking with no `CancellationToken`, so a slow or unreachable remote service blocks the calling thread for up to the default one-minute send timeout — see [Tech debt](tech-debt.md).

## Disposal

| Aspect | Finding |
| --- | --- |
| Disposal performed | `Close()` |
| Faulted channel handled | No — a faulted channel throws from disposal and masks the original failure |
| Wrapper responsibility | `DbConnectionServiceProxy` disposes the generated proxy |
| Source | `Services/SAIF.Services.Web.Proxies/Legacy/DbConnectionsServiceProxy.cs:61-68` |

```csharp
public void Dispose()
{
    webService.Close();
}
```

## Error handling for consumers

| Failure | Surfaces as | Consumer action |
| --- | --- | --- |
| Service unreachable | `EndpointNotFoundException`† | None — propagates to `DbConnectionService.GetConnectionString`, then to the external caller |
| SOAP fault returned | `FaultException`† | None — propagates unchanged |
| Timeout exceeded | `TimeoutException`† | None — propagates unchanged |
| Response larger than the message size limit | `CommunicationException`† | None — propagates unchanged |
| Empty or absent output message | `NullReferenceException` at the `ZSPECIALCHAR` replace for `GetODPConnectString`* | None — unhandled |

## Usage examples

```csharp
// Retrieve an Oracle connection string for the CLM pool code
var connectionString = dbConnectionService.GetConnectionString("MYINSTANCE", "CLM");
```

| Scenario | Operations used | Notes |
| --- | --- | --- |
| Resolve an Oracle connection string by pool code and instance | `GetODPConnectString` | Reached through `SAIF.Services.Common.DbConnectionService.GetConnectionString(instance, userName)` |
| Resolve a SQL Server connection string by server, pool code, and instance | `GetSQLConnectString` | Reached through `SAIF.Services.Common.DbConnectionService.GetConnectionString(server, instance, userName)` |

## Lifecycle guidance

| Question | Answer |
| --- | --- |
| Construct once or per call | Once — the wrapper is created in the `DbConnectionService` constructor and held for its lifetime |
| Disposable | Yes (`IDisposable`) |
| Safe to share across threads | Not determined from source |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Contract](contract.md)
- [Operation map](operation-map.md)
- [Client reference](reference.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence. Statements marked with `**` could
> not be confirmed; treat as unknown until verified.

## Sources
- `Services/SAIF.Services.Web.Proxies/Legacy/DbConnectionsServiceProxy.cs`
- `Services/SAIF.Services.Common/DbConnectionService.cs`
- `Services/SAIF.Services.Web.Proxies/app.config`