[Announcement] New Kestrel endpoint configuration API

[halter73]

For right now, there is no change in the behavior of the WebHostBuilder extension method .UseUrls() as long as UseHttps() nor any other IConnectionFilter is configured.

The main breaking change is that KestrelServerOptions.ConnectionFilter has been removed and replaced with ListenOptions.ConnectionAdapters. Since connection filters are no longer global, but instead per-endpoint, the IConnectionFilter interface has been removed and replaced with IConnectionAdapter. The entire Microsoft.AspNetCore.Server.Kestrel.Filter namespace has been removed and replaced with the Microsoft.AspNetCore.Server.Kestrel.Adapter namespace.

This means that any extension methods that add a global connection filter to KestrelServerOptions (namely UseHttps() and UseConnectionLogging()) are now ListenOptions extension methods.

The second breaking change is that KestrelServerOptions.NoDelay has been moved to ListenOptions.NoDelay.

---

The following description of the new Kestrel endpoint configuration API mostly comes from #996.

• Added an extension method to KestrelServerOptions for binding to a TCP socket. There is no overload on .Listen() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                // Easy mode (http only)
                options.Listen(IPAddress.Any, 80);

                // Verbose
                options.Listen(IPAddress.Any, 443, listenOptions => 
                {
                    listenOptions.NoDelay = false;
                    // Enable https
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();

host.Run();

• Added an extension method to KestrelServerOptions for binding to a unix socket. There is no overload on .ListenUnixSocket() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                // Easy mode
                options.ListenUnixSocket("/tmp/kestrel-test.sock");

                // Verbose
                options.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions => 
                {
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();

host.Run();

• Added an extension method to KestrelServerOptions for binding to a file descriptor. There is no overload on .ListenHandle() that allows you to configure an SSL cert without using an options lambda.

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                var fds = Environment.GetEnvironment("SD_LISTEN_FDS_START");
                int fd = Int32.Parse(fds);

                // Easy mode
                options.ListenHandle(fd);

                // Verbose
                options.ListenHandle(fd, listenOptions => 
                {
                    listenOptions.UseHttps("server.pfx");
                });
            })
            .UseStartup<Startup>()
            .Build();
host.Run();

• Given that the file descriptor will be used will oftentimes be used with systemd socket activation (Support systemd socket activation #1057), provide an extension method to KestrelServerOptions that parses the environment variable set by systemd and binds to that file descriptor. This method will no-op if the requisite environment variable has not been set (Similar to how .UseIISIntegration() no-ops).

var host = new WebHostBuilder()
            .UseKestrel(options =>
            {
                options.UseSystemd();
            })
            .UseStartup<Startup>()
            .Build();
host.Run();

---

There is a follow-up issue to make it easier to configure Kestrel endpoints from config given the new Listen* APIs.

[muratg]

We are closing this issue because no further action is planned for this issue. If you still have any issues or questions, please log a new issue with any additional details that you have.