---
title: Resolve an environment host name
summary: Normalize request hosts to the Environment API naming convention.
status: draft
owner: SAIF Framework
last_reviewed: 2026-07-30
library: SAIF.Framework.Security.EnvironmentApi
reference_type: package
operation_id: OP-ENV-010
trigger: Web or WCF host resolution needs a lookup key
---

# Resolve an environment host name

This operation converts an incoming request URI into the host token the Environment API expects for configuration lookup. It strips domain suffixes from named hosts so that configuration keyed only by machine name still resolves correctly, preserves IP addresses unchanged, and appends non-default ports so multiple services on one host do not collide.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-ENV-010 |
| **Trigger** | Web or WCF host resolution needs a normalized host key |
| **Inputs** | Request `Uri` |
| **Outputs** | Normalized host string |
| **Primary components** | `EnvironmentHost.ResolveHost`, `EnvironmentHost.HostIsIpAddress`, `EnvironmentHost.EnsureHostWithoutDomain` |
| **Entry point** | `SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentHost.cs` |

## Steps

1. Start from `uri.DnsSafeHost`.
2. Determine whether the host is an IP address by removing dots and attempting `long.TryParse` on what remains.
3. If the host is not an IP address, split on `.` and keep only the first segment, so an external domain suffix never changes the Environment API lookup key for the same machine.
4. If the URI uses a non-default port, append `-<port>` to the normalized host so services distinguished only by port resolve to distinct configuration entries.
5. Return the normalized host string to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller provides Uri]) --> Host[Read DnsSafeHost]
	Host --> Ip{Host is IP address?}
	Ip -->|No| Strip[Remove domain suffix]
	Ip -->|Yes| Port{Default port?}
	Strip --> Port
	Port -->|No| Append[Append dash and port]
	Port -->|Yes| ReturnHost([Return host])
	Append --> ReturnPort([Return host-port token])
```

## Failure and edge-case behavior

- Only the first hostname segment is preserved for non-IP hosts; any additional subdomain information is discarded.
- IP detection relies purely on whether the dot-stripped string parses as a number, so an unusual hostname that happens to be all digits could be misclassified as an IP address.
- The method assumes the caller supplies a non-null `Uri`; it performs no null check of its own.

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

## Sources
- SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentHost.cs
- SAIF.Framework.Security.EnvironmentApi\Services.Common\WebEnvironmentService.cs
- SAIF.Framework.Security.EnvironmentApi\Services.Common\WcfEnvironmentService.cs