HostAvailabilityMonitor/Dokumentation.md

Dokumentation

Überblick

Dieses Repository ist für den Betrieb in einer Gitea-Repo-Struktur vorbereitet und enthält zwei Anwendungen:

1. HostAvailabilityMonitor

Der Monitor prüft technische Erreichbarkeit und schreibt:

• Rolling-Dateilog
• Windows Application Event Log
• E-Mail-Benachrichtigungen bei Ausfall, Recovery und täglichem Status
• Statusdatei für Zustandswechsel, Cooldown-Logik und die tägliche Summary-Mail
• optional statische HIP-VM-Prüfungen aus hip-vms.json für Netzwerk/Ping und RDP/TCP 3389

2. BizTalkMonitorConfigGenerator

Der Generator liest BizTalk-Artefakte aus und erzeugt daraus eine Monitor-Konfiguration.

Ziel ist, dass die Ziel-Liste nicht manuell gepflegt werden muss, sondern direkt aus BizTalk stammt.

---

Repository-Struktur für Gitea

.
├── .editorconfig
├── .gitignore
├── Documentation.en.md
├── Dokumentation.md
├── HostAvailabilityMonitor.sln
├── README.md
├── installers/
│   ├── README.md
│   ├── powershell/
│   │   ├── Install-BizTalkMonitorConfigGenerator.ps1
│   │   ├── Install-Both.ps1
│   │   ├── Install-HostAvailabilityMonitor.ps1
│   │   ├── Uninstall-BizTalkMonitorConfigGenerator.ps1
│   │   └── Uninstall-HostAvailabilityMonitor.ps1
│   └── wix/
│       ├── BizTalkMonitorConfigGenerator.wxs
│       ├── HostAvailabilityMonitor.wxs
│       └── build-msi.ps1
├── scripts/
│   ├── build-release.ps1
│   ├── generate-monitor-config.ps1
│   ├── install-generator-on-server.ps1
│   ├── install-on-server.ps1
│   ├── package-deployment.ps1
│   └── register-event-source.ps1
└── src/
    ├── BizTalkMonitorConfigGenerator/
    │   ├── App.config
    │   ├── BizTalkMonitorConfigGenerator.csproj
    │   ├── Program.cs
    │   └── generator-settings.json
    └── HostAvailabilityMonitor/
        ├── App.config
        ├── HostAvailabilityMonitor.csproj
        ├── Program.cs
        ├── appsettings.json
        └── hip-vms.json

Diese Struktur ist für ein normales Gitea-Repository ausgelegt. Build und Deployment können aus der Solution oder projektweise erfolgen.

---

Unterstützte BizTalk-Quellen

Send Ports

Es werden standardmäßig nur gestartete Send Ports übernommen.

Zusätzlich kann optional auch der Secondary Transport eines Send Ports berücksichtigt werden. Secondary Transports mit dem Adapter SMTP werden jedoch bewusst nicht als Monitor-Target übernommen, weil deren Address-Wert in BizTalk typischerweise nur eine Empfängerliste und keine prüfbare Netzwerkadresse darstellt.

Receive Locations

Es werden standardmäßig nur aktivierte Receive Locations übernommen.

---

Endpunkt-Normalisierung

Der Generator versucht, BizTalk-Adressen in Monitor-kompatible Endpunkte zu überführen.

Direkt unterstützt

• \\server\share
• file://...
• http://...
• https://...
• ftp://...
• sftp://...
• tcp://...
• icmp://...
• rdp://...
• Plain Host / Host:Port (best effort)

Spezielle Behandlung

• net.tcp://host:port/... wird auf tcp://host:port/... umgeschrieben
• lokale Dateipfade wie C:\Drop\In werden nur übernommen, wenn IncludeLocalFilePaths=true
• net.pipe://... wird übersprungen, weil der Monitor diesen Typ nicht prüft

---

HostAvailabilityMonitor: Mail- und Statusverhalten

Der Monitor kann drei Arten von Mail-Benachrichtigungen versenden:

