HostAvailabilityMonitor/Dokumentation.md

Dokumentation – Host Availability Monitor (.NET Framework 4.8)

1. Zielbild

Die Anwendung überwacht auf einem Windows Server 2019 in festen Intervallen die netzwerktechnische Verfügbarkeit definierter Ziele. Typische Einsatzzwecke:

• interne Fileshares
• externe HTTPS-Endpunkte
• SFTP-Gegenstellen
• TCP-Dienste
• Hosts per Ping

Der Betrieb erfolgt typischerweise über den Windows Task Scheduler alle 30 Minuten.

2. Unterstützte Zieltypen

2.1 UNC / SMB

Beispiel:

\\internerserver1\share1

Verhalten:

1. TCP-Check auf Port 445 (oder überschriebenen Port)
2. Optional zusätzliche Pfadvalidierung mit Directory.Exists(...) / File.Exists(...)

Hinweis:

• ValidateUncPathAccess=false ist robuster, wenn es nur um Erreichbarkeit geht.
• ValidateUncPathAccess=true ist strenger, weil Berechtigungen, Namensauflösung und tatsächlicher Share-Zugriff geprüft werden.

2.2 HTTP / HTTPS

Beispiele:

https://host1.de/url
http://intranet.local/health

Verhalten:

• Standardmäßig HEAD
• Fallback auf GET, wenn HEAD nicht unterstützt wird (405 / 501) oder der HEAD-Request fehlschlägt
• Jede empfangene HTTP-Antwort zählt als netzwerktechnisch erreichbar

2.3 SFTP

Beispiel:

sftp://partner.example.local/inbound

Verhalten:

• TCP-Port-Prüfung, standardmäßig Port 22
• kein Login, keine Dateioperation

2.4 TCP

Beispiel:

tcp://host2.example.local:8443

Verhalten:

• reiner Verbindungsaufbau auf dem Zielport

2.5 ICMP

Beispiel:

icmp://server01

Verhalten:

• Ping über System.Net.NetworkInformation.Ping

2.6 Plain Hostnames

Beispiele:

server01
partner-gateway

Verhalten:

• wenn Port gesetzt ist: TCP-Check
• wenn kein Port gesetzt ist: ICMP-Check

3. Konfigurationsmodell

Die Konfiguration erfolgt in appsettings.json.

3.1 Runtime

Feld	Bedeutung
MaxConcurrency	Maximale parallele Checks
DefaultValidateUncPathAccess	Default für UNC-Pfadzugriffsprüfung
NonZeroExitCodeOnAnyFailure	Exit Code 2 bei mindestens einem fehlgeschlagenen Check
NonZeroExitCodeOnExecutionError	Exit Code 1 bei technischen Fehlern
StateDirectory	Verzeichnis für Statusdatei

3.2 Logging

Feld	Bedeutung
LogDirectory	Verzeichnis der Logdateien
FilePrefix	Präfix des Tageslogs
RetentionDays	Anzahl Tage zur Aufbewahrung

3.3 EventLog

Feld	Bedeutung
Enabled	Aktiviert Event Log
LogName	Standard: Application
Source	Event Source
CreateSourceIfMissing	Optionaler Versuch, die Source anzulegen
WriteSuccessEntries	Erfolgreiche Einzelchecks schreiben
WriteSummaryEntries	Laufzusammenfassung schreiben

3.4 Email

Feld	Bedeutung
Enabled	Aktiviert SMTP-Benachrichtigung
SmtpHost / SmtpPort	SMTP-Ziel
UseSsl	SSL/TLS für SMTP
Username / Password	Optionale Credentials
From	Absender
To	Empfängerliste
SubjectPrefix	Präfix im Betreff
SendOnFailure	Mail bei Fehler
SendOnRecovery	Mail bei Wiederherstellung
OnlyOnStateChange	Nur bei Statuswechsel
CooldownMinutes	Minimaler Abstand zwischen Benachrichtigungen
TimeoutSeconds	SMTP-Timeout

3.5 Targets

Feld	Bedeutung
Name	Anzeigename
Endpoint	UNC, URL, SFTP, TCP, ICMP oder Hostname
TimeoutSeconds	Timeout je Ziel
Port	Optionaler Zielport
ValidateUncPathAccess	Optional pro UNC-Ziel
HttpMethod	HEAD oder GET
Enabled	Ziel aktiv/inaktiv

4. Logging-Verhalten

4.1 Dateilog

Pro Tag entsteht genau eine Logdatei:

logs\host-availability-monitor-2026-04-16.log

Format:

2026-04-16 08:00:00.123 +02:00 | INFO | Lauf gestartet.
2026-04-16 08:00:00.532 +02:00 | SUCCESS | Name=Externe Webseite | Kind=Https | Endpoint=https://host1.de/url | DurationMs=278 | Status=Reachable | Detail=HTTP-Antwort erhalten (200 OK). | Host=host1.de | Port=443 | HttpStatus=200
2026-04-16 08:00:01.003 +02:00 | FAIL | Name=SFTP Partner A | Kind=Sftp | Endpoint=sftp://partner.example.local/inbound | DurationMs=10005 | Status=Unreachable | Detail=TCP-Verbindung fehlgeschlagen: A connection attempt failed... | Host=partner.example.local | Port=22 | ErrorType=SocketException

