---
applyTo: "Fuchs_DataService/**"
---

# Topshelf Instructions

## Overview
`Fuchs_DataService` uses **Topshelf 4.x** as the Windows Service host. The hosted jobs run inside a `PeriodicHostedService` (see `periodic_service.instructions.md`), which is managed by the Topshelf `FdsService` class.

## Structure

```
FdsMainModule.Main()
  └── HostFactory.Run()
        └── FdsService : ServiceControl
              ├── Start()  → _hostedService.StartAsync(_cts.Token)
              └── Stop()   → _cts.Cancel() + _hostedService.StopAsync()
```

## FdsService Rules
- `FdsService` owns a `CancellationTokenSource _cts` for cooperative cancellation.
- `FdsService` builds the `ILoggerFactory` (via `LoggerFactory.Create(b => b.AddFdsLogging())`) and passes it to all job objects.
- `FdsService` constructs `FdsMfr` directly: `new FdsMfr(loggerFactory.CreateLogger<FdsMfr>(), loggerFactory)`.
- `FdsService` constructs `PeriodicHostedService` with jobs and passes `loggerFactory.CreateLogger<PeriodicHostedService>()`.
- Never use the generic `Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder` pattern here — Topshelf manages the host lifetime.

## Topshelf Configuration
```csharp
HostFactory.Run(x =>
{
    x.Service<FdsService>(s =>
    {
        s.ConstructUsing(name => new FdsService());
        s.WhenStarted((tc, host) => tc.Start(host));
        s.WhenStopped((tc, host) => tc.Stop(host));
        s.WhenPaused((tc, host)    => tc.Stop(host));
        s.WhenContinued((tc, host) => tc.Start(host));
    });
    x.EnablePauseAndContinue();
    x.StartAutomatically();
    x.RunAsLocalSystem();
    x.SetDescription("MFR Data Sync");
    x.SetDisplayName("MFR Data Sync");
    x.SetServiceName("MFR Data Sync");
});
```

## Dev-Machine Shortcut
On machines named `digital-pc` or `digital-dpc` the service runs in-process (console) instead of installing as a Windows Service.

## Adding a New Job
Add a new `PeriodicJobDefinition` in `FdsService` constructor — see `periodic_service.instructions.md`.