Understanding Kestrel and Shutdown

Oct 13, 2025 by talynt.org 114 views

Introduction

When building a self-hosted REST API using .NET Core and Kestrel, it's essential to handle shutdowns gracefully. However, in some cases, the shutdown process can take a significant amount of time to complete, which can lead to issues with the application's overall performance and responsiveness. In this article, we'll explore how to configure Kestrel to ignore shutdown, using CancellationToken and SIGTERM signals.

Understanding Kestrel and Shutdown

Kestrel is a cross-platform web server that's part of the .NET Core framework. It's designed to be lightweight, fast, and scalable, making it an excellent choice for building self-hosted REST APIs. When it comes to shutdown, Kestrel provides a built-in mechanism for handling it gracefully. However, in some cases, the shutdown process can be slow, which can lead to issues with the application's performance.

The Problem with Shutdown

When a shutdown signal is received, Kestrel will attempt to shut down the server gracefully. This involves stopping any ongoing requests, closing connections, and releasing system resources. However, in some cases, the shutdown process can take a significant amount of time to complete. This can lead to issues with the application's performance, as the server may become unresponsive or even crash.

Using CancellationToken to Ignore Shutdown

One way to configure Kestrel to ignore shutdown is by using a CancellationToken. A CancellationToken is a mechanism that allows you to cancel an operation or a task. In the context of Kestrel, you can use a CancellationToken to ignore shutdown signals.

Here's an example of how you can use a CancellationToken to ignore shutdown:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
namespace MyApi
{
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
    public static IHostBuilder CreateHostBuilder(string[] args) =&gt;
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =&gt;
            {
                webBuilder.UseStartup&lt;Startup&gt;();
            })
            .ConfigureServices(services =&gt;
            {
                services.AddHostedService&lt;ShutdownService&gt;();
            });
}

public class ShutdownService : IHostedService, IDisposable
{
    private readonly CancellationTokenSource _cts;

    public ShutdownService()
    {
        _cts = new CancellationTokenSource();
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        // Ignore shutdown signal
        _cts.Cancel();
        return Task.CompletedTask;
    }

    public void Dispose()
    {
        _cts.Dispose();
    }
}

}

In this example, we've created a hosted service called ShutdownService that's responsible for handling shutdown signals. When a shutdown signal is received, the StopAsync method is called, which cancels the CancellationToken. This effectively ignores the shutdown signal and allows the server to continue running.

Using SIGTERM to Ignore Shutdown

Another way to configure Kestrel to ignore shutdown is by using the SIGTERM signal. SIGTERM is a signal that's sent to a process when it's being terminated. In the context of Kestrel, you can use the Process.Kill method to ignore the SIGTERM signal.

Here's an example of how you can use the SIGTERM signal to ignore shutdown:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
namespace MyApi
{
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
    public static IHostBuilder CreateHostBuilder(string[] args) =&gt;
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =&gt;
            {
                webBuilder.UseStartup&lt;Startup&gt;();
            })
            .ConfigureServices(services =&gt;
            {
                services.AddHostedService&lt;ShutdownService&gt;();
            });
}

public class ShutdownService : IHostedService, IDisposable
{
    public Task StartAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        // Ignore SIGTERM signal
        Process.Kill(Process.GetCurrentProcess().Id);
        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

}

In this example, we've created a hosted service called ShutdownService that's responsible for handling shutdown signals. When a SIGTERM signal is received, the StopAsync method is called, which kills the process using the Process.Kill method. This effectively ignores the SIGTERM signal and allows the server to continue running.

Conclusion

Configuring Kestrel to ignore shutdown is a crucial aspect of building a self-hosted REST API. By using a CancellationToken or the SIGTERM signal, you can ensure that your server continues to run even when a shutdown signal is received. In this article, we've explored how to configure Kestrel to ignore shutdown using both mechanisms. By following the examples provided, you can ensure that your server remains responsive and performs optimally even in the face of shutdown signals.

Best Practices

When configuring Kestrel to ignore shutdown, it's essential to follow best practices to ensure that your server remains stable and performs optimally. Here are some best practices to keep in mind:

Use a CancellationToken: Using a CancellationToken is a more elegant way to ignore shutdown signals compared to using the SIGTERM signal.
Implement a shutdown service: Implementing a shutdown service is a good practice to handle shutdown signals and ensure that your server remains stable.
Monitor system resources: Monitoring system resources is essential to ensure that your server remains stable and performs optimally.
Test your server: Testing your server is crucial to ensure that it remains stable and performs optimally even in the face of shutdown signals.

Q: What is the purpose of configuring Kestrel to ignore shutdown?

A: Configuring Kestrel to ignore shutdown is essential to ensure that your server remains stable and performs optimally even when shutdown signals are received. This is particularly important in scenarios where your server is handling critical operations or providing essential services.

Q: How do I configure Kestrel to ignore shutdown using a CancellationToken?

A: To configure Kestrel to ignore shutdown using a CancellationToken, you can create a hosted service that cancels the CancellationToken when a shutdown signal is received. Here's an example:

public class ShutdownService : IHostedService, IDisposable
{
    private readonly CancellationTokenSource _cts;
public ShutdownService()
{
    _cts = new CancellationTokenSource();
}

public Task StartAsync(CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

public Task StopAsync(CancellationToken cancellationToken)
{
    // Ignore shutdown signal
    _cts.Cancel();
    return Task.CompletedTask;
}

public void Dispose()
{
    _cts.Dispose();
}

}

Q: How do I configure Kestrel to ignore shutdown using the SIGTERM signal?

A: To configure Kestrel to ignore shutdown using the SIGTERM signal, you can create a hosted service that kills the process when a SIGTERM signal is received. Here's an example:

public class ShutdownService : IHostedService, IDisposable
{
    public Task StartAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
public Task StopAsync(CancellationToken cancellationToken)
{
    // Ignore SIGTERM signal
    Process.Kill(Process.GetCurrentProcess().Id);
    return Task.CompletedTask;
}

public void Dispose()
{
}

}

Q: What are the benefits of using a CancellationToken to ignore shutdown?

A: Using a CancellationToken to ignore shutdown has several benefits, including:

Elegance: Using a CancellationToken is a more elegant way to ignore shutdown signals compared to using the SIGTERM signal.
Flexibility: A CancellationToken can be used to cancel multiple operations or tasks, making it a more flexible solution.
Scalability: Using a CancellationToken can help scale your server to handle multiple shutdown signals.

Q: What are the benefits of using the SIGTERM signal to ignore shutdown?

A: Using the SIGTERM signal to ignore shutdown has several benefits, including:

Simplicity: Using the SIGTERM signal is a simple way to ignore shutdown signals.
Reliability: The SIGTERM signal is a reliable way to terminate a process.
Platform independence: The SIGTERM signal is a platform-independent way to terminate a process.

Q: How do I monitor system resources to ensure my server remains stable?

A: To monitor system resources, you can use tools such as:

Performance Monitor: A built-in Windows tool that provides real-time performance data.
top: A Linux command-line tool that provides real-time system information.
System Monitor: A built-in macOS tool that provides real-time system information.

Q: How do I test my server to ensure it remains stable?

A: To test your server, you can use tools such as:

Load testing: A type of testing that simulates a large number of users accessing your server.
Stress testing: A type of testing that simulates extreme conditions to test your server's stability.
Performance testing: A type of testing that measures your server's performance under various conditions.

By following these best practices and using the right tools, you can ensure that your server remains stable and performs optimally even when shutdown signals are received.