---
title: Register environment client
summary: Registers the non-secure environment client and its supporting services.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ServiceExtensions
reference_type: package
operation_id: OP-01
trigger: A consuming application calls RegisterEnvironmentClient() during service configuration.
---

# Register environment client

This operation registers the baseline, non-secure `IEnvironmentClient` implementation along with the shared HTTP/host-resolution services it depends on. It is the entry point used by hosts that do not require secure-setting access (contrast with [Register secure environment client](register-secure-environment-client.md)).

| Field | Value |
| --- | --- |
| **Operation ID** | OP-01 |
| **Trigger** | Application startup code calls `RegisterEnvironmentClient()` on `IServiceCollection`. |
| **Inputs** | None (parameterless). |
| **Outputs** | Registers `ISystemWrapper`, `IHostResolver`, `IHttpJsonClient`, `IEnvironmentClient`, and a null `ISystemHashService` factory. |
| **Primary components** | `IServiceCollectionExtensions.RegisterEnvironmentClient` |
| **Entry point** | `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs` (L45–55) |

## Steps

1. `AddHttpContextAccessor()` registers the ASP.NET Core `IHttpContextAccessor`.
2. Register Singleton `ISystemWrapper → SystemWrapper` (`SAIF.NetCore.EnvironmentClient`) and Singleton `IHostResolver → HostResolver` (`SAIF.NetCore.EnvironmentClient`) — composition-root registration of EnvironmentClient's own infrastructure types, not a delegated operation.
3. Register Transient `IHttpJsonClient → HttpJsonClient` (`SAIF.NetCore.HttpClients`).
4. Register Singleton `IEnvironmentClient → BaseEnvironmentClient` ([BR-SE-01](../business-rules.md#br-se-01-non-secure-environment-clients-cannot-retrieve-secure-settings))
   - On failure: a later secure-setting read against this client throws `EnvironmentClientException`.

   > **Origin**: `BaseEnvironmentClient`'s own setting-lookup behavior is documented in [`Get setting value`](../../saif-netcore-environmentclient/operations/get-setting-value.md) and [`Has setting`](../../saif-netcore-environmentclient/operations/has-setting.md) (`SAIF.NetCore.EnvironmentClient`); this step only registers a type-based singleton descriptor — construction of `BaseEnvironmentClient` (and the bootstrap track/host lookup its constructor performs via `Setup()`) is deferred to the first time the DI container resolves `IEnvironmentClient`, not performed during this registration call.
5. Register a Singleton `ISystemHashService` factory that returns `null` ([BR-SE-01](../business-rules.md#br-se-01-non-secure-environment-clients-cannot-retrieve-secure-settings)), [BR-SE-02](../business-rules.md#br-se-02-a-null-system-hash-must-not-be-resolved-as-required)
   - On failure: resolving `ISystemHashService` via `GetRequiredService<ISystemHashService>()` throws `InvalidOperationException` (MS DI behavior for a factory returning `null`).

## Process flow

This diagram shows the one-time DI registration sequence performed when `RegisterEnvironmentClient()` is called during service configuration; the registered services' own setting-lookup behavior runs later, at resolution/use.

```mermaid
flowchart TD
    Start([RegisterEnvironmentClient called]) --> S1[AddHttpContextAccessor]
    S1 --> S2[Register ISystemWrapper / IHostResolver]
    S2 --> S3[Register IHttpJsonClient]
    S3 --> S4[Register IEnvironmentClient as BaseEnvironmentClient]
    S4 --> S5[Register null ISystemHashService factory]
    S5 --> EndOk([Non-secure environment client ready])
```

## Failure and edge-case behavior
- Attempting to read a secure setting from the registered `BaseEnvironmentClient` throws `EnvironmentClientException`.
- Resolving `ISystemHashService` with `GetRequiredService` throws `InvalidOperationException` because the factory returns `null`.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

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