ASP.NET Core Application and Kestrel Web Server Settings

Kestrel server configuration in .NET Core

Let's see how Kestrel server is configured in .NET Core applications?

In ASP.NET Core application there is no Application_Start event, no XML configuration like web.config, instead, application start is a static main method all configuration related to the server is in the main method of a startup.cs class file.

Kestrel server is configured in the Main method of Program.cs file of the .NET Core application. The main method is an entry point of ASP.NET Core application. .NET Core libraries do not have program.cs or Main method. The main method is the first method which will be invoked.

Following is the Main method from ASP.NET Core 1.x application.

public class Program
{
  public static void Main(string[] args)
  {
    var host = new WebHostBuilder()
      .UseKestrel()
      .UseContentRoot(Directory.GetCurrentDirectory())
      .UseIISIntegration()
      .UseStartup()
      .Build();

    host.Run();
  }
}

In 1.x you explicitly set each configuration of WebHostBuilder including Kestrel server.

In 2.0+ you can still configure WebHostBuilder explicitly but a simple approach is available there. Following is a 2.0+ program.cs with simple configuration of WebHostBuilder.

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

  public static IWebHost BuildWebHost(string[] args) =>
      WebHost.CreateDefaultBuilder(args)
          .UseStartup()
          .Build();
}

WebHost.CreateDefaultBuilder(args) configures Kestrel server with default settings. If you want to use a specific configuration for Kestrel use the below code.

Add a reference to Microsoft.AspNetCore.Server.Kestrel.Core. You may need to install the NuGet package Microsoft.AspNetCore.Server.Kestrel.

    using Microsoft.AspNetCore.Server.Kestrel.Core

Why Kestrel server instead of IIS

The ASP.NET Core applications are meant to be run on multiple platforms or cross-platform. Applications built with .NET Core can be run on IIS however IIS is windows only server.

ASP.NET Core applications can be the host on NgInx, Apache servers. If you are not using the Kestrel server you will have to configure the startup method for each server separately. All ASP.NET Core applications use kestrel web server as an in-process for a consistent startup process to support cross-platform execution.

Comparison of Kestrel Web Server Vs IIS

Comparison of Kestrel Web Server Vs IIS IIS can perform anything which is required to run ASP.NET Core application whereas Kestrel uses as little as required, because of this Kestrel server execution is much faster than IIS. Definitely standalone Kestrel has much better performance than IIS when handling the high number of concurrent requests.

However standalone Kestrel server can not handle Windows Authentication, external SSL certificates, Application Initialization, Request Filtering, response caching and many more features which IIS can easily handle.

To make optimized use of Kestrel Server and IIS features, you can use Kestrel with IIS as the reverse proxy server. In this way, IIS will get client request which will be massaged and forward it to the kestrel server. You can use UseIISIntegration(), UseKestrel() and ConfigureKestrel() methods for configuration.

Following code shows configuration of IIS and Kestrel

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseKestrel()
    .UseIISIntegration()
    .UseStartup<Startup>()
    .ConfigureKestrel((context, options) =>
    {
        // Set properties and call methods on options
    })
    .Build();
    host.Run();
}

HTTPS Requests with Kestrel server

Kestrel server makes easy communication with secure requests and responses between your .net core application. you can configure the application to accept only HTTPs request or redirect HTTP requests to https port using UseHttpsRedirection.

The following code calls UseHttpsRedirection to redirect http requests in the Startup class:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseHttpsRedirection();
    
    app.UseMvc();
}

To configure https port you can use CreateDefaultBuilder as shown in below code snippet.

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

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

Deploying ASP.NET Core application to productions.

With ASP.NET core on windows, you can use IIS to host your application. Hosting ASP.NET Core with IIS will give benefits of IIS features like security, process management, configuration, central logging, app performance, error tracking, and many others.

Http/https request still be arrived in IIS first, then IIS will forward it to Kestrel web server and then application code executes. Following pictures shows how HTTP/s request flow from the client to application code.

Web.config settings

ASP.NET core has appsettings.json file to store configuration settings, this does not contain Web.config file by default, when you publish your code, it will be automatically added to your publish folder. Or you can manually add to your project by Add -> New Item -> Web Configuration file. The default file looks like.

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
    <location path="." inheritInChildApplications="false">
    <system.webServer>
    <handlers>
    <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" 
            resourceType="Unspecified" />

      </handlers>
    <aspNetCore processPath="dotnet" arguments=".\WebApplication1.dll" 
            stdoutLogEnabled="false" 
            stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />

    </system.webServer>
  </location>
</configuration>

The web config file is required for settings related to IIS(System.Webserver element) or reverse proxy.

Benefits of using Kestrel Server

1. Cross-platform

   The most useful benefit of the Kestrel web server is the ability to execute across different platforms. You can create ASP.NET Core application on Windows and IIS express and host it on Apache or NGInx, the server will always be Kestrel and you don't have to change any code.

2. Performance

   There is a tremendous difference when you use ASP.NET Core. ASP.NET Core code serves 5 times more requests compare to .NET framework 4.6 on the same hardware.