Turning a Console App into a Windows Service with Topshelf

For many Australian software teams, a console application begins as a quick utility — a script that polls a queue, indexes some files, or processes a nightly batch. Once that same logic must run reliably on a Windows server at three in the morning AEST, the limitations surface: no automatic restart on failure, no clean integration with the Windows Event Log, no friendly name for a sysadmin to find in the Services console. Converting to a Windows service addresses these weaknesses, but the classical .NET ServiceBase path can be heavy. Topshelf sits in the middle — you keep a normal Main method and ship a process that behaves like a first-class service.

This walkthrough assumes Windows 10 or Windows Server 2019, either .NET Framework 4.8 or .NET 6. Topshelf's classic package leans toward .NET Framework, which suits many Australian line-of-business applications. By the end you will have a console application that runs as a console when launched directly and as a service when installed, with minimal restructuring of existing code.

When a console app falls short

Console applications execute inside an interactive session. That suits developers and Task Scheduler jobs, but it creates awkward situations in production. The process has no lifecycle management — a power blip simply kills it and leaves it dead. There is no canonical way to expose a friendly service name, description or recovery actions, and any console output disappears once the process runs unattended. An unhandled exception tends to take the entire process down with it.

In Australia, large retailers in Sydney and Melbourne, government agencies in Canberra, and banks in Brisbane often work to hardening standards informed by the Essential Eight maturity model. A standalone console process has difficulty meeting expectations around automated startup, controlled execution accounts and central logging. The Privacy Act 1988 and the Notifiable Data Breaches scheme also shape how logs are stored, rotated and audited, which pushes teams toward a hosting wrapper that integrates with Event Log rather than ad-hoc text files.

Topshelf addresses most of these gaps by layering a small framework over System.ServiceProcess.ServiceBase. Instead of writing a service class with OnStart and OnStop overrides that only run inside the service host, you keep a normal Program.Main, call HostFactory.Run and let Topshelf wire the rest. The table below compares the two approaches side by side.

The result is identical debug behaviour for developers and real service semantics in production — a balance that has earned Topshelf a following in Australian integration consultancies.

Introducing Topshelf and the HostFactory model

Topshelf is published on NuGet as Topshelf and is an opinionated thin wrapper around ServiceBase. Once referenced, you create a service configuration by calling HostFactory.New and chaining configuration calls. The configuration declares a service name, a display name, a description, the executing account and at least one service implementation. That implementation supplies Start and Stop methods — plain methods you control — instead of overrides on a base class.

If your team has standardised on Microsoft.Extensions.Hosting for new .NET 6 services, you might ask whether Topshelf still fits. The honest answer is that Topshelf shines on .NET Framework projects and on shops that prefer minimal surface area. Many Australian software houses maintain framework applications — especially those integrating with on-prem systems in healthcare, retail and utilities — and that is where Topshelf remains a comfortable choice. For greenfield .NET 6 work, an IHostedService background worker is usually the better answer.

Install Topshelf with Install-Package Topshelf in the NuGet Package Manager, or dotnet add package Topshelf for SDK-style projects. Pair it with one of Topshelf's logging helpers so the host can write to the Event Log directly.

Setting up the project

Start with a .NET Framework console application named, say, EmailDispatcher. The existing Program.cs usually contains a tight Main loop. Open the Package Manager Console and install Topshelf. Target the same .NET Framework version your other libraries already use — there is no advantage in bumping 4.5 code to 4.8 just for this migration.

Packages most teams end up referencing:

• Topshelf — the core service host
• Topshelf.Log4Net — pluggable logging via Log4Net
• Topshelf.NLog — alternative logging adapter
• Topshelf.SysV — for cross-platform experiments on Linux

If you maintain the project across Victoria and Western Australia, think about where the binary will live — shared between regions through a DevOps artefact, or built independently for each state. Either approach works because the installer is just an executable flag, and the executable itself is region-agnostic.

Writing the service code

