UserConfigMigrator 1.3.0

User configuration migrator

A helper utility for migrating user-scoped application settings between different versions of a .NET application.

Useful when:

• Application version upgrades should reuse settings from older versions.
• Application root namespace or assembly name has changed.
• Supports downgrades by allowing import of settings from future versions.

⚠️ Scope: This is a minimal utility tailored for internal use in .NET Framework (e.g., 4.8) desktop applications that store settings using SettingsBase and user.config.
It does not support roaming profiles, custom configuration files, or non-standard config structures.

Features

• Finds the most recent valid user.config file from previous application versions.
• Exports settings from a user.config file.
• Applies exported settings from a user.config file into the current application settings, skipping unknown fields.

📦 NuGet

Install via NuGet Package Manager:

Install-Package UserConfigMigrator

Or via .NET CLI:

dotnet add package UserConfigMigrator

Usage examples

Direct upgrading of user settings

UserConfigMigrator.UpgradeSettings(Properties.Settings.Default);

Direct upgrading of user settings with support for previous app versions

string assemblyName = Assembly.GetExecutingAssembly().GetName().Name;
string oldCompanyName = "oldCompanyName";

IReadOnlyCollection<UserConfigMigrator.AppInfo> previousAppInfos =
    new ReadOnlyCollection<UserConfigMigrator.AppInfo>(
        new List<UserConfigMigrator.AppInfo>()
        {
            new UserConfigMigrator.AppInfo(
                company: new UserConfigMigrator.Filename(oldCompanyName),
                assembly_name: new UserConfigMigrator.Filename(assemblyName))
        });

UserConfigMigrator.UpgradeSettings(Properties.Settings.Default, previous_app_infos: previousAppInfos);

Step-by-step upgrading of user settings

ConfigurationUserLevel userLevelConf = ConfigurationUserLevel.PerUserRoaming;

Version appVersion;
UserConfigMigrator.AppInfo appInfo =
    UserConfigMigrator.GetAppInfoFromCurrentUserConfig(out appVersion, userLevelConf);

string userConfigPath;
if (UserConfigMigrator.TryFindLatestUserConfig(appVersion, appInfo, out userConfigPath))
{
    IDictionary<string, object> exportedSettings =
        UserConfigMigrator.ExportSettings(userConfigPath, Properties.Settings.Default);

    UserConfigMigrator.ApplySettings(exportedSettings, Properties.Settings.Default);
}