Inhaltsverzeichnis

Runbook: Windows Service

Duration: ~15 minutes
Role: Windows Administrator
Prerequisite: Admin rights, .NET 8 Runtime

Install and manage Data Gateway as Windows Service.

Workflow

flowchart TD A[Start] --> B[Copy Gateway] B --> C[Register service] C --> D[Configure service] D --> E[Start service] E --> F[Health Check] F --> G{OK?} G -->|Yes| H[Done] G -->|No| I[Check Event Log] style H fill:#e8f5e9 style I fill:#ffebee

1. Install Gateway

# Create directory
New-Item -ItemType Directory -Path "%SERVICES_ROOT%\DataGateway" -Force
 
# Copy files
Copy-Item -Path ".\publish\*" -Destination "%SERVICES_ROOT%\DataGateway" -Recurse
 
# Adjust configuration
notepad "%SERVICES_ROOT%\DataGateway\appsettings.json"

2. Create Service with sc.exe

# Run as administrator
sc.exe create "DataGateway" `
    binPath= "%SERVICES_ROOT%\DataGateway\WvdS.WebAPI.Data.Gateway.Api.exe" `
    DisplayName= "WvdS Data Gateway" `
    start= auto `
    obj= "NT AUTHORITY\NETWORK SERVICE"
 
# Set description
sc.exe description "DataGateway" "REST/OData/GraphQL API Gateway for databases"

3. Create Service with NSSM (Alternative)

NSSM (Non-Sucking Service Manager) provides more control: 

# Download NSSM
Invoke-WebRequest -Uri "https://nssm.cc/release/nssm-2.24.zip" -OutFile "nssm.zip"
Expand-Archive -Path "nssm.zip" -DestinationPath "%TOOLS_PATH%"
 
# Install service
%TOOLS_PATH%\nssm-2.24\win64\nssm.exe install DataGateway "%SERVICES_ROOT%\DataGateway\WvdS.WebAPI.Data.Gateway.Api.exe"
 
# Configuration
nssm set DataGateway AppDirectory "%SERVICES_ROOT%\DataGateway"
nssm set DataGateway DisplayName "WvdS Data Gateway"
nssm set DataGateway Description "REST/OData/GraphQL API Gateway"
nssm set DataGateway Start SERVICE_AUTO_START
nssm set DataGateway AppStdout "%SERVICES_ROOT%\DataGateway\logs\stdout.log"
nssm set DataGateway AppStderr "%SERVICES_ROOT%\DataGateway\logs\stderr.log"
nssm set DataGateway AppRotateFiles 1
nssm set DataGateway AppRotateBytes 10485760

4. Start Service

# Start
Start-Service -Name "DataGateway"
 
# Check status
Get-Service -Name "DataGateway"
 
# Stop
Stop-Service -Name "DataGateway"
 
# Restart
Restart-Service -Name "DataGateway"

5. Configure Auto-Start

# Auto-start on system boot
Set-Service -Name "DataGateway" -StartupType Automatic
 
# Delayed start (after network)
sc.exe config "DataGateway" start= delayed-auto
 
# Recovery options (restart on crash)
sc.exe failure "DataGateway" reset= 86400 actions= restart/60000/restart/60000/restart/60000

6. Health Check

# Wait until service ready
Start-Sleep -Seconds 5
 
# Health Check
$response = Invoke-WebRequest -Uri "http://localhost:5000/health" -UseBasicParsing
if ($response.StatusCode -eq 200) {
    Write-Host "Gateway running!" -ForegroundColor Green
} else {
    Write-Host "Gateway problem!" -ForegroundColor Red
    Get-EventLog -LogName Application -Source "DataGateway" -Newest 10
}

7. Checklist

# Check Done
———-——
1 Files in %SERVICES_ROOT%\DataGateway [ ]
2 appsettings.json configured [ ]
3 Service registered [ ]
4 Service started [ ]
5 Health Check successful [ ]
6 Auto-start active [ ]
7 Recovery configured [ ]

Troubleshooting

Problem Cause Solution
—————-———-
Service won't start Missing .NET Runtime Check dotnet –info
Access denied Missing permissions Install as Admin
Port already in use Other process netstat -ano | findstr 5000
Config error JSON syntax Validate appsettings.json

Check Event Log: 

Get-EventLog -LogName Application -Source "DataGateway" -Newest 20 | Format-Table TimeGenerated, EntryType, Message -Wrap

Remove Service

# Stop
Stop-Service -Name "DataGateway" -Force
 
# Remove
sc.exe delete "DataGateway"
 
# Delete files (optional)
Remove-Item -Path "%SERVICES_ROOT%\DataGateway" -Recurse -Force

« <- Automation | -> systemd »

Wolfgang van der Stille @ EMSR DATA d.o.o. - Data Gateway Professional

, , ,