1. Failure-Mail: wenn ein Endpoint von erreichbar auf nicht erreichbar wechselt
2. Recovery-Mail: wenn ein Endpoint von nicht erreichbar auf wieder erreichbar wechselt
3. Tagesstatus-Mail: einmal pro Tag ab einer konfigurierten lokalen Uhrzeit, standardmäßig 14:00 Uhr

Die Tagesstatus-Mail wird absichtlich nicht über einen zweiten Task oder separaten Scheduler innerhalb der Anwendung realisiert.

Stattdessen gilt:

• der normale geplante Task startet die Anwendung wie bisher
• die Anwendung prüft bei jedem Lauf, ob die konfigurierte Uhrzeit bereits erreicht ist
• die erste Ausführung ab dieser Uhrzeit verschickt die Tagesstatus-Mail
• pro Kalendertag wird maximal eine Tagesstatus-Mail gesendet
• nur ein erfolgreich versendeter Tagesstatus wird im State gespeichert

Das ist robust für den Betrieb auf BizTalk-Servern, weil keine zusätzliche Orchestrierung erforderlich ist.

---

Konfiguration des Monitors im Detail

Datei: src\HostAvailabilityMonitor\appsettings.json

Root-Felder

• ApplicationName: Name des Monitors
• EnvironmentName: Umgebungsname wie HIP Produktion
• Runtime: Laufzeitverhalten
• Logging: Dateilog-Konfiguration
• EventLog: Windows Event Log Konfiguration
• Email: SMTP- und Benachrichtigungskonfiguration
• HipVirtualMachines: optionale statische VM-Prüfungen
• Targets: die zu prüfenden Endpunkte

Email

Wichtige Felder im Abschnitt Email:

• Enabled: Mailversand insgesamt ein/aus
• SmtpHost, SmtpPort, UseSsl, UseDefaultCredentials, Username, Password
• From, To, Cc, Bcc, SubjectPrefix
• SendOnFailure: Mail bei Ausfall senden
• SendOnRecovery: Mail bei Recovery senden
• SendDailySummary: tägliche Status-Mail senden
• DailySummaryHourLocal: lokale Stunde des Servers, z. B. 14
• DailySummaryMinuteLocal: lokale Minute des Servers, z. B. 0
• OnlyOnStateChange: bei Failure-/Recovery-Mails nur auf Zustandswechsel reagieren
• CooldownMinutes: Cooldown für wiederholte Failure-Mails, wenn OnlyOnStateChange=false
• TimeoutSeconds: SMTP-Timeout

Hinweise zu Empfaengern:

• To, Cc und Bcc sind jeweils JSON-Arrays von Mailadressen.
• Mehrere Empfaenger werden ueber mehrere Array-Eintraege konfiguriert.
• Eine einzelne Zeichenkette mit Semikolon-Liste ist nicht vorgesehen.
• Mindestens ein Empfaenger in To, Cc oder Bcc muss vorhanden sein, wenn Email.Enabled=true.

Beispiel für den Email-Block

"Email": {
  "Enabled": true,
  "SmtpHost": "smtp.example.local",
  "SmtpPort": 25,
  "UseSsl": false,
  "UseDefaultCredentials": false,
  "Username": "",
  "Password": "",
  "From": "monitor@example.local",
  "To": [
    "operations@example.local",
    "integration-oncall@example.local"
  ],
  "Cc": [
    "integration-leads@example.local"
  ],
  "Bcc": [],
  "SubjectPrefix": "[HostAvailabilityMonitor]",
  "SendOnFailure": true,
  "SendOnRecovery": true,
  "SendDailySummary": true,
  "DailySummaryHourLocal": 14,
  "DailySummaryMinuteLocal": 0,
  "OnlyOnStateChange": true,
  "CooldownMinutes": 0,
  "TimeoutSeconds": 30
}

Beispiel fuer mehrere Empfaenger

"Email": {
  "Enabled": true,
  "From": "monitor@example.local",
  "To": [
    "operations@example.local",
    "integration-oncall@example.local"
  ],
  "Cc": [
    "integration-leads@example.local"
  ],
  "Bcc": [
    "audit@example.local"
  ]
}

Inhalt der Tagesstatus-Mail

Die Tagesstatus-Mail enthält:

