DP44/docs/ai/DataPRO/Modules/InstallerCustomActions/MigrateConfiguration.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/InstallerCustomActions/MigrateConfiguration/ConfigurationMigration.cs	2026-04-17T16:00:30.279115+00:00	zai-org/GLM-5-FP8	1	f2a5a0c47cf8f162

ConfigurationMigration Module Documentation

1. Purpose

This module is an installer custom action executable that handles migration of configuration settings and license files from a previously installed version of DataPRO to a newly installed version. It runs during the installation process, locates the most recent prior installation, copies forward user-modified settings (preserving custom values while respecting new defaults), and migrates license files. Its role is to ensure continuity of user configuration across version upgrades.

---

2. Public Interface

ConfigurationMigration (static class)

• Visibility: internal static
• Namespace: MigrateConfiguration

Main(string[] args) (entry point)

• Visibility: private static
• Signature: void Main(string[] args)
• Behavior: Entry point for the custom action. Parses command-line arguments, creates an event log source if needed, orchestrates configuration migration, and displays results via MessageBox unless suppressed.
• Arguments (positional, by index):
  • args[0] - targetDir: Installation target directory
  • args[1] - productVersion: Version of DataPRO being installed (parsed as Version)
  • args[2] - noUI: Set to "TRUE" to suppress MessageBox output
  • args[3] - setupExeDir: Directory containing the setup executable

UpdateConfigurationIfPossible(string targetDir, Version installingVersion, string setupExeDir, out string result)

• Visibility: public static
• Signature: void UpdateConfigurationIfPossible(string targetDir, Version installingVersion, string setupExeDir, out string result)
• Behavior: Locates the most recent previously installed version using PreviousInstall.GetMostRecentlyInstalledSubKeyName, retrieves its path, and migrates the license file. Sets result to describe migration status.

---

3. Invariants

1. Version ordering: Migration only proceeds if PreviousInstall.GetMostRecentlyInstalledSubKeyName returns a non-empty subkey (i.e., a previous version exists that is lower than installingVersion).

2. Settings migration condition: A setting is migrated only if:

   • It exists in both old and new configuration files
   • Its value differs between old and new configurations
   • For DownloadFolder specifically: the old value must NOT equal StringResources.DataUpOneLevel (the previous default)

3. License file identification: A file is considered a valid DataPRO license if it contains both "<License>" and "<LicenseAttributes>" substrings.

4. License search depth: FindLicenseInPath searches up to 2 levels of subdirectories recursively.

5. Event log source: The module attempts to create an event log source named "DataPROInstaller" under log "DataPROInstallerLog" if it does not exist (creation failures are silently ignored).

---

4. Dependencies

This module depends on:

• MigrateConfiguration.Resources.StringResources - Localized string constants for settings names, paths, and messages
• Installer.Common.PreviousInstall - Provides GetMostRecentlyInstalledSubKeyName and GetMostRecentlyInstalledPath methods
• DTS.Common.Utilities.ConfigInitializationHelper - Provides GetNewSettings method
• DTS.Common.Utilities.SettingElementCollection - Collection type for configuration settings
• System.Configuration - ConfigurationManager, Configuration, ClientSettingsSection, SettingElement
• System.Windows.Forms - MessageBox for UI output
• System.IO - File and directory operations

What depends on this module:

• DataPRO installer (WiX or similar) as a custom action executable

---

5. Gotchas

1. Inconsistent event log source: In Main, the event log source is created as "DataPROInstaller", but in UpdateConfigurationIfPossible, the EventLog.Source is set to "MySource" which appears to be a bug or leftover debug code—the log entry is also commented out.

2. Extensive commented-out code: Large blocks of code in Main are commented out, including logic for modifying DownloadFolder, ImportArchiveFolder, and DTSPlugins settings. This may represent deprecated functionality or work-in-progress.

3. Silent exception handling: The event log source creation in Main uses an empty catch {} block, silently ignoring any failures (e.g., permission issues).

4. Hardcoded assumption about registry paths: GetOldSettings constructs the old config path by appending StringResources.RegistryDataPROExe to nextLowerPath, which assumes the previous installation follows a specific directory structure.

5. License priority: MigrateLicenseFile prioritizes finding a license in the installer directory (setupExeDir's parent) before falling back to the previous installation's license. If found in the installer, it copies that instead of migrating the old one.

6. No rollback mechanism: If migration partially succeeds then fails, there is no rollback of already-written changes to the new configuration file.