---
title: EnvironmentServiceBase
summary: API reference for EnvironmentServiceBase.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.Security.EnvironmentApi
reference_type: package
---

# EnvironmentServiceBase

`EnvironmentServiceBase` is the abstract base class implementing `IEnvironmentService`. It performs the HTTP calls to the Environment API, owns the in-memory settings cache and throttled refresh logic, and hosts the cross-cutting `IsDeveloperMachine`/`MachineSecurity` authorization logic shared by all host-specific environment services.

## Purpose
- Provide the shared HTTP/caching/refresh implementation of `IEnvironmentService` for all host-specific subclasses.

## Context
- Namespace: `SAIF.Framework.Security`
- Assembly/package: `SAIF.Framework.Security.EnvironmentApi`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| DeveloperSettingsFile | `string DeveloperSettingsFile { get; }` | Resolves the local developer settings-override file path; only resolved when `IsDeveloperMachine` is true (see [BR-004](../../business-rules.md#br-004-developer-settings-override-requires-developer-machine-status)). |
| ApplicationId | `string ApplicationId { get; }` | The application identifier, defaulting to `"unknown"` when unset. |
| LastRefreshed | `DateTime LastRefreshed { get; }` | The last time settings were refreshed at the server, throttled by `AllowRefreshCheckInSeconds`. |
| Configurations | `ConfigurationSettings Configurations { get; }` | The current in-memory cached configuration settings; triggers a refresh if not yet loaded. |
| LastLoaded | `DateTime LastLoaded { get; }` | The last time settings were loaded from the Environment API. |
| LastRefreshChecked | `DateTime LastRefreshChecked { get; }` | The last time the refresh date was checked against the Environment API. |
| ApplicationHost | `abstract string ApplicationHost { get; }` | Host-specific resolution of the application host name; implemented by each subclass. |
| MachineName | `abstract string MachineName { get; }` | Host-specific machine name. |
| IsClientExternal | `abstract bool IsClientExternal { get; }` | Host-specific external-client determination. |
| IsClientInsideFirewall | `abstract bool IsClientInsideFirewall { get; }` | Host-specific inside-firewall determination. |
| IsLocalMachine | `abstract bool IsLocalMachine { get; }` | Host-specific local-machine determination. |
| IsWeb | `abstract bool IsWeb { get; }` | Host-specific web-context flag. |
| User | `abstract IPrincipal User { get; }` | Host-specific already-authenticated principal. |
| GetApplicationEnvironment | `ApplicationEnvironment GetApplicationEnvironment()` | Returns `Configurations.Environment`. |
| GetApplicationTrack | `string GetApplicationTrack()` | Returns `Configurations.Track`. |
| IsProduction | `bool IsProduction { get; }` | `true` when `GetApplicationEnvironment()` is `ApplicationEnvironment.Prod`. |
| IsMachineTagNumber | `bool IsMachineTagNumber(string hostName)` | Tests whether a host name matches the `^[TV]\d+$` tag-number pattern (case-insensitive). |
| IsDeveloperMachine | `virtual bool IsDeveloperMachine { get; }` | Determines and memoizes developer-machine status (see [BR-005](../../business-rules.md#br-005-developer-machine-classification-requires-tag-number-host-and-ad-membership)). |
| GetConfigSetting | `string GetConfigSetting(string configKey)` | Retrieves a plain-text configuration value. |
| GetGlobalConfigSetting | `string GetGlobalConfigSetting(string configKey)` | Direct HTTP GET against the global-section setting endpoint, bypassing the section cache. |
| GetSecureConfigSetting | `string GetSecureConfigSetting(string configKey, string systemHashValue)` | Retrieves an encrypted configuration value. |
| GetSecureConfigSetting\<T\> | `T GetSecureConfigSetting<T>(string configKey, string systemHashValue)` | Retrieves a typed encrypted configuration value. |
| GetConfigSetting\<T\> | `T GetConfigSetting<T>(string configKey)` | Retrieves a typed configuration value. |
| LoadSection | `ConfigurationSettings LoadSection(string section)` | Fetches and merges an entire named configuration section into the cache. |
| GetHostFromAppConfig | `protected string GetHostFromAppConfig()` | Reads the local `<appSettings>` key `ApplicationHost` as a developer/local host override. |
| EnvironmentApiUrl | `protected string EnvironmentApiUrl { get; }` | The Environment API base URL, resolved from the `EnvironmentApiUrl` OS environment variable (see [BR-002](../../business-rules.md#br-002-environment-api-base-url-must-be-present)). |
| EnvironmentServiceBase() | `protected EnvironmentServiceBase()` | Default constructor; loads global settings for the track. |
| EnvironmentServiceBase(sections) | `protected EnvironmentServiceBase(params string[] sections)` | Constructor that also loads the specified configuration sections. |

## Behavioral notes
- `RefreshConfigurationIfNewer()` (private) is invoked by `Configurations`, `LoadSection`, and configuration-retrieval methods to keep the cache current, throttled by `AllowRefreshCheckInSeconds` (default 120 seconds).
- `IsDeveloperMachine` couples this class to `MachineSecurityService`/`ADService` for AD-group-membership authorization, via the private `MachineSecurity` property, which lazily constructs a `MachineSecurityService` using LDAP/domain values resolved from global Environment API config settings (`ad.ldap.host`, `ad.ldap.internal.root`, `ad.internal.domain`).
- `GetConfigSettingInfo` (private) implements the lookup order described in [Retrieve a configuration setting](../../operations-processes.md#retrieve-a-configuration-setting): developer override file → in-memory cache → Environment API section fetch, throwing `ApplicationException` if unresolved ([BR-001](../../business-rules.md#br-001-configuration-key-must-resolve-or-fail-loudly)).

## Constraints and usage notes
- This is an `abstract` class; consumers must instantiate one of the concrete host-specific subclasses (`WebEnvironmentService`, `WindowsEnvironmentService`, `WcfEnvironmentService`, `CustomEnvironmentService`, `OfficeAddinEnvironmentService`).
- Accessing `EnvironmentApiUrl` when the `EnvironmentApiUrl` OS environment variable is absent throws `MissingEnvironmentUrlVariableException`.

> **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
- SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs
- SAIF.Framework.Security.EnvironmentApi\Exceptions\MissingEnvironmentUrlVariableException.cs