WebHost doesn't detect ASPNETCORE_HTTP_PORTS

[tmds]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

The .NET images for .NET 8 changed from using ASPNETCORE_URLS to using ASPNETCORE_HTTP_PORTS.

Older applications using the WebHost API don't seem to pick up the new environment variable.

Expected Behavior

Applications using the WebHost API should use the new environment variables.

Or this should be documented as a breaking change.

Steps To Reproduce

using Microsoft.AspNetCore ;

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

class Startup
{
    public void Configure()
    { }
}

$ ASPNETCORE_HTTP_PORTS=8080 dotnet run --no-launch-profile
Hosting environment: Production
Content root path: /tmp/web2
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

As shown in the output, the application binds to port 5000 instead of port 8080 as set by the envvar.

Exceptions (if any)

No response

.NET Version

8.0.100-rc.1.23455.1

Anything else?

No response

[tmds]

cc @richlander @Tratcher

[Tratcher]

Correct, the legacy WebHost APIs do not support new features like ASPNETCORE_HTTP_PORTS.

[tmds]

Correct, the legacy WebHost APIs do not support new features like ASPNETCORE_HTTP_PORTS.

Probably the old API is still being used since it's still functional and not deprecated.

Since container images are now using the new envvar, do you think it's worth calling this out as part of the breaking changes? Perhaps include this in https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port?

cc @mthalman

[mthalman]

Correct, the legacy WebHost APIs do not support new features like ASPNETCORE_HTTP_PORTS.

Why not?

[tmds]

@Tratcher what can we do for .NET 8 GA?

[Tratcher]

Correct, the legacy WebHost APIs do not support new features like ASPNETCORE_HTTP_PORTS.

Why not?

Because it's twice as much work to implement new features in both places and in most cases, WebHost doesn't need the new features. We'd only consider this if it was going to cause a significant interop issue?

what can we do for .NET 8 GA?

Not much, .NET 8 is locking down and only taking servicing level fixes at this point. @adityamandaleeka?

[tmds]

Users reading https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port will assume their ASP.NET app will change to port 8080 when using Microsoft base images.

The WebHost based ASP.NET apps will instead be changing to port 5000. It would be good to cover this in the breaking change doc.

The WebHost based apps can either migrate to the new APIs or set ASPNETCORE_URLS to http://*:8080.

[amcasey]

Sorry, I'm getting a little mixed up because I think there's some implicit context in the problem discussion that I'm missing. Do I understand correctly that the dotnet container images were updated for 8.0 to start configuring aspnetcore via ASPNETCORE_HTTP_PORTS, rather than ASPNETCORE_URLS, and that this won't work for code using the older WebHost APIs? If so, which breaking change doc is being referenced? The one for the container images?

What would happen if the container image(s) set both environment variables? I'm assuming the newer one would win in any code path that supports both?

[tmds]

What would happen if the container image(s) set both environment variables? I'm assuming the newer one would win in any code path that supports both?

The newer envar was introduced to be more user-friendly.

When both are set, the new envvar gets ignored for backwards compatibility.

this won't work for code using the older WebHost APIs?

Yes. They don't know about the envvar that is set in the 8.0 container images.

It causes them to bind to port 5000.

which breaking change doc is being referenced?

There is no breaking change doc about the WebHost port yet.

There is one about the port changing from 80 to 8080: https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port.

[amcasey]

When both are set, the new envvar gets ignored for backwards compatibility.

What's the back compat issue? Consumers who were setting ASPNETCORE_HTTP_PORTS before aspnetcore started consuming it?

Edit: To be explicit, you're correct, it's just not immediately obvious to me why it was done that way.

[amcasey]

Do you remember why URLS beats HTTP_PORTS, @Tratcher? It looks like it was a pretty explicit decision.

[tmds]

The reason is backwards compatibility. If user was setting ASPNETCORE_URLS (in a derived image, a Kubernetes spec, ...) then the 8.0 image will still respect that setting.

[amcasey]

