skip to content

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?

level: middleimportance: should knowfreq 35%

answer

  1. IServerAddressesFeature.Addresses
  2. Add before start, read-only after
  3. Run(url) clears, then adds one
  4. config urls read only when list empty
  5. hard-coded URLs defeat ASPNETCORE_URLS

basics

~20 s

app.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 lines
csharp
var 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

for a junior

Recall that app.Urls and the url argument of Run choose addresses in code, and that the url argument replaces rather than adds.

for a middle

Explain that both edit IServerAddressesFeature.Addresses, that configuration fills it only when empty, and that it turns read-only once the server binds.

for a senior

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.

for a principal

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