Customizing URL Binding For ASP .NET Core Kestrel Server

Customizing URL Binding For ASP .NET Core Kestrel Server

Kestrel server is the default server that is shipped with .NET. This article explains how the Kestrel server configurations can be modified to change the default bound URLs.

What is URL Binding ?

A web server generally listens to an IP address (or set of IP addresses) or host address(s) on specific ports and protocols. URL Binding is the server setting where this information can be configured.

For Kestrel server, if this information is not configured, then it by default listens to http://locahost:5000 and https://localhost:5001 URLs. There is only one limitation for HTTPS endpoint – the development certificate should be available on the machine where the server is running.

Development Certificate

For enabling HTTPS, server needs a certificate to enable end to end encryption. Generally, for running applications on production environment, the certificates are purchased from the trusted certificate authorities.

For development environment, generally a locally generated certificate can be used. This certificate is called as development certificate.

There are two ways to install this certificate:

  • The development certificate is installed automatically when the .NET SDK is installed for the first time on a machine.
  • OR another way is to generate the certificate using the dev-certs tool is used to create a certificate.

Change URL Bindings

There are multiple ways to change the URL bindings on Kestrel server. Let’s have a look at them one by one.

Environment Variables

ASPNETCORE_URLS environment variable can be used to set the URL bindings. Refer this blogpost to know different ways to set the environment variables.

Command Line Arguments

The dotnet run command has a switch --urls, which can also set the URL bindings on Kestrel server.

For ex. The command dotnet run --urls "https://localhost:44444" would run the application and Kestrel server would listen to https://localhost:44444.

Multiple URLs can be specified separated by semicolon (;) character.

UseUrls Extension

This method, UseUrls, is an extension method and can be used to set the URL bindings on Kestrel server.

Below code snippet shows the usage of this method while bootstrapping a .NET Core web applications.

public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseUrls("https://localhost:33333");
webBuilder.UseStartup<Startup>();
});
}
view raw Program.cs hosted with ❤ by GitHub

AppSettings.JSON

The configuration file, appsettings.json, can contain the URL bindings as shown in below code snippet. The CreateDefaultBuilder method gets the “Kestrel” configuration section and then applies these configuration to Kestrel.

{
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://localhost:44443"
},
"Https": {
"Url": "https://localhost:44444",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
view raw appsettings.json hosted with ❤ by GitHub

Have you used any other options to apply URL bindings to Kestrel server ? Let me know your thoughts.

Leave a Reply