johannes/HostAvailabilityMonitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated to .NET Framework 4.7.2 due to platform limitations, added email cc, bcc and some fixes.

Browse Source
This commit is contained in:
Johannes Rest
2026-04-21 11:46:55 +02:00
parent c267069d02
commit b8b702bda3
40 changed files with 5666 additions and 2064 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation.en.md
+532
View File
@@ -0,0 +1,532 @@
# Documentation
## Overview
This repository is organized in a **Gitea-friendly repository structure** and contains two applications:
### 1. HostAvailabilityMonitor
The monitor checks technical reachability and writes:
- rolling file logs
- Windows Application Event Log
- email notifications for failures, recoveries, and a daily status summary
- a state file for transition detection, cooldown handling, and once-per-day summary tracking
### 2. BizTalkMonitorConfigGenerator
The generator reads BizTalk artifacts and creates a monitor configuration from them.
The goal is to avoid manually maintaining the target list and instead derive it directly from BizTalk.
---
## Repository structure for 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
```
This layout is intentionally simple so it can be committed to **Gitea**, built on Windows, and deployed to BizTalk or application servers with minimal friction.
---
## Supported BizTalk sources
### Send Ports
By default, only **started send ports** are included.
Optionally, the **secondary transport** of a send port can also be included. Secondary transports using the **SMTP** adapter are intentionally excluded from monitor target generation because their BizTalk address usually represents an email recipient list rather than a network endpoint.
### Receive Locations
By default, only **enabled receive locations** are included.
---
## Endpoint normalization
The generator tries to transform BizTalk addresses into monitor-compatible endpoints.
### Directly supported
- `\\server\share`
- `file://...`
- `http://...`
- `https://...`
- `ftp://...`
- `sftp://...`
- `tcp://...`
- `icmp://...`
- plain host / host:port values on a best-effort basis
### Special handling
- `net.tcp://host:port/...` is rewritten to `tcp://host:port/...`
- local file system paths such as `C:\Drop\In` are only included when `IncludeLocalFilePaths=true`
- `net.pipe://...` is skipped because the monitor does not support it
---
## HostAvailabilityMonitor: mail and status behavior
The monitor can send three kinds of emails:
1. **Failure email** when an endpoint changes from available to unavailable
2. **Recovery email** when an endpoint changes from unavailable back to available
3. **Daily status email** once per day at or after a configured local time, default **14:00 local server time**
The daily summary is intentionally **not** implemented as a second Windows task or a separate internal scheduler.
Instead, the behavior is:
- the normal scheduled monitor run starts as usual
- on every run, the monitor checks whether the configured local time has already been reached
- the **first run at or after that time** sends the daily summary email
- only **one** daily summary email is sent per calendar day
- the daily summary is marked as sent **only if SMTP delivery succeeded**
This keeps the solution resilient and simple for BizTalk server operations.
---
## Monitor configuration details
File: `src\HostAvailabilityMonitor\appsettings.json`
### Root fields
- `ApplicationName`: monitor name
- `EnvironmentName`: environment label such as `HIP Production`
- `Runtime`: runtime behavior
- `Logging`: file logging configuration
- `EventLog`: Windows Event Log configuration
- `Email`: SMTP and notification configuration
- `Targets`: endpoints to probe
### Email section
Important fields in `Email`:
- `Enabled`: enable or disable email delivery completely
- `SmtpHost`, `SmtpPort`, `UseSsl`, `UseDefaultCredentials`, `Username`, `Password`
- `From`, `To`, `Cc`, `Bcc`, `SubjectPrefix`
- `SendOnFailure`: send an email on failure
- `SendOnRecovery`: send an email on recovery
- `SendDailySummary`: send a daily status summary
- `DailySummaryHourLocal`: local server hour, for example `14`
- `DailySummaryMinuteLocal`: local server minute, for example `0`
- `OnlyOnStateChange`: for failure/recovery emails, react only to state changes
- `CooldownMinutes`: cooldown for repeated failure emails when `OnlyOnStateChange=false`
- `TimeoutSeconds`: SMTP timeout
Recipient notes:
- `To`, `Cc`, and `Bcc` are JSON arrays of email addresses.
- Configure multiple recipients by adding multiple array entries.
- A single semicolon-separated string is not the supported format.
- At least one recipient across `To`, `Cc`, or `Bcc` must be configured when `Email.Enabled=true`.
### Example 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
}
```
### Example for multiple recipients
```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"
]
}
```
### Daily summary content
The daily status email contains:
- monitor name
- environment
- machine name
- time window from local midnight until send time
- today's successful and failed probe counts based on the current day's rolling log
- a current snapshot of the latest monitor run
- a list of currently unavailable endpoints including:
- application
- name
- endpoint
- kind
- status
- detail
- host/port/HTTP status when available
Note:
The daily counters are derived from the **current day's rolling log file**. If that evaluation fails for any reason, email delivery still continues; the counters fall back to `0` and the incident is logged.
---
## Generator configuration details
File: `generator-settings.json`
### Root fields
- `GeneratorName`: display name for generator logs and event log entries
- `EnvironmentName`: environment label such as `HIP Production`
- `Logging`: generator logging settings
- `EventLog`: generator event log settings
- `BizTalk`: discovery rules
- `Output`: output path and generation rules
- `GeneratedMonitorConfig`: template for the final monitor JSON
### BizTalk section
- `ConnectionString`: connection to BizTalkMgmtDb
- `IncludeSendPorts`: read send ports
- `IncludeReceiveLocations`: read receive locations
- `OnlyStartedSendPorts`: include active send ports only
- `OnlyEnabledReceiveLocations`: include active receive locations only
- `IncludeSecondaryTransportOnSendPorts`: include secondary send transports
- SMTP send ports and SMTP secondary transports are skipped automatically by the generator
- `IncludeDynamicSendPorts`: include dynamic send ports
- `IncludeLocalFilePaths`: include local file system paths
- `IgnoreSystemApplications`: skip system applications
- `IgnoreApplications`: ignore applications by wildcard pattern
- `IgnoreArtifactNamePatterns`: ignore ports/locations by wildcard pattern
- `ApplicationMappings`: map BizTalk application names to business application names
- `ArtifactMappings`: map specific artifacts to business application names
### Output section
- `Path`: target path of the generated monitor JSON
- `OverwriteExisting`: overwrite existing file
- `FailIfNoTargetsFound`: return exit code 2 when no targets were found
- `TargetTimeoutSeconds`: default timeout for each generated target
- `TargetEnabled`: default `Enabled` value for each generated target
- `DefaultHttpMethod`: default HTTP method for generated HTTP/HTTPS targets
### GeneratedMonitorConfig section
This is the template for the monitor runtime configuration.
It contains:
- monitor `ApplicationName`
- `EnvironmentName`
- `Runtime`
- `Logging`
- `EventLog`
- `Email`
`Targets` is rebuilt by the generator at runtime.
Important:
When the generator writes the monitor JSON, the daily summary options are also copied into the generated target file. That means `GeneratedMonitorConfig.Email.SendDailySummary`, `DailySummaryHourLocal`, and `DailySummaryMinuteLocal` flow directly into the output monitor configuration.
---
## How to use the generator
### Option A: run the EXE directly
```powershell
C:\Tools\BizTalkMonitorConfigGenerator\BizTalkMonitorConfigGenerator.exe C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json
```
### Option B: run the wrapper script
```powershell
.\scripts\generate-monitor-config.ps1 -InstallPath C:\Tools\BizTalkMonitorConfigGenerator
```
### Expected result
After the run, you should have:
- a generated JSON file, for example `C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json`
- a generator log file under `logs\`
- event log entries in the Windows `Application` log
### Run the monitor afterwards
```powershell
C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json
```
---
## Example flow on a BizTalk server
### 1. Install the generator
```powershell
.\scripts\install-generator-on-server.ps1 `
-SourcePath .\artifacts\publish\net472\BizTalkMonitorConfigGenerator `
-InstallPath C:\Tools\BizTalkMonitorConfigGenerator `
-RegisterEventSource
```
### 2. Adjust the generator settings
Edit this file:
```text
C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json
```
Typical values:
- `EnvironmentName = "HIP Production"`
- `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. Run the generator
```powershell
C:\Tools\BizTalkMonitorConfigGenerator\BizTalkMonitorConfigGenerator.exe C:\Tools\BizTalkMonitorConfigGenerator\generator-settings.json
```
### 4. Check the generated JSON
Confirm that the file was created and contains `Targets`.
Also verify:
- the generated JSON contains `SendDailySummary`
- the daily summary time values are correct
### 5. Install the monitor
```powershell
.\scripts\install-on-server.ps1 `
-SourcePath .\artifacts\publish\net472\HostAvailabilityMonitor `
-InstallPath C:\Tools\HostAvailabilityMonitor `
-RegisterEventSource
```
### 6. Start the monitor with the generated JSON
```powershell
C:\Tools\HostAvailabilityMonitor\HostAvailabilityMonitor.exe C:\Tools\BizTalkMonitorConfigGenerator\generated-monitor-appsettings.json
```
### 7. Configure Task Scheduler
Recommended setup:
- generator every 30 minutes
- monitor every 30 minutes, 1 to 2 minutes after the generator
- ensure there is at least one monitor run **after 14:00 local time** so the daily summary can be sent
---
## Generated target names
To make logs and alert emails easy to understand, the generator creates descriptive names such as:
- `SendPort: SAP_Outbound (Primary) [WCF-SQL]`
- `SendPort: PartnerA_SFTP (Secondary) [SFTP]`
- `ReceiveLocation: InboundOrders / RL_FileDrop [FILE]`
The business `ApplicationName` of the generated target is resolved in this order:
1. `ArtifactMappings`
2. `ApplicationMappings`
3. BizTalk application name as fallback
---
## Generator logging and resilience
The generator is designed defensively:
- daily rolling logs
- retries when appending to the log file
- event log is best effort only
- atomic output file writing (`.tmp` + rename)
- existing target file is backed up as `.bak` before overwrite
- unsupported endpoints are logged and skipped
- discovery continues even if individual artifacts are unusable
---
## Monitor logging and resilience
The monitor is also defensive:
- daily rolling logs
- default retention of 5 days
- event log writes are best effort only
- state file is written atomically
- failure/recovery emails follow explicit notification rules
- daily summary is sent only once per day
- the summary is marked as sent only after successful SMTP delivery
- targets that look like SMTP/email recipient lists are handled defensively as `Skipped` and do not raise DOWN alerts
- log parsing or SMTP errors do not crash the monitor run hard
---
## Server installation quick guide
### Create a deployment package
```powershell
.\scripts\build-release.ps1 -CreateDeploymentPackage
```
or separately:
```powershell
.\scripts\package-deployment.ps1
```
The result is a ZIP under `artifacts\deploy\net472\`.
### PowerShell installers (recommended)
Install both applications from the 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
```
Install monitor only:
```powershell
.\installers\powershell\Install-HostAvailabilityMonitor.ps1 `
-PackageRoot .
```
Install generator only:
```powershell
.\installers\powershell\Install-BizTalkMonitorConfigGenerator.ps1 `
-PackageRoot .
```
### WiX MSI sources (optional)
WiX source files are included for both applications. On a Windows build machine with WiX Toolset v3 you can generate MSI packages:
```powershell
.\installers\wix\build-msi.ps1 `
-PublishRoot .\artifacts\publish\net472 `
-OutputRoot .\artifacts\msi
```
### Individual installation using the original scripts
#### 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
```
Then typically:
1. adjust `generator-settings.json`
2. run the generator
3. verify the generated monitor JSON
4. run the monitor against that JSON
5. configure Task Scheduler
---
## Build note
In this environment, no real Windows build against .NET Framework 4.7.2 and BizTalk ExplorerOM could be executed. The same applies to real WiX-built MSI binaries because no Windows/WiX toolchain is available here. The code and repository structure were updated, but the first real build and validation must happen on a Windows/BizTalk system.