Installation und Betrieb
Zuletzt geändert: 18.07.2026 15:19

Installation und Betrieb #

Der API-Server läuft auf http.sys (System.Net.HttpListener) - ohne IIS genauso wie neben einem IIS: http.sys routet Requests nach Hostname (SNI), beide teilen sich denselben Port 443, und die Zertifikate kommen aus dem Windows-Speicher (auch die von IIS bzw. Win-ACME installierten).

Schnellstart (nur LAN, ohne Einrichtung) #

Import-Module EulandaXrest
Invoke-XrestMigration -ConnStr '...Admin-Verbindung...'   # einmalig, braucht DDL-Rechte
Start-XrestServer -Udl 'C:\Eulanda\Mandant.udl'           # bindet nur http://localhost:8100/

Betrieb mit Hostname und HTTPS (auch neben IIS) #

Einmalige Einrichtung in einer Administrator-Konsole - der Befehl sucht das Zertifikat für den Hostnamen selbst im Speicher LocalMachine\My:

Install-XrestServer -HostName api.kunde.de -Port 443 -Https -Execute

Ohne -Execute werden die netsh-Befehle nur angezeigt (zum Prüfen oder für die manuelle Ausführung):

netsh http add urlacl url=https://api.kunde.de:443/ user="DOMAIN\Konto"
netsh http add sslcert hostnameport=api.kunde.de:443 certhash=<THUMBPRINT> appid={b4e8f2c6-7a1d-4c3e-9b5f-0d8a2c6e4f13} certstorename=MY

Die hostnameport-Bindung (SNI) lässt vorhandene IIS-Bindungen auf demselben Port unangetastet; der Hostname darf nur nicht zusätzlich als IIS-Bindung existieren. Danach:

Start-XrestServer -Udl 'C:\Eulanda\Mandant.udl' -HostName api.kunde.de -Https -Port 443

Fehlt die TLS-Bindung, bricht der Start mit dem fertigen Einrichtungs-Befehl ab. Zertifikats-Verlängerung läuft über den vorhandenen IIS-/Win-ACME-Bestand - nach einem Zertifikatswechsel die sslcert-Bindung mit dem neuen Thumbprint erneuern (netsh http delete sslcert hostnameport=... + Install-XrestServer ... -Execute).

Ohne IIS und ohne Hostnamen geht auch eine Bindung auf alle Interfaces (-BindAny); für HTTPS übernimmt dann eine ipport-Bindung das TLS.

Health-Check und Watchdog #

Test-XrestHealth -Url 'https://api.kunde.de'          # Ergebnisobjekt
Test-XrestHealth -Url 'https://api.kunde.de' -Quiet   # $true/$false

curl.exe "https://api.kunde.de/api/v1/health"

Unbeaufsichtigter Betrieb (Aufgabenplanung + Watchdog) #

# Server als Aufgabe: startet bei der Benutzeranmeldung, bei Absturz bis
# zu 3 automatische Neustarts; mit -AtStartup schon beim Hochfahren als
# SYSTEM (Anlage dann in einer Admin-Konsole, UDL mit SQL-Anmeldung nutzen)
Register-XrestServerTask -Udl 'C:\Eulanda\Mandant.udl' -HostName api.kunde.de -Https -Port 443

# Watchdog alle 5 Minuten: Health-Check, bei Ausfall EventLog-Meldung
# (Source EulandaXrest, EventIds 7101-7105) und Neustart über die
# Server-Aufgabe; räumt zusätzlich xrest.RequestLog (90 Tage),
# xrest.IdempotencyKey (30 Tage) und die Tages-Logdateien (365 Tage) auf
Register-XrestWatchdogTask -Url 'https://api.kunde.de' -Udl 'C:\Eulanda\Mandant.udl'

# Steuern wie jede Windows-Aufgabe:
Start-ScheduledTask -TaskName EulandaXrest-Server
Stop-ScheduledTask  -TaskName EulandaXrest-Server
Unregister-XrestServerTask
Unregister-XrestWatchdogTask

# Ein Watchdog-Lauf von Hand (liefert das Ergebnisobjekt):
Invoke-XrestWatchdog -Url 'https://api.kunde.de' -Udl 'C:\Eulanda\Mandant.udl'

Die EventLog-Source EulandaXrest legt Install-XrestServer -Execute mit an; ohne Source fällt der Watchdog auf Konsolen-Warnungen zurück.

Logs #

  • Datei: logs\xrest-JJJJMMTT.log (JSON-Lines, eine Zeile je Request)
  • Datenbank: xrest.RequestLog (Audit mit Client, Status, Dauer, Korrelations-Id)
  • Jede Antwort trägt X-Correlation-Id - bei Supportfragen mit angeben.