Files

T

admin 8b1c14b892 Make shutdown checkpoint dialogs unmistakable

2026-08-27 20:17:16 +02:00

14 KiB

Raw Blame History

BizTalk Platform Management Tool

WinForms tool for controlled Microsoft BizTalk Server 2020 platform operations during maintenance windows. The tool captures runtime snapshots, creates shutdown and restore plans, executes those plans in a safe order, and writes diff reports for validation.

Current State

Application: C# WinForms
Target framework: .NET Framework 4.6.1
Solution: BizTalkPlatformManagementTool.sln
Project: src/BizTalkPlatformManagementTool/BizTalkPlatformManagementTool.csproj
Primary namespace and assembly: BizTalkPlatformManagementTool
Legacy PowerShell archive: archive/powershell/BizTalkPlatformManagementTool.ps1

Features

Snapshot before and after downtime as JSON, CSV and HTML
Diff between before.json and after.json
Controlled shutdown from the current runtime state
Controlled restore from before.json
State-aware emergency restore from a preserved before.json, including Enterprise SSO startup
WMI-free validation and file selection for preserved recovery snapshots, including 2.1.3 snapshots
Host instance handling for the selected BizTalk server
Dry-run mode enabled by default
WMI access through root\MicrosoftBizTalkServer
Correct application ownership from the read-only ExplorerOM application hierarchy, with WMI retained for runtime state and mutations
Startup check for administrator rights
Detailed operation logging in the GUI and daily rolling log files in a write-verified local directory
Automatic operation-log restoration into the grid after an application restart
Thirty-day runtime-log retention with GZip compression for completed daily logs
Process-local ScheduledTask adapter dependency resolution for scheduler: receive locations without modifying the GAC
Fail-closed operator drain checkpoint after all receive locations and before later shutdown phases
Owner-bound shutdown confirmations with an explicit paused/action-required status and an unambiguous Dry-run notice
Best-effort plan execution: one isolated WMI failure is recorded while remaining independent steps continue
Idempotent execution that skips artifacts already in the requested target state
Durable per-step result reports even when a shutdown or restore completes only partially
Environment status indicator based on host instance state
Clear and Close actions in the main toolbar
No compile-time dependency on BizTalk ExplorerOM assemblies; the installed Microsoft assembly is loaded process-locally with identity validation
Transactional Windows installer/updater with SHA-256 payload validation and rollback
Bounded activation retries plus a verified copy fallback for first installs and atomically backed-up updates when Windows/EDR blocks only the staging rename
Opt-in all-users desktop shortcut whose ACL, WSH, validation or rollback failures remain visible but cannot roll back the core installation
Installer diagnostics with stable phase codes, complete child-process output, exception chains and a ProgramData-to-Temp log fallback
WMI-free runtime self-test plus automated regression test executable

Safe Usage

Start the app with Run as administrator on a BizTalk server or a management host with WMI access.
Keep Dry run enabled.
Click Diagnose to verify WMI access.
Click Snapshot Before.
Click Shutdown and review shutdown-plan.json.
Disable Dry run only when the plan is correct.
During a real shutdown, keep the drain dialog open until Group Hub and enterprise monitoring show that in-flight processing has emptied; choose Yes only then.
After maintenance, click Restore using the saved before.json.
Click Snapshot After and Compare.

If a shutdown was interrupted and only the original before.json remains, select that file with State..., run Validate State, keep Dry run enabled and click Emergency Restore. The recovery plan never overwrites the source snapshot, ensures the ENTSSO service is running first, skips already-correct runtime states and continues after isolated step failures. Disable Dry run only after reviewing the timestamped emergency plan. A real run automatically writes a timestamped target/actual diff when the post-operation snapshot succeeds.

The environment indicator shows Started, Stopped, Partial or Unknown from the most recent snapshot. Clear removes the visible status and operation log grids; it does not delete files. Log Folder opens the persistent local runtime-log directory.

The application requests administrator rights through its UAC manifest and checks them again during startup. Only one GUI instance can run per Windows session.

Before a real shutdown or restore, the exact fresh plan is saved and a second dialog shows its executable step count, target server and plan path. Restore is rejected when the snapshot server does not match the selected target (short name and FQDN of the same host are accepted).

Operation Order

Shutdown:

Disable receive locations that were enabled.
Pause at the persisted inbound-drain checkpoint and require an explicit operator decision.
Stop orchestrations that were started.
Stop send ports that were started.
Stop host instances that were started on the selected server.

Restore:

Start host instances that were previously started.
Restore send ports to Started, Stopped or Bound.
Restore orchestrations where safe.
Restore receive locations last.

Orchestrations that were Bound are deliberately left unchanged during restore to avoid accidentally making them Unbound.

The drain checkpoint is part of shutdown-plan.json. In a real run, the status changes to ACTION REQUIRED, and the owned dialog remains in front of the main window. Yes records CheckpointDecision=Continue; No, a closed dialog or a callback error fails closed before orchestrations, send ports and host instances. All later rows are persisted as NotExecuted, followed by a partial-state snapshot and shutdown-result.json. Dry-run shows the checkpoint but never opens a decision dialog; it displays a separate notice explaining that no receive location was changed.

BizTalk applications displaying Partially Started immediately after receive locations are disabled is expected. Microsoft defines “Partial Stop - Allow running instances to continue” as disabling only receive locations so in-flight instances can finish. The tool deliberately does not issue an additional application-level stop: its stronger variants can stop or unenlist artifacts, remove subscriptions, undeploy policies or terminate instances. The existing artifact-level plan preserves exact snapshot state and controlled global ordering.

