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

```text
.
├── .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

### Runtime

Wichtige Felder im Abschnitt `Runtime`:

- `MaxConcurrency`: maximale Anzahl paralleler Endpoint-Checks
- `DefaultValidateUncPathAccess`: Standardwert fuer UNC-Targets ohne eigenen `ValidateUncPathAccess`-Wert
- `NonZeroExitCodeOnAnyFailure`: bei fachlichen DOWN-Ergebnissen mit Exitcode `2` beenden
- `NonZeroExitCodeOnExecutionError`: bei technischen Ausfuehrungsfehlern mit Exitcode `1` beenden
- `StateDirectory`: Verzeichnis fuer die Statusdatei
- `StateFileName`: Dateiname der Statusdatei, standardmaessig `monitor-state.json`

### Logging

Wichtige Felder im Abschnitt `Logging`:

- `LogDirectory`: Verzeichnis fuer die Rolling-Logdateien
- `FilePrefix`: Prefix der taeglichen Logdateien
- `RetentionDays`: Anzahl der aufzubewahrenden taeglichen Logdateien, standardmaessig `30`; `0` deaktiviert die automatische Bereinigung

### 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

```json
"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

```json
"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:

```text
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`:

```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`
- `HipVirtualMachines`

`Targets` wird vom Generator zur Laufzeit neu erzeugt.

Wichtig:

Wenn der Generator die Monitor-JSON erzeugt, werden auch Runtime-, Logging-, Tagesstatus-Mail- und statische HIP-VM-Felder mit erzeugt. Das heißt: Werte wie `GeneratedMonitorConfig.Runtime.StateFileName`, `GeneratedMonitorConfig.Logging.RetentionDays`, `GeneratedMonitorConfig.Email.SendDailySummary`, `DailySummaryHourLocal`, `DailySummaryMinuteLocal` und `GeneratedMonitorConfig.HipVirtualMachines` werden direkt in die Zielkonfiguration übernommen.

---

## Generator verwenden

### Variante A: direkt per EXE

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

### Variante B: per Wrapper-Skript

```powershell
.\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

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

---

## Beispielablauf auf einem BizTalk-Server

### 1. Generator installieren

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

### 2. Generator-Konfiguration anpassen

Datei bearbeiten:

```text
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

```powershell
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

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

### 6. Monitor mit der generierten JSON starten

```powershell
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 30 Tage, konfigurierbar über `Logging.RetentionDays`
- 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

```powershell
.\scripts\build-release.ps1 -CreateDeploymentPackage
```

oder getrennt:

```powershell
.\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:

```powershell
.\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:

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

Nur Generator:

```powershell
.\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:

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

### Einzelinstallation ueber die bisherigen Skripte

#### Monitor

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

#### Generator

```powershell
.\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.