Moving .NET Windows services to Linux with systemd

You don't need Kubernetes to get off Windows. A practical guide to running .NET background services under systemd, and the gotchas that bite during the move.

Plenty of .NET systems still run as Windows services on dedicated servers. Moving them to Linux cuts licensing costs and opens the door to containers later, but you don't have to jump straight to Kubernetes. systemd, the service manager on almost every Linux distribution, does the job well.

Make the service systemd-aware

Add the Microsoft.Extensions.Hosting.Systemd package and one line:

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSystemd();
builder.Services.AddWindowsService(); // keeps it working on Windows during the transition
builder.Services.AddHostedService<Worker>();
builder.Build().Run();

Both calls do nothing unless the app is actually running under that service manager, so the same build runs on Windows and Linux while you migrate.

Write the unit file

[Unit]
Description=Message worker
After=network-online.target

[Service]
Type=notify
WorkingDirectory=/opt/message-worker
ExecStart=/opt/message-worker/MessageWorker
User=message-worker
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
Environment=DOTNET_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

Type=notify means systemd waits until your app reports it has started, instead of assuming it's ready the moment the process launches. Run the service as its own user, never as root.

Gotchas we see every time

  • Paths and case sensitivity. C:\Data\Config.json and config.json don't exist on Linux. Use Path.Combine and match file name casing exactly.
  • Windows-only APIs. Registry access, the Windows Event Log, WMI and performance counters need replacing. Configuration moves to files or environment variables, logs go to standard output, where journald collects them.
  • Graceful shutdown. systemd sends SIGTERM and waits for TimeoutStopSec. Make sure your workers honour the cancellation token, or in-flight work gets cut off.
  • Time zones and culture. Linux servers usually run in UTC with invariant culture. Code that relied on the server's local time or number format will behave differently.
  • Native dependencies. Libraries that wrap Windows DLLs need a Linux alternative before you can move.

Then containers, if you need them

Once a service runs cleanly on Linux, packaging it in a Docker image and running it on Kubernetes is a small step. Doing it in two moves means each problem shows up on its own.

Dealing with this in your own system? We do this work for a living. The first call is free.

Book a call