86 lines
5.2 KiB
Markdown
86 lines
5.2 KiB
Markdown
---
|
|
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. |