In ASP.NET Core 10, what do app.Urls and the url argument of app.Run(url) or app.RunAsync(url) do, and how do they interact with configured URLs?
answer
- IServerAddressesFeature.Addresses
- Add before start, read-only after
- Run(url) clears, then adds one
- config urls read only when list empty
- hard-coded URLs defeat ASPNETCORE_URLS
basics
~20 sapp.Urls is the server's address list, writable until the server starts; the url argument of Run or RunAsync clears it and adds that one URL. Configured URLs such as ASPNETCORE_URLS are read only when the list is still empty at start.
solid answer
~40 s`app.Urls` is the server's `IServerAddressesFeature.Addresses`. Before the app starts you can add several entries — `app.Urls.Add("http://localhost:3000")` — and after the server binds, the collection becomes read-only: `Add` throws `InvalidOperationException` ("cannot be modified after the server has started"), while reading it lists the bound addresses. `app.Run(url)` and `app.RunAsync(url)` call a private `Listen` step that **clears** the list and adds the single URL before running, so they replace, not append. When the web host starts it fills the list from the `urls` configuration key (`ASPNETCORE_URLS`, `--urls`) or the ports settings **only if the list is still empty** — so any address set in code silently wins over the environment. That is why production code usually leaves `Run()` empty and lets configuration decide.
code
csharp · 10 linesvar app = WebApplication.CreateBuilder(args).Build();
app.MapGet("/", () => "Clinic API");
app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");
// ASPNETCORE_URLS is not read: the address list is no longer empty.
// app.Run("http://localhost:5100") would clear both and bind only 5100.
app.Run();go deeper
Recall that app.Urls and the url argument of Run choose addresses in code, and that the url argument replaces rather than adds.
Explain that both edit IServerAddressesFeature.Addresses, that configuration fills it only when empty, and that it turns read-only once the server binds.
Keep addresses out of Program.cs so containers, launch profiles and tests control them, and recognise a hard-coded URL as the cause of an ignored variable.
Make listening addresses a deployment concern across services, so port changes never require a code change or a rebuild.
## The address list behind app.Urls Every ASP.NET Core server publishes an **`IServerAddressesFeature`**; its `Addresses` collection is the list of URLs the server should bind. `WebApplication.Urls` returns exactly that collection, which gives `Program.cs` a code-level way to choose addresses: - **before start** the collection is writable: `app.Urls.Add("http://localhost:3000")` and `app.Urls.Add("http://localhost:4000")` make the app listen on both; - **after the server binds**, the public view is made read-only; `Add`, `Remove` and `Clear` throw `InvalidOperationException` with *"IServerAddressesFeature.Addresses cannot be modified after the server has started."*; - reading it after start lists the addresses in use, which is handy for a startup log line. ## The url argument of Run and RunAsync Both run methods take an optional URL: | Call | Effect on the address list | Then | |---|---|---| | `app.Run()` / `app.RunAsync()` | none | Runs with whatever the list or configuration provides | | `app.Run("http://localhost:5100")` | `Clear()`, then `Add("http://localhost:5100")` | Runs, blocking | | `app.RunAsync("http://localhost:5100")` | same | Runs, returning a `Task` | The work is done by a private `Listen(url)` step in `WebApplication`. It fetches the address feature and throws `InvalidOperationException` if there is none, or if the collection is already read-only; otherwise it clears the list and adds the URL. Two consequences follow: 1. `app.Run(url)` **replaces** anything added through `app.Urls` earlier — it never appends. 2. The URL argument accepts a single address; for several, use `app.Urls.Add` and call `Run()` with no argument. ## Code versus configuration When the web host starts, it checks the address list. **Only if the list is empty** does it consult configuration: the `urls` key (from `ASPNETCORE_URLS`, the `--urls` command-line option or any other source), and failing that the HTTP and HTTPS ports settings. If code has put anything in the list — through `app.Urls` or the `url` argument — those configuration values are not read at all. So with `ASPNETCORE_URLS=http://+:8080` in the environment and `app.Urls.Add("http://localhost:3000")` in `Program.cs`, the app listens on `localhost:3000`. Nothing is merged and no warning is logged for this case; the environment variable is simply never consulted. Kestrel's own endpoint configuration (a `Kestrel:Endpoints` section or `Listen` calls) is a separate, stronger mechanism with its own precedence rules and defaults; it belongs to Kestrel's configuration rather than to `WebApplication`. ## Why hard-coding is a trap - **Containers and platforms** pass the port through environment variables; `app.Run("http://localhost:3000")` ignores them and also binds loopback only, so the container's port mapping reaches nothing. - **Launch profiles** in development set URLs through an environment variable; a hard-coded URL makes the IDE wait on a port the app never opens. - **Tests and tools** that start the app with their own settings cannot move it. For a veterinary clinic's appointment API the safe pattern is: no URL in `Program.cs`, `app.Run()` with no argument, and the address supplied per environment. Code-level addresses remain useful for a throwaway sample or a tool that genuinely must pin its port. ## Reading the addresses at startup Because the list is populated by start-up, code that needs the real addresses reads them after the server has started — for example in a callback registered on `app.Lifetime.ApplicationStarted`, or after `await app.StartAsync()` — and logs `string.Join(", ", app.Urls)`. Reading `app.Urls` before start shows only what code added, which is often nothing.
- Why does app.Run("http://localhost:3000") throw InvalidOperationException when called after await app.StartAsync()?`Run(url)` calls `Listen`, which clears and refills the server's address list. Once Kestrel has bound, that list is read-only, so `Listen` throws before running. Pass the URL before starting, or call `Run()` without an argument.
- How do you make an ASP.NET Core 10 app listen on two ports from Program.cs?Add both to `app.Urls` before starting — `app.Urls.Add("http://localhost:3000"); app.Urls.Add("http://localhost:4000");` — and call `app.Run()` with no argument. Passing a URL to `Run` would clear the list and keep only that one.
- app.Run(url) adds the URL to those already in app.Urls
- ASPNETCORE_URLS always overrides addresses set in Program.cs
- app.Urls can be changed while the app is running to add a port
- Code and configured URLs are merged into one list at startup
- Reading app.Urls before start shows the addresses the app will bind