Comprehensive Guide to Specifying Ports in ASP.NET Core Applications

ASP.NET Core applications, by default, bind to port 5000 when hosted with Kestrel. However, developers often need to specify custom ports to avoid conflicts or adapt to various deployment scenarios. This article systematically covers multiple configuration methods based on the latest ASP.NET Core versions, with step-by-step code examples for clarity.

Default Port Behavior

Without any configuration, ASP.NET Core applications listen on http://localhost:5000. This default can be overridden using several approaches to meet specific requirements.

Configuring Ports via Command-Line Arguments

Command-line arguments offer a quick way to set the port. Use the --urls parameter when starting the application to specify the URL and port. For example:

dotnet run --urls=http://localhost:5001/

This command binds the application to port 5001 on localhost. Multiple URLs can be specified with a semicolon delimiter, such as --urls=http://localhost:5001;https://localhost:5002 for both HTTP and HTTPS support.

Using appsettings.json for Port Configuration

For persistent configuration, add a Urls node in the appsettings.json file to define the port. Example configuration:

{
  "Urls": "http://localhost:5001"
}

This configuration is loaded at application startup and overrides the default port. Note that if Kestrel-specific settings are present, they may take precedence, so careful ordering is advised.

Leveraging Environment Variables for Port Configuration

Environment variables provide flexibility, especially in containerized or cloud environments. Set the ASPNETCORE_URLS environment variable to specify the port:

ASPNETCORE_URLS=http://localhost:5001/

The host builder reads this variable and uses it to configure the listening addresses automatically.

Programmatic Configuration with UseUrls Method

In code, the UseUrls method can be called during host configuration to set the port. For applications using the generic host builder:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
            webBuilder.UseUrls("http://localhost:5001/");
        });

For the older web host builder approach:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseUrls("http://localhost:5001/")
        .Build();
    host.Run();
}

This method allows full control over port settings within the code, ideal for dynamic configurations.

Advanced Kestrel Endpoint Configuration

Beyond UseUrls, Kestrel enables detailed endpoint configuration via KestrelServerOptions. For instance, define Kestrel endpoints in appsettings.json:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5002"
      }
    }
  }
}

This approach supports advanced features like HTTPS. If both Urls and Kestrel endpoints are configured, the latter may override or complement based on the setup.

HTTPS and Security Considerations

When configuring HTTPS ports, additional steps such as certificate specification are required. For example, using UseUrls with HTTPS necessitates a default certificate. In code, employ the UseHttps method:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("certificate.pfx", "password");
    });
});

This ensures secure TLS communication on the specified port, enhancing data protection for the application.

Conclusion

Port configuration is a critical aspect of deploying ASP.NET Core applications. Developers can choose from command-line, configuration files, environment variables, or code-based methods based on their needs. Understanding these options facilitates the building of robust, configurable applications suited for diverse environments.