WildDragonLLC/dragon-iso
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 2 Packages Wiki Activity Actions
dragon-iso/docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md

7.5 KiB
Raw Blame History

Dragon-ISO Installer Design

Date: 2026-05-31
Status: Design Complete
Audience: End users downloading and installing Dragon-ISO

Overview

Update the existing WiX Toolset v5 MSI installer from TeamsISO branding to Dragon-ISO. The installer provides a simple, professional Windows installation experience for end users with minimal choices (Next → Install).

Key characteristics:

  • Per-machine installation to Program Files\Wild Dragon\Dragon-ISO\
  • Simple UI (no customization dialogs)
  • Start Menu and Desktop shortcuts
  • Professional Add/Remove Programs (ARP) metadata
  • Prerequisite detection for .NET 8 Desktop Runtime and NDI 6 Runtime (warn, don't block)
  • Version: 1.0.0.0

File and Naming Structure

Files to Rename

  • installer/TeamsISO.Installer.wixproj → installer/Dragon-ISO.Installer.wixproj
  • installer/Package.wxs → remains (generic name, no change needed)

Build Output

  • Current (TeamsISO): TeamsISO-Setup-1.0.0.0.msi
  • Updated (Dragon-ISO): Dragon-ISO-Setup-1.0.0.0.msi

Asset References

  • Icon: References Dragon-ISO.ico (already exists in src/Dragon-ISO.App/Assets/)
  • App directory: src/Dragon-ISO.App/ (updated from src/TeamsISO.App/)
  • Publish output: publish/Dragon-ISO/ (updated from publish/TeamsISO/)

Branding Updates (in Package.wxs)

Product Metadata

  • Package Name: "Dragon-ISO" (from "TeamsISO")
  • Manufacturer: "Wild Dragon LLC" (unchanged)
  • UpgradeCode: Keep existing GUID (allows upgrades from TeamsISO to Dragon-ISO)
  • Version: 1.0.0.0

Summary Information

  • Description: "Dragon-ISO — per-participant NDI ISO controller for Microsoft Teams. Splits each Teams participant into a normalized NDI source for vMix / OBS / Ross / hardware switchers."
  • Keywords: "Dragon-ISO, NDI, Microsoft Teams, ISO recording, broadcast, live production, vMix, OBS, switcher, Wild Dragon"

Add/Remove Programs (ARP) Metadata

  • Help Link: https://forge.wilddragon.net/zgaetano/dragon-iso
  • About Link: https://wilddragon.net
  • Support Contact: Wild Dragon LLC — support@wilddragon.net
  • Comments: "Dragon-ISO turns Microsoft Teams' raw NDI broadcast into clean, normalized, per-participant NDI sources for ingestion by a live-production switcher (vMix, OBS, Ross, hardware capture). Each participant gets an individually-addressable source with configurable framerate, resolution, aspect mode, and audio routing."

Registry Keys

  • Location: Software\Wild Dragon\Dragon-ISO (from Software\Wild Dragon\TeamsISO)
  • Used for: Start Menu shortcut tracking, Desktop shortcut tracking, Install path storage

Shortcuts

  • Start Menu: Wild Dragon → Dragon-ISO
  • Desktop: Dragon-ISO shortcut
  • Target: [INSTALLFOLDER]Dragon-ISO.exe
  • Icon: Dragon-ISO icon from assets
  • Description: "Per-Participant NDI ISO Controller for Microsoft Teams"

Installation Layout

Directory Structure

Program Files\Wild Dragon\Dragon-ISO\
  ├── Dragon-ISO.exe                    (main executable)
  ├── DragonISO.dll                     (core assembly)
  ├── Assets\                           (icons, fonts, resources)
  ├── Themes\                           (XAML theme files)
  ├── [.NET dependencies]               (runtime assets, supporting DLLs)
  └── [all other published files]

Shortcuts Created

  • Start Menu: %ProgramMenu%\Wild Dragon\Dragon-ISO.lnk
  • Desktop: %UserProfile%\Desktop\Dragon-ISO.lnk
  • Both use stable GUIDs for reliable uninstall tracking

Uninstall Behavior

  • Standard Windows uninstall via Add/Remove Programs
  • Removes all application files and shortcuts
  • Removes registry entries under Software\Wild Dragon\Dragon-ISO
  • Preserves: User config files in %APPDATA%\Dragon-ISO\ (for future upgrades)

Add/Remove Programs Entry

Users see:

  • Name: Dragon-ISO
  • Version: 1.0.0.0
  • Publisher: Wild Dragon LLC
  • Help: Link to Forge repository
  • About: Link to wilddragon.net
  • Contact: support@wilddragon.net
  • Icon: Dragon-ISO app icon

Build Process

Prerequisites

  • .NET 8 SDK
  • WiX Toolset v5 (dotnet workload install wix)

Build Steps

  1. Publish the application:

    dotnet publish src/Dragon-ISO.App/Dragon-ISO.App.csproj `
  -c Release -r win-x64 `
  -o publish/Dragon-ISO

  2. Build the MSI:

    dotnet build installer/Dragon-ISO.Installer.wixproj -c Release

  3. Output:

    • Location: installer/bin/Release/Dragon-ISO-Setup-1.0.0.0.msi
    • Ready for end-user distribution

Version Management

  • MSI version is driven by the app's .csproj <Version> tag
  • Update version once, builds auto-propagate to the MSI filename
  • UpgradeCode remains constant across versions (enables upgrade detection)

CI/CD Integration

  • Update existing .forgejo/workflows/ to use new project paths
  • Scripts already handle publish → build → sign → release
  • Just update path references and output filename

Prerequisites & Runtime Detection

.NET 8 Desktop Runtime

  • Check: Registry lookup for installed .NET 8 Desktop Runtime
  • If missing: Display warning dialog with link to download
  • Install behavior: Continue installation anyway (user can install .NET 8 later)
  • At app launch: App checks again; shows MessageBox with install link if still missing

NDI 6 Runtime

  • Check: Environment variable NDI_RUNTIME_DIR_V6
  • If missing: Display warning dialog
  • Install behavior: Continue installation anyway
  • At app launch: App checks again; shows MessageBox with install link if still missing

Rationale: Allows staged deployment where IT can install Dragon-ISO first, then NDI/runtime later. End users get clear guidance at both install-time and app-launch time.

Major Upgrade Behavior

The installer detects when a newer version is already installed and:

  1. Prevents downgrade: Blocks installation of older versions with a clear error message
  2. In-place upgrade: Newer installs replace older ones seamlessly
  3. Config preservation: User configuration in %APPDATA%\Dragon-ISO\ is preserved
  4. UpgradeCode: Constant GUID ensures upgrade detection works (TeamsISO → Dragon-ISO, and future versions)

Error Handling

Installation Failures

  • WiX standard rollback behavior: if installation fails, all changes are undone
  • Clear error messages for common issues (insufficient permissions, disk space, etc.)

Shortcut Creation

  • If shortcut creation fails, installation continues (non-blocking)
  • User can manually create shortcuts from Program Files\Wild Dragon\Dragon-ISO\Dragon-ISO.exe

Registry Operations

  • If registry write fails, installation continues (non-blocking)
  • ARP entry may be incomplete but app is still functional

Testing Checklist

  • MSI builds successfully with new branding
  • Install to clean system works end-to-end
  • Shortcuts appear in Start Menu and on Desktop
  • ARP entry shows correct metadata
  • Uninstall removes all files and shortcuts
  • Upgrade from TeamsISO to Dragon-ISO works
  • .NET 8 runtime detection shows warning if missing
  • NDI runtime detection shows warning if missing
  • App launches after installation
  • Help/About links in ARP entry work

Future Enhancements (Out of Scope)

  • Code signing for published MSI
  • Automatic update checks via Squirrel.Windows
  • Per-user installation option
  • Silent/unattended install mode (for enterprise deployment)