4.2 Retention

Beim Start eines Laufs werden alte Tageslogs bereinigt.

Standard:

• aktueller Tag + 4 vorherige Tage bleiben erhalten
• ältere Logs werden gelöscht

5. Event Log

Es wird in das Windows Application Event Log geschrieben.

Typische Events:

• Fehler bei Einzelchecks: Warning
• technische Fehler: Error
• Laufzusammenfassung: Information oder Warning

Wichtig:

• Das Erzeugen einer Event Source benötigt erhöhte Rechte.
• Im produktiven Betrieb sollte die Source einmalig per Skript registriert werden.
• Falls Event Log nicht verfügbar ist, fällt die Anwendung auf Dateilogging zurück und läuft weiter.

6. Benachrichtigungslogik

Die Anwendung speichert je Ziel einen Status in state\monitor-state.json.

Gespeicherte Informationen pro Ziel:

• IsUp
• ConsecutiveFailures
• LastCheckedUtc
• LastChangedUtc
• LastNotificationUtc
• LastDetail

6.1 Benachrichtigung bei Fehler

Es wird benachrichtigt, wenn:

• Email.Enabled=true
• SendOnFailure=true
• das Ziel aktuell fehlschlägt
• und je nach Einstellung entweder
  • ein Statuswechsel vorliegt oder
  • der Cooldown abgelaufen ist

6.2 Benachrichtigung bei Recovery

Es wird benachrichtigt, wenn:

• Email.Enabled=true
• SendOnRecovery=true
• das Ziel aktuell erfolgreich ist
• und der vorherige bekannte Zustand down war

6.3 Anti-Spam

Mit OnlyOnStateChange=true werden bei Dauerfehlern nicht bei jedem Lauf erneut Mails versendet.

Mit CooldownMinutes > 0 kann zusätzlich ein Zeitfenster definiert werden.

7. Exit Codes

Exit Code	Bedeutung
0	Lauf erfolgreich abgeschlossen
1	technischer Fehler / Konfigurations- oder Laufzeitproblem
2	mindestens ein Ziel fehlgeschlagen und NonZeroExitCodeOnAnyFailure=true

8. Task Scheduler Empfehlung

8.1 Allgemein

• Trigger: alle 30 Minuten
• Benutzerkonto: dediziertes Servicekonto, falls UNC-Zugriffe Berechtigungen benötigen
• "Start in": Installationsverzeichnis setzen

8.2 Beispiel

Aktion

• Program/script:

C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe

• Add arguments:

C:\Tools\HostAvailabilityMonitor\appsettings.json

• Start in:

C:\Tools\HostAvailabilityMonitor

9. Betriebshinweise

9.1 UNC-Prüfung

Wenn echte Share-Verfügbarkeit geprüft werden soll:

• Task mit geeignetem Servicekonto ausführen
• ValidateUncPathAccess=true für das betreffende Ziel setzen

Wenn nur der Zielserver bzw. SMB-Port relevant ist:

• ValidateUncPathAccess=false belassen

9.2 HTTP/HTTPS

Die Anwendung prüft Erreichbarkeit, nicht Business-Logik. Für Applikations-Health kann eine dedizierte Health-URL sinnvoller sein.

9.3 SFTP

Da nur der Port geprüft wird, eignet sich der Check für "Ist die Gegenstelle erreichbar?", nicht für "Kann ich mich anmelden und Dateien lesen?".

9.4 TLS

Die Anwendung aktiviert zusätzlich gängige SecurityProtocol-Werte, damit HTTPS-Ziele in älteren .NET-Framework-Umgebungen robuster funktionieren.

10. Build und Deployment

10.1 Voraussetzungen

• Windows Build Host
• Visual Studio oder Build Tools mit MSBuild
• .NET Framework 4.8 Targeting/Developer Pack

10.2 Build

msbuild .\HostAvailabilityMonitor.sln /p:Configuration=Release /p:Platform="Any CPU"

10.3 Artefakte

Relevant für Deployment:

• HostAvailabilityMonitor.exe
• HostAvailabilityMonitor.exe.config
• appsettings.json
• weitere referenzierte .NET-Assemblies aus bin\Release

11. Sicherheits- und Resilienz-Aspekte

Die Anwendung ist bewusst defensiv aufgebaut:

• Fehler einzelner Checks stoppen nicht den Gesamtlauf
• Event Log Ausfälle führen nicht zum Abbruch
• Statusdatei wird atomar aktualisiert
• Log-Bereinigung blockiert den Lauf nicht
• Mailversand markiert Benachrichtigungen nur bei echtem Erfolg

12. Empfohlene nächste Ausbaustufen

Optional könnte das Projekt später erweitert werden um:

• CSV- oder HTML-Report pro Lauf
• pro Target eigene Empfängergruppen
• zusätzliche Protokolle wie FTP oder LDAP-Portchecks
• Performance Counter oder Windows Service statt Task Scheduler
• Gitea CI-Workflow für Windows Runner