• Monitorname
• Umgebung
• Servername
• Zeitfenster von Mitternacht bis Versandzeitpunkt
• Anzahl heutiger erfolgreicher und fehlgeschlagener Checks laut Tageslog
• aktueller Snapshot des letzten Monitor-Laufs
• Liste aktuell DOWN befindlicher Endpunkte inklusive:
  • Anwendung
  • Name
  • Endpoint
  • Typ
  • Status
  • Detail
  • Host/Port/HTTP-Status, soweit vorhanden
• HIP-VM-Snapshot mit Netzwerk- und RDP-Status pro VM, wenn HipVirtualMachines.Enabled=true

Hinweis:

Die Tageszähler werden aus dem heutigen Rolling-Log ausgewertet. Sollte diese Auswertung ausnahmsweise fehlschlagen, bleibt die Mail-Funktion funktionsfähig; die Tageszähler werden dann defensiv mit 0 angegeben und der Vorfall wird geloggt.

---

HIP-VM-Monitoring

Die HIP-VMs werden bewusst in einer eigenen Datei gepflegt:

src\HostAvailabilityMonitor\hip-vms.json

Damit bleiben sie unabhängig von den durch den BizTalk-Generator neu erzeugten Targets. Änderungen an BizTalk-Sendports oder Receive Locations überschreiben diese statische VM-Liste nicht.

Aktiviert wird die Erweiterung in appsettings.json:

"HipVirtualMachines": {
  "Enabled": true,
  "ConfigPath": "hip-vms.json",
  "ApplicationName": "HIP Virtual Machines",
  "TimeoutSeconds": 5,
  "RdpPort": 3389,
  "CheckNetwork": true,
  "CheckRdp": true
}

Die Datei hip-vms.json enthält pro VM Gruppe, Namen, Adresse, Beschreibung und Aktivstatus. Beim Start erzeugt der Monitor daraus normale Targets:

• Network: icmp://<adresse> für Ping/Netzwerk-Konnektivität
• RDP: rdp://<adresse>:3389 für TCP-Konnektivität zum RDP-Dienst

Diese Targets nutzen dieselbe State-Datei wie alle anderen Checks. Dadurch werden verlorene Netzwerk- oder RDP-Erreichbarkeit und spätere Recoveries automatisch in den normalen Failure-/Recovery-Mails gemeldet. Im Dateilog und Event Log werden zusätzlich Quelle, Gruppe, Maschine und Check-Typ geschrieben.

---

Generator-Konfiguration im Detail

Datei: generator-settings.json

Root-Felder

• GeneratorName: Anzeigename für Logs/Eventlog des Generators
• EnvironmentName: Umgebung wie HIP Produktion
• Logging: Logging des Generators
• EventLog: Eventlog des Generators
• BizTalk: Discovery-Regeln
• Output: Zielpfad und Erzeugungsregeln
• GeneratedMonitorConfig: Vorlage für die endgültige Monitor-JSON

BizTalk

• ConnectionString: Verbindung zur BizTalkMgmtDb
• IncludeSendPorts: Send Ports auslesen
• IncludeReceiveLocations: Receive Locations auslesen
• OnlyStartedSendPorts: nur aktive Send Ports
• OnlyEnabledReceiveLocations: nur aktive Receive Locations
• IncludeSecondaryTransportOnSendPorts: sekundäre Send-Port-Transporte zusätzlich aufnehmen
• SMTP-Sendports bzw. SMTP-Secondary-Transports werden vom Generator automatisch übersprungen
• IncludeDynamicSendPorts: dynamische Send Ports aufnehmen
• IncludeLocalFilePaths: lokale Pfade aufnehmen
• IgnoreSystemApplications: Systemanwendungen ignorieren
• IgnoreApplications: Anwendungen per Pattern ausblenden
• IgnoreArtifactNamePatterns: Ports/Locations per Pattern ignorieren
• ApplicationMappings: Mapping BizTalk-App -> fachliche App
• ArtifactMappings: Mapping einzelner Artefakte -> fachliche App

Output

