---
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.