HostAvailabilityMonitor/README.md

# Host Availability Monitor + BizTalk Monitor Config Generator (.NET Framework 4.7.2)

Dieses Repository ist für eine **Gitea-kompatible Repo-Struktur** aufgebaut und enthält zwei Konsolenanwendungen für **Windows Server 2019 / BizTalk Server 2019** auf **.NET Framework 4.7.2**:

1. **HostAvailabilityMonitor**
   - prüft Endpunkte wie UNC/SMB, `file://`, HTTP/HTTPS, SFTP, FTP, TCP, ICMP und RDP
   - lädt optional eine statische HIP-VM-Liste aus `hip-vms.json` und prüft pro VM Netzwerk/Ping sowie RDP/TCP 3389
   - schreibt Rolling-Logs, Windows Application Event Log und E-Mails bei DOWN, Recovery und täglichem Status

2. **BizTalkMonitorConfigGenerator**
   - liest aktive **BizTalk Send Ports** und aktivierte **Receive Locations** aus
   - erzeugt daraus automatisch die JSON-Konfiguration, die der `HostAvailabilityMonitor` direkt verwenden kann
   - übernimmt Umgebung, Default-Werte und fachliche Anwendungszuordnung

## Zielbild

Der typische Betrieb auf einer BizTalk-Maschine ist:

1. Der **Generator** läuft mit Admin-Rechten auf dem jeweiligen BizTalk-Server.
2. Er liest die aktiven BizTalk-Artefakte aus.
3. Er erzeugt eine vollständige Monitor-Konfiguration im JSON-Format.
4. Der **Monitor** läuft anschließend mit genau dieser JSON-Datei.
5. Bei DOWN und bei `DOWN -> UP` gehen Mails raus.
6. Zusätzlich geht **einmal pro Tag** eine **Status-Mail** mit Tageszusammenfassung raus, standardmäßig um **14:00 Uhr lokal**.

## Gitea-kompatible Repository-Struktur