Outputs

before.json, after.json
shutdown-plan.json, restore-plan.json
shutdown-after.json, restore-after.json
shutdown-result.json, restore-result.json
Timestamped emergency-source-before-*, emergency-restore-plan-*, emergency-restore-result-*, emergency-restore-after-* and emergency-restore-diff-* files
diff.json, diff.csv, diff.html
Snapshot sidecars: *.csv, *.hosts.csv, *.html
Runtime logs primarily under %ProgramData%\BizTalkPlatformManagementTool\Logs

The current day remains a plain BizTalkPlatformManagementTool-yyyy-MM-dd.log. Completed daily logs are compressed to .log.gz; the current day plus the previous 29 calendar days are retained. Older records are removed on startup. Up to the newest 10,000 retained entries are automatically restored from plain and compressed files into the Operation Log grid after a restart.

At every start, the application performs an actual create/write/flush/delete probe and then appends a visible startup verification record. The ordered locations are ProgramData, the current account's LocalAppData, Logs below the executable directory, and Temp. Log Folder opens the path that really accepted the write. A fallback or complete storage failure is shown with attempted paths and exception details in the Operation Log; it is never silently ignored.

C:\Program Files\BizTalkPlatformManagementTool therefore normally contains no log file. ProgramData is a separate, normally hidden Windows directory. An install-local Logs subdirectory appears only when both ProgramData and LocalAppData were rejected and Program Files itself permits the fallback write.

Troubleshooting

The BizTalk runtime WMI classes for Send Ports, Receive Locations and Orchestrations do not expose a reliable application property. The tool therefore reads MgmtDbServerName/MgmtDbName from MSBTS_GroupSetting, opens the installed read-only ExplorerOM application catalog and builds an application/artifact index before collecting WMI state. Diagnose reports both visible and application-resolved Send Port counts. A mismatch is never silently presented as a valid association: affected rows stay under (Unknown Application) and the Operation Log records whether ExplorerOM loading, Management database access or catalog matching failed.

The Operation Log shows the WMI class, key property, key value and method for real shutdown and restore steps. WMI objects are resolved with a broad SELECT * FROM <class> query and a client-side key filter so names containing special characters do not break the WMI query parser.

Execution is deliberately best-effort. A failure such as an adapter-specific validation exception is written as Failed in the result report, but later independent plan steps are still attempted. The GUI ends in a failed/operator-review state when any step failed; it never reports a partial execution as an unconditional success. The post-operation snapshot is attempted independently and its own failure is preserved in the same report.

The operator checkpoint is the explicit exception to best-effort continuation: declining it or losing the confirmation mechanism intentionally prevents every later shutdown phase. This is a safe incomplete operation, not a successful full shutdown, and remains visible in the report and grid.

For a ScheduledTask receive location, the operation plan retains adapter name and address. Immediately before a real Enable or Disable, the tool preloads Microsoft.BizTalk.Scheduler.dll from the locally installed BizTalk directory and resolves further dependencies from identity-checked BizTalk/ScheduledTask adapter directories. Conventional BizTalk 2020 and BizTalk ScheduledTask Adapter 7.x folders plus BizTalk registry paths are discovered automatically. An exceptional installation path can be added to the semicolon-delimited AdapterAssemblySearchPaths value in BizTalkPlatformManagementTool.exe.config. This is process-local: the tool neither copies DLLs nor changes the GAC. Never point the setting at assemblies from a different BizTalk version.

Error records in the grid, execution report and file log include exception type, HRESULT, complete inner-exception chain, available Fusion loader information and stack trace. For the PROD validation and support bundle, follow ScheduledTask control and runtime logging runbook.

For the specific PROD finding "no logs visible below Program Files" and the version 2.3.1 storage verification, follow PROD runtime-log storage validation.

Snapshot and plan JSON files are written as UTF-8 without BOM. Loading is tolerant of existing files that contain a UTF-8 BOM or a visible BOM marker from previous encoding conversions.

JSON snapshots and plans are written through a same-directory temporary file and atomic replacement. Snapshot comparison keys artifacts by application plus name, preventing collisions between equal artifact names in different applications. CSV fields that could be interpreted as spreadsheet formulas are neutralized.

Installer, update and uninstall diagnostics are retained for 90 days under %ProgramData%\BizTalkPlatformManagementTool\InstallerLogs. The setup UI can open that directory directly. If the primary log cannot be created, setup reports and uses a %TEMP%\BizTalkPlatformManagementTool\InstallerLogs fallback. See Installation for phase codes and the support checklist.

Build

Open BizTalkPlatformManagementTool.sln in Visual Studio on Windows with the .NET Framework 4.6.1 Developer Pack installed, then build the Release|Any CPU configuration.

The app targets .NET Framework 4.6.1 for compatibility with customer environments that do not have newer .NET Framework developer packs installed.

Use scripts\test-release.cmd for the build and regression suite and scripts\package-release.cmd for the tested installer ZIP, Certutil-compatible Base64 TXT and SHA-256 file. See Installation for decoding and update/rollback details.

Source Documentation

All C# types and methods in the application, setup, packager and regression project use XML documentation comments. Method contracts include param, typeparam and returns elements where applicable. Release builds generate one XML documentation file per assembly, so malformed or missing public documentation becomes visible during compilation.

Targeted German inline comments explain non-obvious operational decisions such as WMI client-side filtering, shutdown/restore order, atomic file replacement, CSV formula neutralization and installer transaction boundaries. Trivial statements are intentionally not paraphrased in comments; the comments record the reason or safety constraint behind the code.

14 KiB Raw Blame History