[Documentation] Internal Port Resolution Logic

[souvikghosh04]

Background

With recent changes, Data API Builder (DAB) now determines the internal HTTP port using a clear precedence order, including support for a DAB-specific DEFAULT_PORT environment variable as a fallback. This logic ensures compatibility across all major .NET hosting environments (ACA, AKS, ACI, Docker, IIS/Kestrel, etc.).

• Platform agnostic port resolution for health endpoint #2757

Proposed Documentation Section

Internal Port Resolution

Data API Builder (DAB) determines which HTTP port to use for internal operations (such as health checks and internal HTTP calls) using the following precedence:

1. ASPNETCORE_URLS
   If set, DAB parses this environment variable and uses the first port specified.

2. ASPNETCORE_HTTP_PORTS
   If ASPNETCORE_URLS is not set, DAB checks this variable (introduced in .NET 8 for container scenarios) and uses the first port specified.

3. DEFAULT_PORT (DAB-specific)
   If neither of the above are set, DAB looks for a DEFAULT_PORT environment variable.
   ℹ️ Note: DEFAULT_PORT is a DAB-specific environment variable. It is not recognized by .NET or Azure Container Apps by default. It is only used by DAB as a fallback for custom scenarios.

4. Fallback to 5000
   If none of the above are set or valid, DAB defaults to port 5000, which is the standard default for ASP.NET Core applications.

Example Scenarios

Scenario	Port Used
ASPNETCORE_URLS=http://*:8080	8080
ASPNETCORE_HTTP_PORTS=7071	7071
DEFAULT_PORT=6000	6000
None of the above set	5000

Additional Notes

• If any variable is set but contains an invalid or malformed value, DAB will fall back to the next option in the list.
• This logic ensures DAB works seamlessly in Azure Container Apps, AKS, ACI, Docker, IIS/Kestrel, and other .NET hosting environments.
• DEFAULT_PORT is only used by DAB and is not a standard environment variable in .NET or Azure.