Overview
This blogpost discusses how to create a Linux service using DotNet Core (6). It also discusses how to implement a clean shutdown routine.
Creating the application skeleton
The application boilerplate code can be quickly generated using Visual Studio. Just select to create a new "Worker Service" (the last one in the screenshot).
You can do the same using just the dotnet CLI:
dotnet new worker
The files that are of interest are:
- Program.cs
- Worker.cs
Program.cs creates the host and registers the Worker class. The Worker class is where you start to write your logic. The generated code in Program.cs is:
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureServices(services =>
{
services.AddHostedService<Worker>();
})
.Build();
await host.RunAsync();
We need to add a reference to Microsoft.Extensions.Hosting.Systemd package in order to interact with the Service manager of Linux. The short and somewhat useless documentation by Microsoft says "Sets the host lifetime to SystemdLifetime, provides notification messages for application started and stopping, and configures console logging to the systemd format.". Hopefully that explains everything about its use. The sample application uses version 6.0.0 because trying to use 7.0.0.0 resulted in compilation errors. You can add the package using:
dotnet add package Microsoft.Extensions.Hosting.Systemd --version 6.0.0
You need to make one code change after the package has been added, its at the time of creating the host:
IHost host = Host.CreateDefaultBuilder(args)
.ConfigureServices(services =>
{
services.AddHostedService<Worker>();
})
.UseSystemd() // added to work with systemd
.Build();
Note: the sample code defines the Main method and adds another method to create the HostBuilder instead of using the generated code as-is.
Deploying the service
We need to abide by a couple of rules to deploy a service managed by 'Systemd'. What's systemd you ask? Systemd is the service manager used by Linux today just like we have the SCM (Service Control Manager) in Windows.
The first step is to create a service file, the service file defines the name of the service, its dependencies and its startup & shutdown behavior among other things..
Here is a basic service file which can be used for our service. The name of the file defines the name of the service. The file should be named as "servicename.service".
[Unit] Description=Sample Linux Service [Service] Type=notify WorkingDirectory=/usr/sbin/SampleLinuxService/ ExecStart=/usr/bin/dotnet /usr/sbin/SampleLinuxService/SampleLinuxService.dll Environment=DOTNET_ROOT=/usr/lib64/dotnet User=ec2-user SyslogIdentifier=SampleLinuxService Restart=always RestartSec=5 [Install] WantedBy=multi-user.target
The important lines here are:
| Property | Description |
|---|---|
| WorkingDirectory | Setting this is specially important if we are not using a single-contained application. The sample discussed in the blogpost is published as a framework-dependent application |
| ExecStart | Defines the command to run to start the service. We are using the dotnet command to run our application stored in folder '/usr/sbin/SampleLinuxService/' |
| User | Specifies the Linux user used to run the service. |
| Environment | We can setup various environment variables, this is not needed if the user used to start the service already had the correct environment variables defined in the profile. |
You can read about the other properties here. The service file needs to be stored at /etc/systemd/system/. Ensure that all the application files are accessible by the user mentioned in the service file. You can change the ownership to the correct user with the following command:
sudo chown ec2-user /usr/sbin/SampleLinuxService/*
Finally, we need to tell systemd about our service by issuing the following command:
sudo systemctl daemon-reload
Interacting with the service
Now that the service is registered, you can start interacting with the service. What kind of interaction you ask? First let's query its status:
$ sudo systemctl status SampleLinuxService SampleLinuxService.service - Sample Linux Service Loaded: loaded (/etc/systemd/system/SampleLinuxService.service; disabled; vendor preset: disabled) Active: inactive (dead)
To start the service use:
$ sudo systemctl start SampleLinuxService
To stop the service use:
sudo systemctl stop SampleLinuxService
To ensure service auto-starts on machine reboots:
sudo systemctl enable SampleLinuxService
To view the service logs use:
sudo journalctl -u SampleLinuxService
To read the last (latest) 10 log lines use:
sudo journalctl -u SampleLinuxService -n 10
One interesting thing to notice is that logs written to by service (to the console in our example) are available using the journalctl command.
The matter graceful shutdown
Services usually perform important tasks like reading data, storing stuff here, writing a record there and many more. We obviously don't want to abandon these tasks half-way and would like to stop the service cleanly.
The default code does not allow for clean shutdown, in fact there is no shutdown handler which can be used to stop exisiting execution, wait for their completion and then continue the service shutdown.
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
_logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
await Task.Delay(1000, stoppingToken);
}
}
We however can make use of the StopAsync virtual method of the BackgroundService, override it and implement a clean-shutdown mechanism. The Worker.cs class has code which does exactly this but not in a very clean way. The idea here is:
- We have two boolean variables _stop & _stopped both initialized to false.
- The main loop in the ExecuteAsync method monitors the value of _stop, if _stop is true, it starts its shutdown routine - a Thread.Sleep(5000) for now.
- The ExecuteAsync method sets _stopped to true once it has completed all its shutdown activities.
- The StopAsync method is the one that is called by the framework when a service stop command is requested.
- The StopAsync method then sets the _stop to true and waits until the _stopped variable is true.
The code for the two methods are below:
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
bool stop = false;
while (!stop)
{
_logger.LogInformation("ThreadID: {0} Worker running at: {1}", Thread.CurrentThread.ManagedThreadId, DateTimeOffset.Now);
await Task.Delay(1000, stoppingToken);
_logger.LogInformation("I woke up");
if (stoppingToken.IsCancellationRequested)
{
_logger.LogCritical("Cancellation is requested.");
Console.WriteLine("Waiting for {0}ms before stopping.", StopIntervalMS);
_logger.LogCritical("Waiting for {0}ms before stopping.", StopIntervalMS);
Thread.Sleep(StopIntervalMS);
stop = true;
}
if (_stop)
{
_logger.LogCritical("ThreadID: {0}, Stop signal has been set, cleaning up...", Thread.CurrentThread.ManagedThreadId);
Thread.Sleep(5000);
_logger.LogCritical("ThreadID: {0}, Finished cleaning up", Thread.CurrentThread.ManagedThreadId);
stop = true;
}
}
_stopped = true;
}
public override async Task StopAsync(CancellationToken cancellationToken)
{
_logger.LogCritical("ThreadID: {0}, In StopAsync(), Setting stop signal", Thread.CurrentThread.ManagedThreadId);
_stop = true;
while(_stopped != true)
{
_logger.LogCritical("ThreadID: {0}, In StopAsync(), waiting for task to cleanup...", Thread.CurrentThread.ManagedThreadId);
Thread.Sleep(1000);
}
_logger.LogCritical("ThreadID: {0}, In StopAsync(), cleapup complete detected", Thread.CurrentThread.ManagedThreadId);
await base.StopAsync(cancellationToken);
return;
}
The code illustrates how a clean-shutdown mechanism can be implemented. A cleaner implementation is attempted using the GracefulShutdownWorker class. This class encapsulates the implementation for the StopAsync method. The MyWorker class inherits GracefulShutdownWorker and queries the RequireStop property to know if it has to start its shutdown routine and finally sets the SafeToShutdown property to true which results in the service shutting down.
namespace SampleLinuxService
{
public abstract class GracefulShutdownWorker : BackgroundService
{
protected readonly ILogger<GracefulShutdownWorker> _logger;
protected volatile bool _stop = false;
private volatile bool _stopped = false;
public GracefulShutdownWorker(ILogger<GracefulShutdownWorker> logger)
{
_logger = logger;
}
public override async Task StopAsync(CancellationToken cancellationToken)
{
_logger.LogCritical("Setting stop signal");
_stop = true;
while (_stopped != true)
{
_logger.LogCritical("Waiting for cleanup to complete");
Thread.Sleep(_cleanupIntervalMS);
}
_logger.LogCritical("Cleapup complete detected");
await base.StopAsync(cancellationToken);
return;
}
protected bool RequireStop
{
get { return _stop; }
}
protected bool SafeToShutdown
{
get { return _stopped; }
set { _stopped = value; }
}
protected int _cleanupIntervalMS = 1000;
}
}
The MyWorker class which derives from the GracefulShutdownWorker class.
namespace SampleLinuxService
{
public class MyWorker : GracefulShutdownWorker
{
public MyWorker(ILogger<MyWorker> logger) : base(logger)
{
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
bool stop = false;
while (!stop)
{
_logger.LogInformation("ThreadID: {0} I am working at {1}", Thread.CurrentThread.ManagedThreadId, DateTimeOffset.Now);
await Task.Delay(1000, stoppingToken);
if (RequireStop)
{
_logger.LogCritical("ThreadID: {0}, Stop signal has been set, cleaning up...", Thread.CurrentThread.ManagedThreadId);
Thread.Sleep(5000);
_logger.LogCritical("ThreadID: {0}, Finished cleaning up", Thread.CurrentThread.ManagedThreadId);
stop = true;
}
}
SafeToShutdown = true;
}
public static int StopIntervalMS = 1000;
}
}
Source code
The source code for the blogpost is available at Github.
Conclusion
DotNetCore makes it quite easy to write Linux services. Using systemd package maps the logging levels of the DotNetCore logger to systemd logging and the logs showup as part of the service logs. We need to write a bit of extra code to handle clean service shutdowns but its always a good idea to do so.