MSI installer

A Windows Installer package that deploys SQL Server Health Monitor and registers it as a Windows service. Authored with WiX v5; the sources live in installer/ (Package.wxs + build.ps1).

Building the MSI

Prerequisites on the build machine:

  • .NET 9 SDK
  • WiX v5 CLI: dotnet tool install --global wix
  • WiX UI extension (for the setup wizard): wix extension add -g WixToolset.UI.wixext
cd installer
./build.ps1                                  # -> installer/SqlServerHealthMonitor-1.0.0.0.msi
./build.ps1 -Version 1.2.0.0 -Manufacturer "Contoso Ltd"
./build.ps1 -SelfContained                   # bundle the .NET runtime (larger MSI, no runtime prereq)

build.ps1 runs dotnet publish (win-x64, framework-dependent by default) into installer/publish, then wix build. The default build needs the ASP.NET Core 9 Runtime on the target machine; use -SelfContained to bundle it.

Bump -Version for every release. The UpgradeCode in Package.wxs is fixed and must never change — it's what lets a newer MSI upgrade an older install in place.

What it installs

  • Files to C:\Program Files\SQL Server Health Monitor\.
  • A Windows service SqlServerHealthMonitor ("SQL Server Health Monitor"), start type Automatic, running as LocalSystem.
  • The service is not started during install — a fresh install has no connection string yet and would fail the production startup guard. Configure first, then start.

Install-time configuration (port & connection string)

Interactive install: double-click the MSI to launch a wizard (Welcome → License → Install folder → Service configuration → Confirm → Finish). The Service configuration page has fields for the HTTPS port and the database connection string. Replace installer/license.rtf with your own EULA before shipping.

Unattended install: the same two settings are MSI properties. Two settings can be supplied as MSI properties at install time. The installer writes them as machine environment variables, which ASP.NET Core reads on top of appsettings.json — so you don't have to edit any file:

Property Sets env var Default
HTTPSPORT SecuritySettings__HttpsPort 8443
SQLCONNECTIONSTRING ConnectionStrings__DefaultConnection (unset — required before the service starts) 
msiexec /i SqlServerHealthMonitor-1.0.1.0.msi `
    HTTPSPORT=9443 `
    SQLCONNECTIONSTRING="Server=db;Database=SQLSpa;User Id=svc;Password=…;TrustServerCertificate=true" `
    /qn /norestart

The connection-string variable is only created when you pass a non-empty value, and both are removed again on uninstall. Security note: a machine environment variable is readable by local administrators and processes — for a SQL password prefer a domain service account with Integrated Security (no password in the string) over passing SQLCONNECTIONSTRING.

First-time setup

# 1. Configure the monitoring database connection (either edit the config...)
notepad "C:\Program Files\SQL Server Health Monitor\appsettings.json"
#    ...set ConnectionStrings:DefaultConnection

#    ...or supply it as a machine environment variable (preferred — no secrets on disk):
[Environment]::SetEnvironmentVariable("ConnectionStrings__DefaultConnection",
    "Server=db;Database=SQLSpa;User Id=svc;Password=…;TrustServerCertificate=true", "Machine")

# 2. (Recommended) run the service under a domain account for Integrated Security:
sc.exe config "SqlServerHealthMonitor" obj= "DOMAIN\monitor-svc" password= "…"

# 3. Start it
sc.exe start "SqlServerHealthMonitor"

It listens on https://localhost:8443 by default (self-signed cert generated on first run — see deployment.md for replacing it). The first-run admin bootstrap writes credentials to INITIAL_ADMIN_PASSWORD.txt in the install folder; see deployment.md → Initial admin account.

Silent install / uninstall

msiexec /i SqlServerHealthMonitor-1.0.0.0.msi /qn /norestart
msiexec /x SqlServerHealthMonitor-1.0.0.0.msi /qn          # uninstall

Upgrades

Run a newer-versioned MSI; the major-upgrade logic stops the service, replaces the files, and re-registers the service. appsettings.json is preserved (marked never-overwrite), so the operator's connection string survives. After upgrading, start the service again (upgrades don't auto-start it).

What is NOT removed on uninstall

  • The DataProtection keys (default %LOCALAPPDATA%\SqlServerHealthMonitor\… of the service account) — the framework key ring for auth cookies and the self-signed certificate. Keeping them only saves your users a forced re-login.
  • The monitoring database — it's external.
  • Operator edits to appsettings.json may remain. Remove the install folder manually if you want a clean slate.