The migration leaves most of your business logic untouched; only the entry point changes. The new Program.cs reduces to a single HostFactory.New call that registers the service, sets the display name and description, configures the start mode, and binds Start and Stop to methods on a plain class.

Inside EmailDispatcherService.cs, implement Start and Stop directly. The Start method might spin up a System.Threading.Timer that polls a queue every thirty seconds; the Stop method cancels the timer and waits briefly for any in-flight work to finish. Because the service runs under the Service Control Manager rather than an interactive desktop, you do not need to worry about losing UI state when a session logs off.

A practical habit for Australian teams is to set the service account explicitly during configuration rather than relying on LocalSystem. From Brisbane to Perth, customers often request a dedicated service account aligned with their Active Directory structure, particularly when the service reads from network shares or writes to a confidential database. Topshelf makes this straightforward: RunAs(username, password) accepts the credentials, and DependsOn("mssql$MAIN_INSTANCE") declares dependencies on SQL Server or message-queue services so startup ordering is correct.

Installation and lifecycle management

Once compiled, the same executable behaves differently depending on how it is invoked. Launching EmailDispatcher.exe with no arguments runs the host in console mode — breakpoints work, Console.WriteLine output appears, and any exception lands in the terminal. Launching it with install registers it with the Service Control Manager, and uninstall removes it.

Operations teams in Melbourne and Sydney typically rely on a short set of commands:

• EmailDispatcher.exe install — register the service
• EmailDispatcher.exe start — start after installation
• EmailDispatcher.exe stop / uninstall — decommission cleanly
• sc query EmailDispatcher — verify the state from another host

Configuration can be passed in at install time using the syntax described in the Topshelf documentation, for example -displayname "Email Dispatcher" -description "Sends queued outbound mail". This is convenient when the same artefact is deployed to staging and production with slightly different names.

Logging, monitoring and recovery

By default, Topshelf writes to the console and a log file, but production deployments generally want structured entries in the Windows Event Log. Wiring this up involves adding Topshelf's logging helpers in the host configuration and supplying a SourceName that matches a registry entry created during an elevated install. Most automated deployment pipelines in Australian shops include a small PowerShell step that provisions the event source before the service is installed.

For recovery actions, Topshelf supports first-failure, second-failure and subsequent-failure responses such as restart, run a program, or reboot the machine. A pragmatic pattern is to restart on the first two failures and run a small diagnostic on the third, with an alert raised through whatever monitoring platform the customer uses — whether Datadog, New Relic, or a home-grown Grafana stack on AWS Sydney (ap-southeast-2) or Azure Australia East.

Privacy deserves a quick mention here. Any log line that contains personal information interacts with the Australian Privacy Principles, particularly APP 11 (security of personal information). Truncate or hash identifiers in Event Log output, and configure log retention to align with the agency's records management policy rather than indefinitely.

Running services in Australian environments

A few practicalities come up repeatedly in this part of the world. Time-zone handling is one — many scheduled jobs target business hours in Sydney or Melbourne rather than UTC, which means a job that should run at 08:00 local can drift during the AEDT-to-AEST switch if it relies on DateTime.Now. Topshelf services run in whatever time zone the host machine is configured for, so set this explicitly at deployment time, or store timestamps in UTC and convert when presenting.

Hosting choices also matter. Public cloud regions in Australia include AWS Sydney and Melbourne, Azure Australia Central, and Azure Australia East, and government customers may require that their data remain onshore. The Australian Government Cloud Policy and the hosting certification framework (IRAP) influence whether a service can run in a public hyperscaler, a certified cloud, or an on-premises data centre in Canberra. Topshelf runs equally well in all three; only the install scripts differ.

Daylight saving in Tasmania, New South Wales, Victoria, South Australia and the ACT means that jobs touching local calendars need extra care. While Topshelf itself is Windows-only, the same business logic can later be lifted into a Worker Service on .NET 6 for customers who want to modernise toward cross-platform hosting. That flexibility — write once, deploy anywhere from Perth to Parramatta — is why this compact tool still earns a place in a migration toolbox.