If I understand correctly, the scenario of concern is when the user has specified ASPNETCORE_URLS and the container tooling has specified ASPNETCORE_HTTP_PORTS. When that occurs, we want the user's setting to win. Is that right?

If so, how did the container tooling formerly handle the case where the user had specified ASPNETCORE_URLS? I'm guessing the user's setting was applied last and won?

And the reason the container tooling prefers not to continue using ASPNETCORE_URLS is that the user might begin using ASPNETCORE_HTTP_PORTS, which would then be clobbered by the tooling's setting?

[tmds]

The scenario of concern is when a user has not specified the ASPNETCORE_URLS and relies on the envvar that is set in the .NET container image.

Before .NET 8, ASPNET Core binds to port 80.

With the .NET 8 images, applications that use the newer WebApplication API bind to port 8080 instead of port 80 as described in https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port.

Applications that use the older WebHost API bind to port 5000 instead of port 80.
This change in behavior is not documented.

[amcasey]

@tmds Thanks for the explanation! I agree with your assessment that this will be disruptive to some users and needs to be documented. My questions were more aimed at improving my understanding of what could have been done to avoid getting into this state and what we could do to get out of it in the future.

[richlander]

I can explain the behavior. It's not quite as described. It's neither due to compat or "winning". It's much simpler.

• ASPNETCORE_URLS is the "low level API". It is capable to describing multiple ports and multiple protocols all in one syntax. It's overkill for the default cause, which is why I asked for the new ENV.
• ASPNETCORE_HTTP_PORT/S is the "high level API". It can specify one or more ports for a single protocol as semicolon delimited ints. Super nice.
• The former overrides the latter because the former offers a superset of the descriptiveness. That's it and the only coherent approach. It could be argued as being for compat, but we don't need to even get to compat for this choice to the best one.
• You can just as easily override ASPNETCORE_HTTP_PORT with ASPNETCORE_HTTP_PORT.
• The dotnet containers all use ASPNETCORE_HTTP_PORT so that users can override the setting with either ENV.
• However, you also don't know (unless you check) what was used to define the port within the container unless its yours. So, ASPNETCORE_URLS is the safest option to use for overriding, in general. Also, if you are overriding a container you don't own, you probably know what you are doing and the more complicated API is then fine for you to use.

[amcasey]

@Tratcher Which hosts support ASPNETCORE_HTTP_PORT and in what circumstances might someone be using one that doesn't?

[Tratcher]

Do: 'Modern' hosts, everything since 3.0:

aspnetcore/src/ProjectTemplates/Web.ProjectTemplates/content/WebApi-CSharp/Program.cs

Lines 20 to 21 in 2b7e994

	Host.CreateDefaultBuilder(args)
	.ConfigureWebHostDefaults(webBuilder =>

aspnetcore/src/ProjectTemplates/Web.ProjectTemplates/content/WebApi-CSharp/Program.cs

Line 17 in d025c79

var builder = WebApplication.CreateBuilder(args);

Do not: 'Legacy' hosts:

aspnetcore/src/Templating/src/Microsoft.DotNet.Web.ProjectTemplates/content/WebApi-CSharp/Program.cs

Line 21 in 1be20f4

WebHost.CreateDefaultBuilder(args)

So if an application was created using the 2.1 templates and then updated to later versions without updating the host code, they could run into this.

[Tratcher]

What I said about versions is confusing. The hosting APIs introduced in 3.0 and later have been updated in 8.0 to support ASPNETCORE_HTTP_PORT. The hosting APIs from 2.1 and earlier were not updated.

[amcasey]

@tmds is the scenario that came to your attention a legacy app or was there a compelling reason to write a new app in an old style?

[tmds]

Apps using the old APIs which haven't been updated.

These APIs aren't marked obsolete and are still functional.

Some users aren't inclined update their apps to use newer APIs until the old ones stop working.

[richlander]

I think that updating the breaking change docs to cover this case is warranted. It probably just needs a sentence of two.

https://learn.microsoft.com/en-us/dotnet/core/compatibility/containers/8.0/aspnet-port

[amcasey]

dotnet/docs#37661