init

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

@@ -0,0 +1,86 @@
+---
+source_files:
+  - DataPRO/Modules/InstallerCustomActions/MigrateConfiguration/ConfigurationMigration.cs
+generated_at: "2026-04-17T16:00:30.279115+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "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.