microsoft / microsoft/aspire

Support setting resource endpoint ports from AppHost config & persist random assignments to user secrets

Open
#13,597 2 comments 3 reactions 0 assignees View on GitHub
area-app-model
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

## Summary

Support configuring resource endpoint ports via the AppHost `IConfiguration` (e.g. from `appsettings.json` or user secrets), and persist randomly assigned ports to user secrets, so subsequent runs maintain the same port assignments for resources (when possible). This would avoid developers needing to hard-code ports into the AppHost. The port configuration can optionally indicate whether the configured port value is "required" (default), "preferred", or "suggested".

## Proposal

- When a resource endpoint port is randomly assigned, save it to the AppHost user secrets using a schema like `Resources:::port` along with a flag indicating the port is preferred rather than static.
- When an endpoint's port is being assigned when it wasn't specified directly via code on the endpoint annotation, attempt to use the port assigned via `IConfiguration` if present
- Before reusing a port specified via config, check if the port is still available; if not, and it's also marked "preferred" or "suggested", fallback to assigning a different random port and logging a message to the resource logs. If the configured port was marked "suggested", then persist the new port to user secrets.
- For resources that read endpoints/ports from launch profiles, define precedence rules. For example:
- Configuration from AppHost should be able to override launch profile.
- Ports set directly in code should always win.
- Document the order of precedence for where port values are sourced.

## Benefit

Enables "sticky but safe" port assignments for local resources, improving developer experience (no more unexpected port changes, less manual config). Avoids requiring all ports to be hardcoded. We could update the polyglot templates to set ports in configuration for Python and JavaScript app resources.

## Additional context

- Schema suggestion: `Resources:::port`
- Typical scenario: Docker resources in Aspire AppHost needing stable endpoint assignment across runs.

## ❓Open questions
- Should we treat ports in .NET project resources' launch profiles as "required", "preferred", or "suggested"? Today, they act as "required" and if there's a port conflict the resource just fails to start.

Contributor guide

Open the contributing guide

Research direction

Start with the AppHost IConfiguration, appsettings.json, user secrets, and launch-profile behavior described in the issue. Trace how endpoint ports are currently selected for Docker and .NET resources, including the precedence between configuration and code. Done means required, preferred, and suggested ports have defined behavior, with documented precedence and persistent assignments when possible.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.