• Path: Pfad der erzeugten Monitor-JSON
• OverwriteExisting: bestehende Datei überschreiben
• FailIfNoTargetsFound: ExitCode 2, wenn keine Targets gefunden wurden
• TargetTimeoutSeconds: Standard-Timeout pro generiertem Target
• TargetEnabled: Enabled-Default in jedem Target
• DefaultHttpMethod: Standard für generierte HTTP/HTTPS-Ziele

GeneratedMonitorConfig

Dies ist die Vorlage für den späteren Monitor.

Hier werden gepflegt:

• ApplicationName des Monitors
• EnvironmentName
• Runtime
• Logging
• EventLog
• Email

Targets wird vom Generator zur Laufzeit neu erzeugt.

Wichtig:

Wenn der Generator die Monitor-JSON erzeugt, werden auch die Felder für die Tagesstatus-Mail und die statische HIP-VM-Prüfung mit erzeugt. Das heißt: GeneratedMonitorConfig.Email.SendDailySummary, DailySummaryHourLocal, DailySummaryMinuteLocal und GeneratedMonitorConfig.HipVirtualMachines werden direkt in die Zielkonfiguration übernommen.

---

Generator verwenden

Variante A: direkt per EXE

C:\Tools\BizTalkMonitorConfigGenerator\BizTalkMonitorConfigGenerator.exe C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json

Variante B: per Wrapper-Skript

.\scripts\generate-monitor-config.ps1 -InstallPath C:\Tools\BizTalkMonitorConfigGenerator

Erwartetes Ergebnis

Nach dem Lauf sollte vorhanden sein:

• generierte Datei, z. B. C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json
• Logdatei des Generators unter logs\
• Eventlog-Einträge im Application-Log

Monitor danach starten

C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json

---

Beispielablauf auf einem BizTalk-Server

1. Generator installieren

.\scripts\install-generator-on-server.ps1 `
  -SourcePath .\artifacts\publish\net472\BizTalkMonitorConfigGenerator `
  -InstallPath C:\Tools\BizTalkMonitorConfigGenerator `
  -RegisterEventSource

2. Generator-Konfiguration anpassen

Datei bearbeiten:

C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json

Typische Werte:

• EnvironmentName = "HIP Produktion"
• Output.Path = "C:\\Tools\\BizTalkMonitorConfigGenerator\\generated-monitor-appsettings.json"
• BizTalk.ConnectionString = "SERVER=.;DATABASE=BizTalkMgmtDb;Integrated Security=SSPI"
• GeneratedMonitorConfig.Email.SendDailySummary = true
• GeneratedMonitorConfig.Email.DailySummaryHourLocal = 14
• GeneratedMonitorConfig.Email.DailySummaryMinuteLocal = 0

3. Generator ausführen

C:\Tools\BizTalkMonitorConfigGenerator\BizTalkMonitorConfigGenerator.exe C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json

4. Generierte JSON prüfen

Prüfen, ob die Datei erzeugt wurde und Targets enthält.

Zusätzlich prüfen:

• ob GeneratedMonitorConfig.Email.SendDailySummary in der erzeugten JSON übernommen wurde
• ob die Uhrzeitfelder korrekt gesetzt sind

5. Monitor installieren

.\scripts\install-on-server.ps1 `
  -SourcePath .\artifacts\publish\net472\HostAvailabilityMonitor `
  -InstallPath C:\Tools\HostAvailabilityMonitor `
  -RegisterEventSource

6. Monitor mit der generierten JSON starten

C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json

7. Task Scheduler konfigurieren

Empfehlung:

• Generator z. B. alle 30 Minuten
• Monitor z. B. 1 bis 2 Minuten später ebenfalls alle 30 Minuten
• wichtig ist mindestens ein Monitor-Lauf nach 14:00 Uhr lokal, damit die Tagesstatus-Mail gesendet werden kann

---

Erzeugte Target-Namen

Damit im Log und in der Mail eindeutig erkennbar ist, woher ein Ziel stammt, werden sprechende Namen erzeugt, z. B.:

• SendPort: SAP_Outbound (Primary) [WCF-SQL]
• SendPort: PartnerA_SFTP (Secondary) [SFTP]
• ReceiveLocation: InboundOrders / RL_FileDrop [FILE]