```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 bewusst einfach gehalten, damit das Repository sauber in **Gitea** eingecheckt, gebaut und auf Windows-Servern ausgerollt werden kann.

## Lösung / Solution

- `src/HostAvailabilityMonitor/`
- `src/BizTalkMonitorConfigGenerator/`
- `scripts/build-release.ps1`
- `scripts/install-on-server.ps1`
- `scripts/install-generator-on-server.ps1`
- `scripts/generate-monitor-config.ps1`
- `scripts/package-deployment.ps1`
- `installers/powershell/*`
- `installers/wix/*`

## Technische Eckpunkte

### HostAvailabilityMonitor

- Task-Scheduler-tauglich
- tägliche Logrotation
- Log-Retention standardmäßig 30 Tage
- Windows Application Event Log
- SMTP-Mails bei DOWN, Recovery (`DOWN -> UP`) und täglichem Status
- SMTP-Sendports bzw. reine E-Mail-Empfaengerlisten werden vom Generator uebersprungen und vom Monitor defensiv nur als `Skipped` protokolliert, nicht alarmiert
- statische HIP-VM-Prüfung über separate `hip-vms.json`, damit durch BizTalk neu erzeugte Endpunktlisten nicht mit der VM-Liste kollidieren
- pro HIP-VM werden zwei normale Monitor-Targets erzeugt: `icmp://<ip>` für Netzwerk-Konnektivität und `rdp://<ip>:3389` für RDP
- tägliche Status-Mail auf Basis des **ersten Laufs ab der konfigurierten Uhrzeit**
- State-Datei gegen Mail-Spam und für die Einmal-pro-Tag-Logik der Status-Mail
- `ApplicationName` pro Target
- `EnvironmentName` global

### BizTalkMonitorConfigGenerator

- liest BizTalk über **Microsoft.BizTalk.ExplorerOM**
- berücksichtigt standardmäßig nur:
  - **gestartete Send Ports**
  - **aktivierte Receive Locations**
- unterstützt optional:
  - Secondary Transport von Send Ports
  - lokale Pfade
  - Mapping von BizTalk-Anwendungsnamen auf fachliche `ApplicationName`-Werte
- schreibt Rolling-Log und Event Log
- schreibt die Ziel-JSON **atomar** über Temp-Datei + Rename

## Build

### Voraussetzung

Für den Generator muss auf dem Build- oder Zielsystem die BizTalk-Assembly **`Microsoft.BizTalk.ExplorerOM.dll`** verfügbar sein, typischerweise durch installierten BizTalk Server bzw. BizTalk Developer/Admin Components.

### MSBuild

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

### Build-Skript

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

Das Skript erstellt anschließend typischerweise:

- `artifacts\publish\net472\HostAvailabilityMonitor\`
- `artifacts\publish\net472\BizTalkMonitorConfigGenerator\`

Optional direkt mit Deployment-Paket:

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

Oder separat:

```powershell
.\scripts\package-deployment.ps1
```

Danach liegt ein verteilerfertiges ZIP unter `artifacts\deploy\net472\`.


## Installer / Setup-Optionen

Es gibt jetzt **zwei Installer-Wege**:

### 1. PowerShell-Installer (empfohlen fuer BizTalk/Windows Server)

Diese Variante ist in restriktiven Serverumgebungen meist am praktikabelsten.

Wichtige Dateien:

- `installers\powershell\Install-HostAvailabilityMonitor.ps1`
- `installers\powershell\Install-BizTalkMonitorConfigGenerator.ps1`
- `installers\powershell\Install-Both.ps1`
- `installers\powershell\Uninstall-HostAvailabilityMonitor.ps1`
- `installers\powershell\Uninstall-BizTalkMonitorConfigGenerator.ps1`

Beispiel fuer ein gemeinsames Setup 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
```

### 2. WiX-MSI-Quellen (optional)

Fuer beide Programme liegen **WiX-Quellen** bei:

- `installers\wix\HostAvailabilityMonitor.wxs`
- `installers\wix\BizTalkMonitorConfigGenerator.wxs`
- `installers\wix\build-msi.ps1`

Damit kannst du auf einem Windows-Buildsystem mit WiX Toolset v3 echte MSI-Pakete erzeugen.

Beispiel:

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

Hinweis: In diesem Arbeitsraum konnte ich **keine MSI-Binaries real bauen**, weil hier keine Windows-/WiX-Toolchain bereitsteht. Ich habe dir daher **robuste PowerShell-Installer** und **MSI-Quellen fuer den Windows-Build** bereitgestellt.

## Installation auf dem Server

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

## Monitor-Konfiguration für tägliche Status-Mail

In `appsettings.json` bzw. in `GeneratedMonitorConfig.Email` des Generators stehen jetzt zusätzlich diese Felder:

```json
"Email": {
  "Enabled": true,
  "To": [ "operations@example.local", "integration-oncall@example.local" ],
  "Cc": [ "integration-leads@example.local" ],
  "Bcc": [],
  "SendOnFailure": true,
  "SendOnRecovery": true,
  "SendDailySummary": true,
  "DailySummaryHourLocal": 14,
  "DailySummaryMinuteLocal": 0
}
```

Bedeutung:

- `SendDailySummary`: schaltet die tägliche Status-Mail ein oder aus
- `DailySummaryHourLocal`: lokale Stunde auf dem Server, z. B. `14`
- `DailySummaryMinuteLocal`: lokale Minute auf dem Server, z. B. `0`

Empfaengerfelder:

- `To`: Hauptempfaenger als JSON-Liste
- `Cc`: optionale CC-Empfaenger als JSON-Liste
- `Bcc`: optionale BCC-Empfaenger als JSON-Liste
- Es muss mindestens ein Empfaenger in `To`, `Cc` oder `Bcc` vorhanden sein.
- Mehrere Empfaenger werden **nicht** per Semikolon in einem String konfiguriert, sondern als mehrere Array-Eintraege.

Wichtig für den Betrieb:

- Die Mail wird **nicht durch einen separaten zweiten Job** verschickt.
- Sie wird vom normalen Monitor-Lauf versendet.
- Das heißt: Der **erste erfolgreiche Programmlauf ab 14:00 Uhr lokal** verschickt die Tageszusammenfassung.
- Läuft der Task z. B. alle 30 Minuten, dann geht die Status-Mail je nach Startzeit um `14:00`, `14:30`, `15:00` usw. raus — aber **nur einmal pro Tag**.

Inhalt der Tagesstatus-Mail:

- Monitorname, Umgebung, Servername
- Zeitfenster von Mitternacht bis Versandzeitpunkt
- Anzahl aller heutigen Checks
- Anzahl heutiger erfolgreicher und fehlgeschlagener Checks
- aktueller Snapshot des letzten Laufs
- Liste der aktuell DOWN befindlichen Endpunkte mit Anwendung und Umgebung
- HIP-VM-Snapshot mit Netzwerk- und RDP-Status pro VM

## HIP-VM-Monitoring

Die statischen HIP-VMs liegen getrennt von den BizTalk-Endpunkten in:

```text
src\HostAvailabilityMonitor\hip-vms.json
```

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

Pro VM erzeugt der Monitor beim Start zwei normale Checks:

- `Network`: Ping/ICMP gegen die konfigurierte Adresse
- `RDP`: TCP-Verbindung auf den konfigurierten RDP-Port, standardmäßig `3389`

Ausfälle und Recoveries laufen über dieselbe State-Datei und dieselbe Mail-Logik wie alle anderen Targets. Die tägliche Status-Mail enthält zusätzlich eine kompakte HIP-VM-Übersicht je Gruppe, Maschine und Beschreibung.

## Mehrere Mail-Empfaenger konfigurieren

Beispiel:

```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"
  ]
}
```

Wichtig:

- pro Adresse ein eigener Eintrag im Array
- keine Semikolon-getrennte Empfaengerliste in einem einzelnen String
- `Cc` und `Bcc` sind optional

## Generator verwenden

### 1. Generator-Einstellungen prüfen oder anpassen

Datei:

```text
src\BizTalkMonitorConfigGenerator\generator-settings.json
```

Wichtige Felder:

- `EnvironmentName`: z. B. `HIP Produktion`
- `BizTalk.ConnectionString`: meist `SERVER=.;DATABASE=BizTalkMgmtDb;Integrated Security=SSPI`
- `BizTalk.OnlyStartedSendPorts`: nur gestartete Send Ports übernehmen
- `BizTalk.OnlyEnabledReceiveLocations`: nur aktivierte Receive Locations übernehmen
- `BizTalk.IncludeSecondaryTransportOnSendPorts`: Secondary Transport mit aufnehmen
- Hinweis: Secondary Transports mit Adapter `SMTP` werden bewusst nicht als Monitor-Targets erzeugt
- `BizTalk.IncludeLocalFilePaths`: lokale Pfade zulassen oder verwerfen
- `BizTalk.ApplicationMappings`: Mapping von BizTalk-Anwendungsnamen auf fachliche App-Namen
- `Output.Path`: Pfad der zu erzeugenden Monitor-JSON
- `GeneratedMonitorConfig`: Vorlage für Logging, Runtime, Event Log und Mail des Monitors
- `GeneratedMonitorConfig.Logging.RetentionDays`: Aufbewahrung der taeglichen Monitor-Logdateien, standardmaessig `30`
- `GeneratedMonitorConfig.Runtime.StateFileName`: Dateiname der Statusdatei, falls mehrere Monitor-Konfigurationen getrennten Zustand brauchen
- `GeneratedMonitorConfig.HipVirtualMachines`: statische HIP-VM-Prüfung in der generierten Monitor-JSON einschalten
- `GeneratedMonitorConfig.Email.SendDailySummary`: tägliche Status-Mail in der generierten Monitor-JSON einschalten
- `GeneratedMonitorConfig.Email.DailySummaryHourLocal`: lokale Uhrzeit der Tageszusammenfassung
- `GeneratedMonitorConfig.Email.DailySummaryMinuteLocal`: lokale Minute der Tageszusammenfassung

### 2. Generator direkt starten

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

### 3. Generator per Hilfsskript starten

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

### 4. Ergebnis prüfen

Danach sollte eine generierte Monitor-Datei vorhanden sein, z. B.:

```text
C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json
```

Zusätzlich prüfen:

- Generator-Logdatei unter `logs\`
- Einträge im Windows Application Event Log
- Inhalt der generierten JSON

### 5. Monitor mit der erzeugten Datei starten

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

## Praxisbeispiel für den Betrieb auf der BizTalk-Maschine

### Task 1: Generator

- Programm: `C:\Tools\BizTalkMonitorConfigGenerator\BizTalkMonitorConfigGenerator.exe`
- Argumente: `C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json`
- Starten in: `C:\Tools\BizTalkMonitorConfigGenerator`
- Konto: BizTalk-Admin / technisches Administratorkonto
- Intervall: z. B. alle 30 Minuten oder vor dem Monitor-Lauf

### Task 2: Monitor

- Programm: `C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe`
- Argumente: `C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json`
- Starten in: `C:\Tools\HostAvailabilityMonitor`
- Konto: Dienstkonto mit technischem Zugriff auf Shares, HTTP(S), FTP/SFTP und andere Zielsysteme
- Intervall: kurz nach dem Generator, z. B. 1 bis 2 Minuten später

Empfehlung für die Status-Mail um 14:00:

- den Monitor mindestens alle 15 oder 30 Minuten laufen lassen
- sicherstellen, dass in dieser Zeit auch **mindestens ein Lauf nach 14:00 Uhr** stattfindet
- kein separater Status-Task notwendig

## Beispiel für ein Generator-Mapping

```json
"ApplicationMappings": [
  {
    "BizTalkApplicationName": "HIP*",
    "ApplicationName": "HIP"
  },
  {
    "BizTalkApplicationName": "PartnerA*",
    "ApplicationName": "HIP Partneranbindung"
  }
]
```

## Hinweise

- Fuer .NET Framework 4.7.2 ist der Build-Output jetzt unter `artifacts\publish\net472\` vorgesehen.

- Nicht unterstützte Endpunkte wie `net.pipe://` werden sauber übersprungen und protokolliert.
- Für `net.tcp://host:port/...` wird eine Monitor-kompatible `tcp://...`-Adresse erzeugt.
- Für lokale Dateipfade ist standardmäßig `IncludeLocalFilePaths=false` gesetzt.
- Die erzeugte Monitor-JSON enthält `EnvironmentName` global und `ApplicationName` pro Target.
- Der Generator versendet selbst keine E-Mails, sondern erzeugt nur die Konfiguration.
- Die Event-Source-Erstellung benötigt Administratorrechte.
- Die Tagesstatus-Mail wird nur dann als „versendet“ gespeichert, wenn der SMTP-Versand erfolgreich war.

## Dokumentation

- Deutsch: [Dokumentation.md](Dokumentation.md)
- English: [Documentation.en.md](Documentation.en.md)