Das fachliche ApplicationName des Targets kommt aus:

1. ArtifactMappings
2. ApplicationMappings
3. BizTalk-Anwendungsname (Fallback)

---

Logging und Resilienz des Generators

Der Generator ist defensiv gebaut:

• tägliche Logrotation
• Retry beim Schreiben ins Logfile
• Eventlog nur best effort
• atomisches Schreiben der Ausgabedatei (.tmp + Rename)
• bestehende Zieldatei wird vor Überschreiben als .bak gesichert
• nicht unterstützte Endpunkte werden protokolliert und übersprungen
• Discovery läuft möglichst weiter, auch wenn einzelne Artefakte unbrauchbar sind

---

Logging und Resilienz des Monitors

Der Monitor ist ebenfalls defensiv gebaut:

• Rolling-Dateilog mit täglicher Rotation
• Retention standardmäßig 5 Tage
• Eventlog-Schreiben nur best effort
• Statusdatei mit atomischem Schreiben
• Failure-/Recovery-Mails nur bei definierten Bedingungen
• Tagesstatus nur einmal pro Tag
• Tagesstatus wird nur nach erfolgreichem SMTP-Versand als versendet markiert
• Ziele, die wie SMTP-/E-Mail-Empfängerlisten aussehen, werden vom Monitor defensiv als Skipped protokolliert und nicht als DOWN alarmiert
• Fehler bei der Tageslog-Auswertung oder beim SMTP-Versand stoppen den Monitorlauf nicht hart

---

Server-Installation kompakt

Deployment-Paket erzeugen

.\scripts\build-release.ps1 -CreateDeploymentPackage

oder getrennt:

.\scripts\package-deployment.ps1

Das Ergebnis liegt dann unter artifacts\deploy\net472\ als ZIP.

PowerShell-Installer (empfohlen)

Komplette Installation beider Programme aus dem Deployment-ZIP:

.\installers\powershell\Install-Both.ps1 `
  -PackageRoot . `
  -BaseInstallPath "C:\Program Files\JR IT Services\BizTalk Endpoint Monitor" `
  -BaseConfigPath "C:\ProgramData\JR IT Services\BizTalk Endpoint Monitor" `
  -RegisterEventSources

Nur Monitor:

.\installers\powershell\Install-HostAvailabilityMonitor.ps1 `
  -PackageRoot .

Nur Generator:

.\installers\powershell\Install-BizTalkMonitorConfigGenerator.ps1 `
  -PackageRoot .

WiX-MSI-Quellen (optional)

Fuer beide Programme liegen WiX-Quellen bereit. Auf einem Windows-Buildserver mit WiX Toolset v3 kannst du daraus MSI-Dateien erzeugen:

.\installers\wix\build-msi.ps1 `
  -PublishRoot .\artifacts\publish\net472 `
  -OutputRoot .\artifacts\msi

Einzelinstallation ueber die bisherigen Skripte

Monitor

.\scripts\install-on-server.ps1 `
  -SourcePath .\artifacts\publish\net472\HostAvailabilityMonitor `
  -InstallPath C:\Tools\HostAvailabilityMonitor `
  -RegisterEventSource

Generator

.\scripts\install-generator-on-server.ps1 `
  -SourcePath .\artifacts\publish\net472\BizTalkMonitorConfigGenerator `
  -InstallPath C:\Tools\BizTalkMonitorConfigGenerator `
  -RegisterEventSource

Danach typischerweise:

1. generator-settings.json anpassen
2. Generator ausführen
3. generierte Monitor-JSON prüfen
4. Monitor mit dieser JSON starten
5. Task Scheduler einrichten

---

Hinweis zum Build

In dieser Arbeitsumgebung konnte kein echter Windows-Build gegen .NET Framework 4.7.2 und BizTalk ExplorerOM ausgefuehrt werden. Ebenso konnte hier kein echtes WiX-MSI gebaut werden, weil keine Windows-/WiX-Toolchain verfuegbar war. Der Code und die Repo-Struktur sind angepasst, der erste echte Build und Test muss auf einem Windows-/BizTalk-System erfolgen.